Installing Buildkite Agent on Ubuntu

Installation

First, add our signed apt repository. The default version of the agent is stable, but you can get the beta version by using unstable instead of stable in the following command, or the agent built from the main branch of the repository by using experimental instead of stable.

Start by downloading the Buildkite PGP key to a directory that is only writable by root (create the directory before running the following command if it doesn't already exist):

curl -fsSL https://keys.openpgp.org/vks/v1/by-fingerprint/32A37959C2FA5C3C99EFBC32A79206696452D198 | sudo gpg --dearmor -o /usr/share/keyrings/buildkite-agent-archive-keyring.gpg

Then add the signed source to your list of apt sources:

echo "deb [signed-by=/usr/share/keyrings/buildkite-agent-archive-keyring.gpg] https://apt.buildkite.com/buildkite-agent stable main" | sudo tee /etc/apt/sources.list.d/buildkite-agent.list

And install the Buildkite agent:

sudo apt-get update && sudo apt-get install -y buildkite-agent

Configure your agent token:

sudo sed -i "s/xxx/INSERT-YOUR-AGENT-TOKEN-HERE/g" /etc/buildkite-agent/buildkite-agent.cfg

And then start the agent:

sudo systemctl enable buildkite-agent && sudo systemctl start buildkite-agent

You can view the logs at:

journalctl -f -u buildkite-agent

Updating keys installed using apt-key

If you've previously installed keys using apt-key, move the Buildkite agent key from /etc/apt/trusted.gpg or /etc/apt/trusted.gpg.d/ to /usr/share/keyrings/buildkite-agent-archive-keyring.gpg, making sure that both that file and directory are only writable by root.

Update your Buildkite agent entries in /etc/apt/sources.list.d/buildkite-agent.list to:

deb [signed-by=/usr/share/keyrings/buildkite-agent-archive-keyring.gpg] https://apt.buildkite.com/buildkite-agent stable main

SSH key configuration

SSH keys should be copied to (or generated into) /var/lib/buildkite-agent/.ssh/. For example, to generate a new private key which you can add to your source code host:

$ sudo su buildkite-agent
$ mkdir -p ~/.ssh && cd ~/.ssh
$ ssh-keygen -t rsa -b 4096 -C "build@myorg.com"

See the Agent SSH keys documentation for more details.

File locations

• Configuration: /etc/buildkite-agent/buildkite-agent.cfg
• Agent Hooks: /etc/buildkite-agent/hooks/
• Builds: /var/lib/buildkite-agent/builds/
• Logs, depending on your system:
  • journalctl -f -u buildkite-agent (systemd)
  • /var/log/upstart/buildkite-agent.log (upstart)
  • /var/log/buildkite-agent.log (older systems)

• Agent user home: /var/lib/buildkite-agent/
• SSH keys: /var/lib/buildkite-agent/.ssh/

Configuration

The configuration file is located at /etc/buildkite-agent/buildkite-agent.cfg. See the configuration documentation for an explanation of each configuration setting.

Running multiple agents

You can run as many parallel agent workers on the one machine as you wish with the spawn configuration setting, or by passing the --spawn flag.

# Start 5 workers. Each one independently fetches and executes jobs.
spawn=5

Upgrading

The Buildkite Agent can be upgraded like any other system package:

sudo apt-get update && apt-get upgrade

Alternative keyservers

The PGP key used to sign the Buildkite Agent package is also hosted on the following keyservers. Use these keyservers if the one in the installation instructions is down.

• keyserver.ubuntu.com

  curl -fsSL 'https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x32A37959C2FA5C3C99EFBC32A79206696452D198&exact=on&options=mr' | sudo gpg --dearmor -o /usr/share/keyrings/buildkite-agent-archive-keyring.gpg
  

• pgp.mit.edu

  curl -fsSL 'https://pgp.mit.edu/pks/lookup?op=get&search=0x32A37959C2FA5C3C99EFBC32A79206696452D198&exact=on&options=mr' | sudo gpg --dearmor -o /usr/share/keyrings/buildkite-agent-archive-keyring.gpg