The Buildkite Agent

The buildkite agent is a small, reliable and cross-platform build runner that makes it easy to run automated builds on your own infrastructure. Its main responsibilities are polling buildkite.com for work, running build jobs, reporting back the status code and output log of the job, and uploading the job's artifacts.

How it Works

The agent works by polling Buildkite’s agent API over HTTPS. There is no need to forward ports or provide incoming firewall access, and the agents can be run across any number of machines and networks.

Diagram showing agent to agent API communication

The agent starts by registering itself with Buildkite, and once registered it’s placed into your organization’s agents pool. The agent periodically polls Buildkite looking for new work, waiting to accept an available job.

After accepting a build job the agent will execute the command, streaming back the build script’s output and then posting the final exit status.

Whilst the job is running you can use the buildkite-agent meta-data command to set and get build-wide meta-data, and buildkite-agent artifact for fetching and retrieving binary build-wide artifacts. These two commands allow you to have completely isolated build jobs (similar to a 12 factor web application) but have easy access to shared state and data storage across any number of machines and networks.

Installation

The agent can be easily installed onto almost any system large or tiny, and we have installers to make it easy to run and manage your agents. See the installation instructions to get started.

Usage

$ buildkite-agent --help
Usage:

  buildkite-agent <command> [arguments...]

Available commands are:

  start     Starts a Buildkite agent
  artifact  Upload/download artifacts from Buildkite jobs
  meta-data Get/set data from Buildkite jobs
  help, h   Shows a list of commands or help for one command

Use "buildkite-agent <command> --help" for more information about a command.

To start an agent you’ll need your organization’s agent token from the Agents page of your Buildkite dashboard. You pass the token to the agent via an environment variable or command line flag, and it will register itself with Buildkite and wait to accept jobs.

Configuration

The agent has a standard configuration file format on all systems to set meta-data, priority, etc. See the configuration documentation for more details.

Customising with Hooks

The agent’s behaviour can be customized using hooks, which are just shell scripts that exist on your build machines or in each pipeline’s code repository. Hooks can be used to set up secrets as well as overriding default behavior. See the hooks documentation for full details.

Signal Handling

When a build job is canceled the agent will send the build job process a SIGTERM signal to allow it to gracefully exit. If the process does not exit within 10 seconds it will be forcefully terminated with a SIGKILL signal.