Buildkite Agent SSH keys

This page references the out-of-date Buildkite Agent v2.

For docs referencing the Buildkite Agent v3, see the latest version of this document.

If your agent needs to clone your repositories using git and SSH, you'll need to configure your agent with a valid SSH key.

Finding your SSH key directory

When the Buildkite Agent runs any git operations, SSH will look for keys in ~/.ssh under whichever user the agent runs as. Each platform's agent installation documentation specifies the exact location of this directory.

Debugging SSH key issues

To help debug SSH issues you can enable verbose logging by editing the ~/.ssh/config file and adding the following settings:

Host *
  LogLevel DEBUG3

Creating a single SSH key

The following shows an example of creating a new “machine user” SSH key for an agent:

$ sudo su buildkite-agent # or whichever user your agent runs as
$ mkdir -p ~/.ssh && cd ~/.ssh
$ ssh-keygen -t rsa -b 4096 -C "dev+build@myorg.com"
Generating public/private rsa key pair.
Enter file in which to save the key (/var/lib/buildkite-agent/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /var/lib/buildkite-agent/.ssh/id_rsa.
Your public key has been saved in /var/lib/buildkite-agent/.ssh/id_rsa.pub.
The key fingerprint is:
4b:6f:7b:5f:8e:f7:5b:c1:fa:e3:dd:9a:8e:a8:e8:33 dev@org.com
The key's randomart image is:
+---[RSA 4096]----+
|                 |
|                 |
|                 |
|              .  |
|        S      o |
|       . o    . .|
|        . o  .  o|
|      E. . o...*=|
|     .oo..o..oB*O|
+-----------------+
$ ls
id_rsa  id_rsa.pub
$ cat id_rsa.pub
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDELESv1QGfoZ2hECJr.......Yho9hDPoNefDbcdZM4NdKWTVmyNGQo6YTzw== dev+build@myorg.com

You'd then add this key to the user's settings on GitHub, Bitbucket, GitLab, etc.

Creating multiple SSH keys

If you need to use multiple SSH keys for different pipelines, we support a special repository hostname format which you can use with your ~/.ssh/config.

To use a different key for a given pipeline, first change the repository hostname in your Buildkite pipeline settings from server.com to server.com-mypipeline, and then add an entry to the SSH config file on your agent machine for the host server.com-mypipeline and specify your custom SSH key.

For example, if you had a pipeline repository URL of git@github.com:org/pipeline-1.git you would change it in your Buildkite repository settings to git@github.com-pipeline-1:org/pipeline-1.git and create the following SSH config file:

Host github.com-pipeline-1
  HostName github.com
  IdentityFile /var/lib/buildkite-agent/.ssh/id_rsa.pipeline-1

The following example shows how to create the corresponding pipeline-specific SSH key:

$ sudo su buildkite-agent # or whichever user your agent runs as
$ cd ~/.ssh
$ ssh-keygen -t rsa -b 4096 -C "dev+build-pipeline-1@myorg.com"
Generating public/private rsa key pair.
Enter file in which to save the key (/var/lib/buildkite-agent/.ssh/id_rsa): id_rsa.pipeline-1
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in id_rsa.pipeline-1.
Your public key has been saved in id_rsa.pipeline-1.pub.
The key fingerprint is:
e4:60:69:a3:a0:63:bb:27:e6:ff:53:d3:4a:06:7f:e4 dev@org.com
The key's randomart image is:
+---[RSA 4096]----+
|                 |
|       .         |
|  .   * .        |
| . . = = .       |
|o.  . o S        |
|...    * E       |
| .    + +        |
| o.. . .         |
|oo+....          |
+-----------------+
$ ls
id_rsa.pipeline-1  id_rsa.pipeline-1.pub

Using multiple keys with ssh-agent

If you need to use multiple keys, or want to use keys with pass-phrases, an alternative to the above hostname method is to use ssh-agent.

After running ssh-agent and adding the keys, you'll need to ensure the SSH_AUTH_SOCK environment variable is exported in your environment agent hook.

For example, if you set up ssh-agent like so:

$ sudo su buildkite-agent
$ ssh-agent -a ~/.ssh/ssh-agent.sock
$ export SSH_AUTH_SOCK=/var/lib/buildkite-agent/.ssh/ssh-agent.sock
$ ssh-add ~/.ssh/id_rsa-pipeline-1
Identity added: /var/lib/buildkite-agent/.ssh/id_rsa-pipeline-1
$ ssh-add ~/.ssh/id_rsa-pipeline-2
Identity added: /var/lib/buildkite-agent/.ssh/id_rsa-pipeline-2

Then you will need the following environment agent hook so that the build's git operations use the ssh-agent socket:

#!/bin/bash

set -eu

export SSH_AUTH_SOCK="/var/lib/buildkite-agent/.ssh/ssh-agent.sock"