The Buildkite Agent’s
start command is used to manually start an agent and register it with Buildkite.
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]
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:
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
Once you've started agents with metadata you can target them in the build pipeline using agent query rules.
Here's an example of targetting agents that are running with the meta-data value
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:
To do this from an uploaded pipeline.yml you would do:
steps: - command: "script.sh" agents: postgres: '*'
Partial wildcard matching (e.g.
postgres=*1.9) is not yet supported.
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.