Learn different ways to manage SSH keys on your servers when you automate deployment scripts and which way is best for you.
In this article
You can manage SSH keys on your servers when automating deployment scripts using SSH agent forwarding, HTTPS with OAuth tokens, deploy keys, or machine users.
In many cases, especially in the beginning of a project, SSH agent forwarding is the quickest and simplest method to use. Agent forwarding uses the same SSH keys that your local development computer uses.
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
You can launch projects from a repository on GitHub.com 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 account, and the private part of the key remains on your server. For more information, see Delivering deployments.
For enhanced security and fine-grained control over repository access and permissions, we recommend using a GitHub App instead. See Deciding when to build a GitHub App.
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.
Deploy keys are credentials that don't have an expiry date.
Deploy keys aren't linked directly to organization membership. If the user who created the deploy key is removed from the repository, the deploy key will still be active as it isn't tied to the specific user, but rather to the repository.
If your organization is owned by an enterprise, and your enterprise owner has restricted the use of deploy keys in repositories, then you cannot override the policy in your organization to create a deploy key. For more information, see Enforcing repository management policies in your enterprise.
Run the ssh-keygen procedure on your server, and remember where you save the generated public and private rsa key pair.
On GitHub, navigate to the main page of the repository.
Under your repository name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then click Settings.
Screenshot of a repository header showing the tabs. The "Settings" tab is highlighted by a dark orange outline.
In the sidebar, click Deploy Keys.
Click Add deploy key.
In the "Title" field, provide a title.
In the "Key" field, paste your public key.
Select Allow write access if you want this key to have write access to the repository. A deploy key with write access lets a deployment push to the repository.
If you use multiple repositories on one server, you will need to generate a dedicated key pair for each one. You can't reuse a deploy key for multiple repositories.
In the server's SSH configuration file (usually ~/.ssh/config), add an alias entry for each repository. For example:
Hostname github.com - Configures the hostname to use with the alias.
IdentityFile=/home/user/.ssh/repo-0_deploy_key - Assigns a private key to the alias.
You can then use the hostname's alias to interact with the repository using SSH, which will use the unique deploy key assigned to that alias. For example:
If your server needs to access repositories across one or more organizations, you can use a GitHub App to define the access you need, and then generate tightly-scoped, installation access tokens from that GitHub App. The installation access tokens can be scoped to single or multiple repositories, and can have fine-grained permissions. For example, you can generate a token with read-only access to a repository's contents.
Since GitHub Apps are a first class actor on GitHub, the installation access tokens are decoupled from any GitHub user, which makes them comparable to "service tokens". Additionally, installation access tokens have dedicated rate limits that scale with the size of the organizations that they act upon. For more information, see Rate limits for GitHub Apps.
Determine if your GitHub App should be public or private. If your GitHub App will only act on repositories within your organization, you likely want it private.
Determine the permissions your GitHub App requires, such as read-only access to repository contents.
Create your GitHub App via your organization's settings page. For more information, see Creating a GitHub App.
Note your GitHub App id.
Generate and download your GitHub App's private key, and store this safely. For more information, see Generating a private key.
Install your GitHub App on the repositories it needs to act upon, optionally you may install the GitHub App on all repositories in your organization.
Identify the installation_id that represents the connection between your GitHub App and the organization repositories it can access. Each GitHub App and organization pair have at most a single installation_id. You can identify this installation_id via Get an organization installation for the authenticated app. This requires authenticating as a GitHub App using a JWT, for more information see Authenticating as a GitHub App.
If your server needs to access multiple repositories, you can create a new account on GitHub.com and attach an SSH key that will be used exclusively for automation. Since this account on GitHub.com 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), as an outside collaborator on an organization repository (granting read, write, or admin access), or to a team with access to the repositories it needs to automate (granting the permissions of the team).
Accounts registered by "bots" or other automated methods are not permitted.
This means that you cannot automate the creation of accounts. But if you want to create a single machine user for automating tasks such as deploy scripts in your project or organization, that is totally cool.
Give the machine user account access to the repositories you want to automate. You can do this by adding the account as a collaborator, as an outside collaborator, or to a team in an organization.