agent

README

Buildkite Agent

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 buildkite.com 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.com/docs/agent

$ 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
  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.

Installing

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.

Starting

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

Development

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/github.com/buildkite/agent# 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 github.com/buildkite/agent
cd "$HOME/go/src/github.com/buildkite/agent"

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 docker-compose.windows.yml run agent cmd
C:\gopath\src\github.com\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 github.com/kardianos/govendor

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 github.com/buildkite/go-buildkite@v2.0.0

Contributing

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

Contributors

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

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