Setting up deployment scripts for your servers, but not sure how to attack ssh key management? There are four common methods: SSH agent forwarding, HTTPS with OAuth tokens, deploy keys, and machine users. This guide will help you decide what strategy is best for you.

SSH agent forwarding

In many cases, especially early on, SSH agent forwarding is the quickest and simplest method to use. Agent forwarding uses the SSH keys already set up on your local development machine when you SSH in to your server and run git commands.

Pros

  • You do not have to generate any new keys
  • There is no key management, your users will have the same permissions on the server that they do locally
  • No keys are stored on the server, so in case of a server compromise you don't need to hunt down and remove the compromised keys

Cons

  • Users must SSH in to deploy, automated deploy processes can't be used
  • SSH agent can be troublesome to run for Windows users

Setup

Setting up agent forwarding requires only two setups:

  1. Turn on agent forwarding locally, see this guide
  2. Set your deploy script to use agent forwarding if it has a setting

HTTPS cloning with OAuth tokens

If you don't want to use SSH keys, you can use HTTPS with OAuth tokens.

Pros

  • Anyone with access to the server has access to deploy the repository
  • Users don't have to change their local SSH settings
  • Multiple tokens are not needed, one token per server is adequate
  • A compromised token can be revoked at any time, it is essentially a throw-away password
  • Generating new tokens can be easily scripted using the OAuth API

Cons

  • The token has full read/write access to all repositories that the account it is attached to has write access to
  • Tokens are essentially passwords, and must be protected the same way

Setup

See this guide.

Deploy keys

A deploy key is an SSH key that is stored on the server and grants access to a single repository on GitHub. This key is attached directly to the repository instead of to a user account.

Pros

  • Anyone with access to the server has access to deploy the repository
  • Users don't have to change their local SSH settings

Cons

  • Deploy keys only grant access to a single repository, more complex projects may have many repositories to pull to the same server
  • The key has full read/write access to the repository
  • Deploy keys are usually not protected by a passphrase, making the key easily accessible if the server is compromised

Setup

Setting up a deploy key is almost exactly the same as setting up a normal key, you just attach it to a repository instead of a user.

  1. Run the ssh-keygen procedure outlined here on your server.
  2. Instead of going to your account settings, go to the target repository's settings page. Settings tab
  3. Go to "Deploy Keys" and click "Add deploy key". Paste the public key in and submit. Add Deploy Key button

Machine users

In the case where you have multiple repositories a server will need access to, the simplest solution is to attach the key to a user account. Since this account won't be used by a human, it's called a machine user. You would treat this user the same way you would a human though, attach the key to the machine user account as if it were a normal account. Grant the account collaborator or team access to the repositories it needs access to.

Pros

  • Anyone with access to the server has access to deploy the repository
  • Users don't have to change their local SSH settings
  • Multiple keys are not needed, one per server is adequate
  • Organizations can give read-only access to their machine users

Cons

  • The key has full read/write access to the repository if the repository belongs to a User account
  • Machine user keys, like deploy keys, are usually not protected by a passphrase

Setup

The setup process is basically the same as a new user:

  1. Follow this guide on your server and attach the public key to the machine user account.
  2. Grant that account access to the repositories it will need access to by adding it as a collaborator or team member if you have an organization.

Tip: Our terms of service do mention that 'Accounts registered by “bots” or other automated methods are not permitted.' and 'One person or legal entity may not maintain more than one free account.' Don't fear, we won't send rabid lawyers out to hunt you down if you make machine users for your server deploy scripts. Machine users are kosher with us.