Installing Buildkite Agent on Debian

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 can be installed on Debian versions 7.x and 8.x using our signed apt repository.

Installation

Firstly, ensure your list of packages is up to date:

sudo apt-get update

Debian doesn't always have sudo available, so you can run these commands as root and omit the sudo, or install the sudo package as root first.

Next, ensure you have the apt-transport-https package installed for the HTTPS package repository, and the dirmngr package installed for adding the signing key:

sudo apt-get install -y apt-transport-https dirmngr

Download 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):

wget -O- https://keys.openpgp.org/vks/v1/by-fingerprint/32A37959C2FA5C3C99EFBC32A79206696452D198 | sudo tee /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

Then 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:

# For Debian 8.x (systemd)
sudo systemctl enable buildkite-agent && sudo systemctl start buildkite-agent

# For Debian 7.x (using upstart)
sudo service buildkite-agent start

# For Debian 7.x (using sysvinit)
sudo /etc/init.d/buildkite-agent start

You can view the logs at:

# For Debian 8.x (systemd)
sudo journalctl -f -u buildkite-agent

# For Debian 7.x (using upstart)
sudo tail -f /var/log/upstart/buildkite-agent.log

# For Debian 7.x (using sysvinit)
sudo tail -f /var/log/buildkite-agent.log

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 agents on the one machine as you wish by duplicating the systemd/upstart service configuration file, for example:

For Debian 8.x (systemd)

# Disable the default unit
sudo systemctl stop buildkite-agent && sudo systemctl disable buildkite-agent

# Create a systemd template
sudo cp /lib/systemd/system/buildkite-agent.service /etc/systemd/system/buildkite-agent@.service

# Now, as many times as you like
sudo systemctl enable buildkite-agent@1 && sudo systemctl start buildkite-agent@1
sudo systemctl enable buildkite-agent@2 && sudo systemctl start buildkite-agent@2

# Follow them all
sudo journalctl -f -u "buildkite-agent@*"

# Or one-by-one
sudo journalctl -f -u buildkite-agent@2

For Debian 7.x (using upstart)

sudo cp /etc/init/buildkite-agent.conf /etc/init/buildkite-agent-2.conf
sudo service buildkite-agent-2 start
sudo tail -f /var/log/upstart/buildkite-agent-2.log

Upgrading

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

sudo apt-get update && apt-get upgrade