English
No results found.

Explore by product

Developers
  • Get started
  • Account and profile
  • Authentication
  • Repositories
  • GitHub
  • Enterprise administrators
  • Billing and payments
  • Organizations
  • Code security
  • GitHub Issues
  • GitHub Actions
  • GitHub Codespaces
  • GitHub Packages
  • Search on GitHub
  • Developers
  • REST API
  • GraphQL API
  • GitHub CLI
  • GitHub Discussions
  • GitHub Sponsors
  • Building communities
  • GitHub Pages
  • Education
  • GitHub Desktop
  • Atom
  • Electron
  • CodeQL
  • npm
    • English
  • English
  • 简体中文 (Simplified Chinese)
  • 日本語 (Japanese)
  • Español (Spanish)
  • Português do Brasil (Portuguese)

    • This version of GitHub Enterprise was discontinued on 2021-09-23. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise. For help with the upgrade, contact GitHub Enterprise support.

    Article version

    In this article

    Using SSH agent forwarding

    To simplify deploying to a server, you can set up SSH agent forwarding to securely use local SSH keys.

    SSH agent forwarding can be used to make deploying to a server simple. It allows you to use your local SSH keys instead of leaving keys (without passphrases!) sitting on your server.

    If you've already set up an SSH key to interact with GitHub Enterprise Server, you're probably familiar with ssh-agent. It's a program that runs in the background and keeps your key loaded into memory, so that you don't need to enter your passphrase every time you need to use the key. The nifty thing is, you can choose to let servers access your local ssh-agent as if they were already running on the server. This is sort of like asking a friend to enter their password so that you can use their computer.

    Check out Steve Friedl's Tech Tips guide for a more detailed explanation of SSH agent forwarding.

    Setting up SSH agent forwarding

    Ensure that your own SSH key is set up and working. You can use our guide on generating SSH keys if you've not done this yet.

    You can test that your local key works by entering ssh -T git@hostname in the terminal:

    $ ssh -T git@hostname
# Attempt to SSH in to github
> Hi username! You've successfully authenticated, but GitHub does not provide
> shell access.

    We're off to a great start. Let's set up SSH to allow agent forwarding to your server.

    1. Using your favorite text editor, open up the file at ~/.ssh/config. If this file doesn't exist, you can create it by entering touch ~/.ssh/config in the terminal.

    2. Enter the following text into the file, replacing example.com with your server's domain name or IP:

      Host example.com
  ForwardAgent yes

    Warning: You may be tempted to use a wildcard like Host * to just apply this setting to all SSH connections. That's not really a good idea, as you'd be sharing your local SSH keys with every server you SSH into. They won't have direct access to the keys, but they will be able to use them as you while the connection is established. You should only add servers you trust and that you intend to use with agent forwarding.

    Testing SSH agent forwarding

    To test that agent forwarding is working with your server, you can SSH into your server and run ssh -T git@hostname once more. If all is well, you'll get back the same prompt as you did locally.

    If you're unsure if your local key is being used, you can also inspect the SSH_AUTH_SOCK variable on your server:

    $ echo "$SSH_AUTH_SOCK"
# Print out the SSH_AUTH_SOCK variable
> /tmp/ssh-4hNGMk8AZX/agent.79453

    If the variable is not set, it means that agent forwarding is not working:

    $ echo "$SSH_AUTH_SOCK"
# Print out the SSH_AUTH_SOCK variable
> [No output]
$ ssh -T git@hostname
# Try to SSH to github
> Permission denied (publickey).

    Troubleshooting SSH agent forwarding

    Here are some things to look out for when troubleshooting SSH agent forwarding.

    You must be using an SSH URL to check out code

    SSH forwarding only works with SSH URLs, not HTTP(s) URLs. Check the .git/config file on your server and ensure the URL is an SSH-style URL like below:

    [remote "origin"]
  url = git@hostname:yourAccount/yourProject.git
  fetch = +refs/heads/*:refs/remotes/origin/*