buildkite-agent start

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's start command is used to manually start an agent and register it with Buildkite.

Starting an agent

Usage:

   buildkite-agent start [arguments...]

Description:

   When a job is ready to run it will call the "bootstrap-script"
   and pass it all the environment variables required for the job to run.
   This script is responsible for checking out the code, and running the
   actual build script defined in the project.

   The agent will run any jobs within a PTY (pseudo terminal) if available.

Example:

   $ buildkite-agent start --token xxx

Options:

   --config                         Path to a configuration file [$BUILDKITE_AGENT_CONFIG]
   --token                      Your account agent token [$BUILDKITE_AGENT_TOKEN]
   --name                       The name of the agent [$BUILDKITE_AGENT_NAME]
   --priority                       The priority of the agent (higher priorities are assigned work first) [$BUILDKITE_AGENT_PRIORITY]
   --meta-data '--meta-data option --meta-data option'  Meta-data for the agent (default is "queue=default") [$BUILDKITE_AGENT_META_DATA]
   --meta-data-ec2                  Include the host's EC2 meta-data (instance-id, instance-type, and ami-id) as meta-data [$BUILDKITE_AGENT_META_DATA_EC2]
   --meta-data-ec2-tags                 Include the host's EC2 tags as meta-data [$BUILDKITE_AGENT_META_DATA_EC2_TAGS]
   --git-clean-flags '-fdq'             Change flags used during Git clean [$BUILDKITE_GIT_CLEAN_FLAGS]
   --git-clone-flags '-v'               Change flags used during Git clone [$BUILDKITE_GIT_CLONE_FLAGS]
   --bootstrap-script                   Path to the bootstrap script [$BUILDKITE_BOOTSTRAP_SCRIPT_PATH]
   --build-path                     Path to where the builds will run from [$BUILDKITE_BUILD_PATH]
   --hooks-path                     Directory where the hook scripts are found [$BUILDKITE_HOOKS_PATH]
   --no-pty                     Do not run jobs within a pseudo terminal [$BUILDKITE_NO_PTY]
   --no-automatic-ssh-fingerprint-verification      Don't automatically verify SSH fingerprints [$BUILDKITE_NO_AUTOMATIC_SSH_FINGERPRINT_VERIFICATION]
   --no-command-eval                    Don't allow this agent to run arbitrary console commands [$BUILDKITE_NO_COMMAND_EVAL]
   --endpoint 'https://agent.buildkite.com/v3'      The Agent API endpoint [$BUILDKITE_AGENT_ENDPOINT]
   --no-color                       Don't show colors in logging [$BUILDKITE_AGENT_NO_COLOR]
   --debug                      Enable debug mode [$BUILDKITE_AGENT_DEBUG]
   --debug-http                     Enable HTTP debug mode, which dumps all request and response bodies to the log [$BUILDKITE_AGENT_DEBUG_HTTP]

Setting metadata

Each agent has meta-data tags which can be used to group and target the agents in your build pipelines. This way you're free to dynamically scale your agents and target them based on their capabilities rather than maintaining a static list.

To set an agent's meta-data you can set it in the configuration file:

meta-data="docker=true,ruby2=true"

or with the --meta-data command line flag:

buildkite-agent start --meta-data "docker=true" --meta-data "ruby2=true"

or with the BUILDKITE_AGENT_META_DATA an environment variable:

env BUILDKITE_AGENT_META_DATA="docker=true,ruby2=true" buildkite-agent start

Agent Targeting

Once you've started agents with metadata you can target them in the build pipeline using agent query rules.

Here's an example of targeting agents that are running with the meta-data value postgres of 1.9.4:

Agent Selector showing a single match

To do this from uploaded pipeline.yml you would do:

steps:
  - command: "script.sh"
    agents:
      postgres: "1.9.4"

You can also match for any agent with a postgres meta-data by omitting the value after the = sign, or by using *, for example:

Agent Selector showing a single match

To do this from an uploaded pipeline.yml you would do:

steps:
  - command: "script.sh"
    agents:
      postgres: '*'

Partial wildcard matching (for example, postgres=1.9* or postgres=*1.9) is not yet supported.

The queue tag

The queue meta-data tag works differently from other tags, and can be used for isolating jobs and agents. See the agent queues documentation for more information about using queues.