The Buildkite Agent is an open-source toolkit written in Golang for securely running build jobs on any device or network
Switch branches/tags
Clone or download
lox Merge pull request #840 from buildkite/bundle-update-for-gems
Bundle update for ruby dependencies
Latest commit c4434cb Oct 18, 2018
Failed to load latest commit information.
.buildkite Revert "Use `docker login` for publishing" Oct 8, 2018
agent fix: agent panics on arm Oct 9, 2018
api Add a tags-from-host config Jul 6, 2018
bootstrap Ensure plugin directory exists, otherwise lock thrashes Oct 8, 2018
clicommand Ensure pipeline parser maintains map order in output Sep 20, 2018
cliconfig Add a list normalization for --tags and --experiment May 18, 2018
env Use testify/assert vs testify/require Jan 18, 2018
experiments Experiments is now a global generic package Nov 23, 2016
logger Formatted all the things using goimports - /cc @wolfeidau Jun 10, 2015
mime Don't set Content-Encoding on s3 upload Apr 17, 2018
packaging Point BUILDKITE_AGENT_CONFIG at /buildkite/buildkite-agent.cfg for Do… Oct 10, 2018
pool Moved pool and glob out of the buildkite package. Jun 2, 2015
process Cancellation on Windows: Pass `/T` to `taskkill` Jul 13, 2018
proctitle Added linux,ppc64le as valid build target. Apr 4, 2018
retry Apply `govendor fmt +l` to current source tree Jun 7, 2017
scripts Add a virtual provides to the RPM package Apr 19, 2018
signalwatcher Added graceful shutdown. Fixes #176 Sep 20, 2015
stdin Use os.ModeCharDevice instead of os.ModeNamedPipe May 1, 2018
system Moved the OS version dump gear into a new package. Sep 20, 2015
templates Updating launchd to only restart on error Aug 1, 2018
test/fixtures/artifacts Move docker integration test to new location Sep 17, 2017
utils Renamed normalization `command` to `commandpath` and cleanups Apr 3, 2018
vendor Update AWS SDK to latest Sep 4, 2018
yamltojson Ensure pipeline parser maintains map order in output Sep 20, 2018
.dockerignore Add dockerfile and docker-compose for windows Jan 16, 2018
.editorconfig Add .editorconfig and set indent_size to 4 Aug 22, 2017
.gitignore Rename docker scripts to better reflect what they do May 18, 2018 Bump version and changelog for 3.5.2 Oct 9, 2018
Dockerfile Top level docker files are for development Mar 22, 2018
Dockerfile-github-release Bump our Docker image base to alpine v3.7 Apr 27, 2018
Dockerfile-windows Top level docker files are for development Mar 22, 2018 Clarify that experiments will change May 24, 2018
Gemfile Bundle update May 10, 2016
Gemfile.lock Bundle update all the things Oct 18, 2018
LICENSE.txt Remove DEPENDENCIES.txt, it's out of date anyway May 18, 2018 edit Buildkite Agent license info so that GitHub recognizes it Apr 21, 2018
Vagrantfile Use a box that is published on Nov 12, 2017 Add a windows vagrant VM and dockerfile Nov 12, 2017
docker-compose.release.yml Add a dockerfile for local development Aug 23, 2017 Add a windows-dev docker-compose for development Jan 19, 2018 Set builds path in Jan 22, 2018
docker-compose.yml Pass BUILDKITE_JOB_ID to Jan 21, 2018
install.ps1 Fixed typo in line 5 - Missing 'd' in buildkite Apr 10, 2018 Update path from bash installer to v3 docs Mar 21, 2018
main.go Bump, closes #576 Nov 12, 2017

Buildkite Agent Build status

Note: This is the development branch of the buildkite-agent, and may not contain files or code in the current stable release. To see code or submit PRs for stable agent versions, please use the corresponding maintenance branch: 3.0.x.

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

Full documentation is available at

$ buildkite-agent --help

  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
  pipeline	Make changes to the pipeline of the currently running build
  bootstrap	Run a Buildkite job locally
  help, h	Shows a list of commands or help for one command

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


The agents page on Buildkite has personalised instructions for installing the agent with Ubuntu (via apt), Debian (via apt), macOS (via homebrew), Windows and Linux. You can also run the agent via Docker.


To start an agent all you need is your agent token, which you can find on your Agents page within Buildkite.

buildkite-agent start --token


These instructions assume you are running a recent macOS, but could easily be adapted to Linux and Windows.

With Docker

docker-compose run agent bash
root@d854f845511a:/go/src/ go run main.go start --token xxx --debug

Without Docker

# Make sure you have go installed.
brew install go

# Setup your GOPATH
export GOPATH="$HOME/go"
export PATH="$HOME/go/bin:$PATH"

# Checkout the code
go get
cd "$HOME/go/src/"

To test the commands locally:

go run main.go start --debug --token "abc123"

Windows via Vagrant

This requires either Virtualbox (free) or VMWare Fusion + Vagrant VMWare Fusion plugin (paid).

It assumes that you have Docker for Mac or similar installed. The following commands are run on your local machine. Expect things to take a long time, the vagrant box is 10GB and the docker base image is 3.4GB.

vagrant up
eval $(docker-machine env windows-2016)
docker-compose -f run agent cmd
C:\gopath\src\\buildkite\agent> go run main.go start --token xxx --debug

Dependency management

We're using govendor to manage our Go dependencies. Install it with:

go get

If you introduce a new package, just add the import to your source file and run:

govendor fetch +missing

Or explicitly fetch it with a version using:

govendor fetch


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request


Many thanks to our fine contributors! @adill, @airhorns, @alexjurkiewicz, @bendrucker, @bradfeehan, @byroot, @cab, @caiofbpa, @colinrymer, @cysp, @daveoflynn, @daveoxley, @daveslutzkin, @davidk-zenefits, @DazWorrall, @dch, @deoxxa, @dgoodlad, @donpinkster, @essen, @grosskur, @jgavris, @joelmoss, @jules2689, @julianwa, @kouky, @marius92mc, @mirdhyn, @mousavian, @nikyoudale, @pda, @rprieto, @samritchie, @silarsis, @skevy, @stefanmb, @tekacs, @theojulienne, @tommeier, @underscorediscovery, and @wolfeidau.


Copyright (c) 2014-2017 Buildkite Pty Ltd. See LICENSE and DEPENDENCIES for details.