Installing Buildkite Agent on Ubuntu

The Buildkite Agent can be installed on on Ubuntu versions 12.04 and above using our signed apt repository.

Installation

First, add our signed apt repository:

sudo sh -c 'echo deb https://apt.buildkite.com/buildkite-agent stable main > /etc/apt/sources.list.d/buildkite-agent.list'
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 32A37959C2FA5C3C99EFBC32A79206696452D198

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

# Ubuntu 15.04+ (systemd)
sudo systemctl enable buildkite-agent && sudo systemctl start buildkite-agent

# Older Ubuntu (upstart)
sudo service buildkite-agent start

You can view the logs at:

# Ubuntu 15.04+ (systemd)
journalctl -f -u buildkite-agent

# Older Ubuntu (upstart)
tail -f /var/log/upstart/buildkite-agent.log

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
  • 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 upstart service configuration file, for example:

# For Ubuntu 15.04+ (using 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 older Ubuntu (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