Running Buildkite Agent with Docker
You can run the Buildkite Agent inside a Docker container using the
buildkite/agent docker image on Docker Hub.
Running each build in it’s own container
These instructions cover how to run the agent using Docker. If you want to learn how to isolate each build using Docker and any of our standard Linux-based installers read the Docker-Based Builds guide.
On this page:
Running via Docker
Start an agent with the official image based on Alpine Linux:
docker run -e BUILDKITE_AGENT_TOKEN="INSERT-YOUR-AGENT-TOKEN-HERE" buildkite/agent
A much larger Ubuntu-based image is also available:
docker run -e BUILDKITE_AGENT_TOKEN="INSERT-YOUR-AGENT-TOKEN-HERE" buildkite/agent:ubuntu
Running on startup
By default Docker starts containers on restart so there's no need for upstart or similar. Simply start your container with
-d to daemonize it and it will be restarted on system boot with the same environment variables and arguments.
Running different versions
The default tag (i.e.
buildkite/agent:latest) will always point to the latest stable release.
We recommend you use
buildkite/agent:3 for new setups to get at least version 3.0 of the agent
If you want to use an exact version of Buildkite Agent you can use the corresponding tag, such as
You can see all the available versions on https://hub.docker.com/r/buildkite/agent/tags/.
Configuring the agent
Most agent configuration settings can be set with environment variables. Setting sensitive data, (such as the agent token) via environment variables or command line arguments is not recommended as they are exposed in commands such as
In addition to environment variables, you can copy or mount a configuration file to
/etc/buildkite-agent/buildkite-agent.cfg, for example:
docker run -it \ -v "$HOME/buildkite-agent.cfg:/etc/buildkite-agent/buildkite-agent.cfg:ro" \ buildkite/agent:3
You can add custom agent hooks by mounting or copying them into the
/buildkite/hooks directory (and ensuring they are executable).
For example, this is how you'd mount the hooks directory using a read-only host volume:
docker run -it \ -v "$HOME/buildkite-hooks:/buildkite/hooks:ro" \ buildkite/agent:3
Alternatively, if you create your own image based off
buildkite/agent, you can copy your hooks into the correct location:
FROM buildkite/agent ADD hooks /buildkite/hooks/
Exposing build secrets into the container
There are many approaches to exposing secrets to Docker containers. In addition, many Docker platforms have their own methods for exposing secrets. If you’re running your own Docker containers, we recommend using a read-only host volume.
The following example mounts a directory containing secrets on the host machine (
$HOME/buildkite-secrets) into the container as a read-only data volume at
docker run -it \ -v "$HOME/buildkite-secrets:/buildkite-secrets:ro" \ buildkite/agent:3
You can then use an
environment agent hook to expose those secrets via environment variables, or to configure tools such as
Authenticating private git repositories
#!/bin/bash set -euo pipefail git config --global credential.helper "store --file=/buildkite-secrets/git-credentials" # You can export other secrets here too # export FOO=bar
To configure a private SSH key located at
/buildkite-secrets/id_rsa_buildkite_git you could use the following
environment agent hook mounted to
#!/bin/bash set -euo pipefail eval "$(ssh-agent -s)" ssh-add -k /buildkite-secrets/id_rsa_buildkite_git # You can export other secrets here too # export FOO=bar
Other options for configuring Git and SSH include:
ssh-agenton the host machine and mounting the ssh-agent socket into the containers. See the Buildkite Agent SSH keys documentation for examples on using ssh-agent.
- The least-secure approach: the built-in docker-ssh-env-config support allows you to pass in keys via environment variables.
Invoking Docker from within a build
To invoke Docker from within builds you'll need to mount the Docker socket into the container:
docker run -it \ -v /var/run/docker.sock:/var/run/docker.sock \ buildkite/agent:3
Note that this gives builds the same access to the host system as docker has, which is generally root.
The entrypoint uses
tini to correctly pass signals to, and kill, sub-processes. Instead of redefining
ENTRYPOINT we recommend you copy executable scripts into
/docker-entrypoint.d/. All executable scripts should not contain any file extension, and will be executed in alphanumeric order.