GitHub 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.

The Buildkite Agent clones your source code directly from GitHub or GitHub Enterprise. The easiest way to provide it with access is by creating a "Buildkite Agent" machine user in your organization, and adding it to a team that has access to the relevant repositories.

If you're running a build agent on a local development machine which already has access to GitHub then you can skip this setup and start running builds.

Method 1: Machine user

Creating a machine user is the simplest way to create a single SSH key which provides access to your organization's repositories.

The easiest way to do this is by creating a “Buildkite Agent” machine user in your organization, and adding it to a team that has access to the relevant repositories.

To setup a GitHub machine user:

On your agent machine, generate a key as per the agent SSH keys documentation
Sign up to GitHub as a new user (using a valid email address), and add the SSH key to the user's settings
Sign back into GitHub as an organization admin, create a new team, then add the new user and any required repositories to the team

Method 2: Deploy keys

An alternative method of providing access to your repositories is to use deploy keys. The advantage of deploy keys is they can provide read-only access to your source code, but the disadvantage is that you'll have to configure ssh on your build agents to handle multiple keys.

To setup GitHub deploy keys with the Buildkite Agent, you'll need to do the following for each repository:

On your agent machine, generate a key as per the agent SSH keys documentation
In GitHub, copy the key into the repository's "Deploy keys" settings