Upgrading to Buildkite Agent v2
This page references the out-of-date Buildkite Agent v2.
For docs referencing the Buildkite Agent v3, see the latest version of this document.
The Buildkite Agent has changed a lot in v2 but upgrade process is straight forward. We'll cover what’s changed and how to upgrade to new agents.
On this page:
- The default install location has changed from
~/.buildkite-agent(although each installer may install in different locations).
- Agents can be configured with a config file.
- Agents register themselves with a organization-wide token, you no longer need to create them via the web.
- Agents now have hooks support and there should be no reason to customise the
- There is built-in support for containerizing builds with Docker and Docker Compose.
- There are installer packages available for most systems.
- Agents now have meta-data.
- Agent meta-data can be imported from EC2 tags with
- Build steps select agents using key/value patterns rather than explicit agent selection.
- Windows support
- Ability to specify commands such as
makein your build pipelines instead of a path to a script
- Automatic ssh fingerprint verification
- You can set a priority for the agent.
*priority 5will have a job assigned to it over an agent with
- The agent now works better under flakey internet connections by retrying certain API calls
- A new command
buildkite-agent artifact shasumthat allows you to download the shasum of a previously uploaded artifact
Meta-data and agent targetting
No longer do you select individual agents to run build steps but instead you provide an agent query pattern that's used to select the correct agent.
See the meta-data documentation for more details.
If you customized your
bootstrap.sh file you should now switch to using hooks to achieve the same results. See our hooks documentation for details on the hooks available.
Upgrading each pipeline
We recommend upgrading one pipeline at a time to the new agents. This is because you'll need to update your build pipelines to use agent targeting, rather than selecting the individual agents.
To update the agent on a build machine we recommend stopping the agent, removing all the files, and following the install instructions for your platform.
Once you have the new agent running, update your pipeline’s build pipeline steps to target the new agent, and trigger a build.
Upgrading a pre-1.0 agent
All agents prior to v2 (including the old Buildbox Ruby agents) are deprecated and will stop executing new jobs on December 12th 2015.
To upgrade you simply install the a new 2.0 agent using the standard installation methods and migrate each pipeline to target the new agents.
To make installation easy we’ve created packages for each of the major operating systems.
Upgrading a 1.0 beta agent
To upgrade a Ubuntu / Debian 1.0 beta agent:
/etc/apt/sources.list.d/buildkite-agent.listand replace the word
sudo apt-get update && sudo apt-get upgrade -y buildkite-agent
To upgrade a Red Hat / CentOS 1.0 beta agent:
/etc/yum.repos.d/buildkite-agent.repoand replace the word
sudo yum clean expire-cache && sudo yum update buildkite-agent
Note that when you install the agent on a new machine using the debian / rpm packages the agent will be installed and run as the unprivileged
buildkite-agent user, unlike some beta builds which ran as root.
If you didn't install the agent using the above packages then simply update the agent like you did originally and you should get the latest stable version.