Originally this repository contained the source for the docker images for Buildkite Agent, but they are now built as part of that project. See https://github.com/buildkite/agent/tree/master/packaging/docker.
docker pull buildkite/agent:3.0
docker run buildkite/agent:3.0 --helpThe default tag (i.e. buildkite/agent and buildkite/agent:latest) will always point to the latest stable release (currently 3.x).
We recommend you use buildkite/agent:3 for new setups.
If you want to use an exact version of Buildkite Agent you can use the corresponding tag, such as buildkite/agent:3.0.1.
You can see all the available versions on https://hub.docker.com/r/buildkite/agent/tags/.
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 docker inspect.
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:3You 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:3Alternatively, 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/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 /buildkite-secrets:
docker run -it \
-v "$HOME/buildkite-secrets:/buildkite-secrets:ro" \
buildkite/agent:3You can then use an environment agent hook to expose those secrets via environment variables, or to configure tools such as git or ssh.
To configure a git-credentials file located at /buildkite-secrets/git-credentials, you could use the following environment agent hook mounted to /buildkite/hooks/environment:
#!/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=barTo configure a private SSH key located at /buildkite-secrets/id_rsa_buildkite_git you could use the following environment agent hook mounted to /buildkite/hooks/environment:
#!/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=barOther options for configuring Git and SSH include:
ssh-agent on 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.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:3Note 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.
Come and say hi in the #docker channel in the Buildkite Chat slack room!