Managing Deploy Keys

Learn different ways to manage SSH keys on your servers when you automate deployment scripts.

You can manage SSH keys on your servers when automating deployment scripts using:

• SSH Agent Forwarding
• HTTPS with OAuth tokens
• deploy keys
• machine users

• SSH Agent Forwarding

  Agent forwarding uses the same SSH keys that your local development computer uses.

  • In many cases, especially in the beginning of a project, SSH agent forwarding is the quickest and simplest method to use.
  • Pros
    • You do not have to generate or keep track of any new keys.
    • There is no key management; users have the same permissions on the server that they do locally.
    • No keys are stored on the server, so in case the server is compromised, 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 forwarding can be troublesome to run for Windows users.
  • Setup
    1. Turn on agent forwarding locally.
    2. Set your deploy scripts to use agent forwarding. For example, on a bash script, enabling agent forwarding would look something like this:

       ssh -A serverA 'bash -s' < deploy.sh
       

• 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 can deploy the repository.
    • Users don’t have to change their local SSH settings.
    • Multiple tokens (one for each user) are not needed; one token per server is enough.
    • A token can be revoked at any time, turning it essentially into a one-use password.
    • Generating new tokens can be easily scripted using the OAuth API.
  • Cons
    • You must make sure that you configure your token with the correct access scopes.
    • Tokens are essentially passwords, and must be protected the same way.
  • Setup

    Guide on Git automation with tokens

• Deploy Keys

  You can launch projects from a GitHub repository to your server by using a deploy key, which is an SSH key that grants access to a single repository.

  • GitHub attaches the public part of the key directly to your repository instead of a personal user account, and the private part of the key remains on your server.
  • Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository.
  • Pros
    • Anyone with access to the repository and server has the ability to deploy the project.
    • Users don’t have to change their local SSH settings.
    • Deploy keys are read-only by default, but you can give them write access when adding them to a repository.
  • Cons
    • Deploy keys only grant access to a single repository. More complex projects may have many repositories to pull to the same server.
    • Deploy keys are usually not protected by a passphrase, making the key easily accessible if the server is compromised.
  • Setup

    Setup guide

• Machine Users

  If your server needs to access multiple repositories, you can create a new GitHub account and attach an SSH key that will be used exclusively for automation. Since this GitHub account won’t be used by a human, it’s called a "machine user"

  You can add the machine user as:

  • a collaborator on a personal repository (granting read and write access)
  • an outside collaborator on an organization repository (granting read, write, or admin access)
  • to a team with access to the repositories it needs to automate (granting the permissions of the team).
  • Pros
    • Anyone with access to the repository and server has the ability to deploy the project.
    • No (human) users need to change their local SSH settings.
    • Multiple keys are not needed; one per server is adequate.
  • Cons
    • Only organizations can restrict machine users to read-only access. Personal repositories always grant collaborators read/write access.
    • Machine user keys, like deploy keys, are usually not protected by a passphrase.
  • Setup

    Setup guide