Installing Buildkite Agent on Debian
The Buildkite Agent is supported on Debian versions 8 and above 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
Now you can 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
.
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):
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 apt sources list:
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:
sudo 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.
Which user the agent runs as
On Debian, the Buildkite agent runs as user buildkite-agent
.
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:
# 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
Upgrading
The Buildkite Agent can be upgraded like any other system package:
sudo apt-get update && apt-get upgrade