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.
On this page:
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.
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 access to shared state and data storage across any number of machines and networks.
You can install the agent on a wide variety of platforms, see the installation instructions for a full list and for information on how to get started.
$ buildkite-agent --help Usage: buildkite-agent [command] [arguments...] Available commands are: start Starts a Buildkite agent annotate Annotate the build page within the Buildkite UI with text from within a Buildkite job artifact Upload/download artifacts from Buildkite jobs meta-data Get/set data from Buildkite jobs pipeline Make changes to the pipeline of the currently running build bootstrap Run a Buildkite job locally help 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.
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 behavior can be customized using hooks, which are 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.
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 the 10s grace period it will be forcefully terminated with a
SIGKILL signal. If you require a longer grace period, it can be customized using the cancel-grace-period agent configuration option.
The agent also accepts the following two signals directly:
SIGTERM- Instructs the agent to gracefully disconnect, after completing any job that it may be running.
SIGQUIT- Instructs the agent to forcefully disconnect, cancelling any job that it may be running.
The agent reports its activity to Buildkite using exit codes. The most common exit codes and their descriptions can be found in the table below.
|0||The job exited with a status of 0 (success)|
|1||The job exited with a status of 1 (most common error status)|
|128 + signal number||The job was terminated by a signal (see note below)|
|255||The agent was gracefully terminated|
|-1||Buildkite lost contact with the agent or it stopped reporting to us|
Jobs terminated by signals
When a job is terminated by a signal, the exit code will be set to 128 + the signal number. For more information about how shells manage commands terminated by signals, see the Wiki page on Exit Signals.
Exit codes for common signals:
|130||2||SIGINT||Terminal interrupt signal|
|137||9||SIGKILL||Kill (cannot be caught or ignored)|
|139||11||SIGSEGV||Segmentation fault; Invalid memory reference|
|141||13||SIGPIPE||Write on a pipe with no one to read it|
|143||15||SIGTERM||Termination signal (graceful)|