buildkite-agent bootstrap

bootstrap is the command the agent executes when it comes to run a job on your agent.

Running the bootstrap


buildkite-agent bootstrap [options...]


The bootstrap command executes a buildkite job locally.

Generally the bootstrap command is run as a sub-process of the buildkite-agent to execute a given job sent from, but you can also invoke the bootstrap manually.

Execution is broken down into phases. By default, the bootstrap runs a plugin phase which sets up any plugins specified, then a checkout phase which pulls down your code and then a command phase that executes the specified command in the created environment.

You can run only specific phases with the --phases flag.

The bootstrap is also responsible for executing hooks around the phases. See for more details.


$ eval $(curl -s -H "Authorization: Bearer xxx" \
    "[org]/pipelines/[proj]/builds/[build]/jobs/[job]/env.txt" | sed 's/^/export /')
$ buildkite-agent bootstrap --build-path builds


  • --command value - The command to run [$BUILDKITE_COMMAND]
  • --job value - The ID of the job being run [$BUILDKITE_JOB_ID]
  • --repository value - The repository to clone and run the job from [$BUILDKITE_REPO]
  • --commit value - The commit to checkout in the repository [$BUILDKITE_COMMIT]
  • --branch value - The branch the commit is in [$BUILDKITE_BRANCH]
  • --tag value - The tag the commit [$BUILDKITE_TAG]
  • --refspec value - Optional refspec to override git fetch [$BUILDKITE_REFSPEC]
  • --plugins value - The plugins for the job [$BUILDKITE_PLUGINS]
  • --pullrequest value - The number/id of the pull request this commit belonged to [$BUILDKITE_PULL_REQUEST]
  • --agent value - The name of the agent running the job [$BUILDKITE_AGENT_NAME]
  • --queue value - The name of the queue the agent belongs to, if tagged [$BUILDKITE_AGENT_META_DATA_QUEUE]
  • --organization value - The slug of the organization that the job is a part of [$BUILDKITE_ORGANIZATION_SLUG]
  • --pipeline value - The slug of the pipeline that the job is a part of [$BUILDKITE_PIPELINE_SLUG]
  • --pipeline-provider value - The id of the SCM provider that the repository is hosted on [$BUILDKITE_PIPELINE_PROVIDER]
  • --artifact-upload-paths value - Paths to files to automatically upload at the end of a job [$BUILDKITE_ARTIFACT_PATHS]
  • --artifact-upload-destination value - A custom location to upload artifact paths to (e.g. s3://my-custom-bucket/and/prefix) [$BUILDKITE_ARTIFACT_UPLOAD_DESTINATION]
  • --clean-checkout - Whether or not the bootstrap should remove the existing repository before running the command [$BUILDKITE_CLEAN_CHECKOUT]
  • --git-clone-flags value - Flags to pass to "git clone" command (default: "-v") [$BUILDKITE_GIT_CLONE_FLAGS]
  • --git-clone-mirror-flags value - Flags to pass to "git clone" command when mirroring (default: "-v") [$BUILDKITE_GIT_CLONE_MIRROR_FLAGS]
  • --git-clean-flags value - Flags to pass to "git clean" command (default: "-ffxdq") [$BUILDKITE_GIT_CLEAN_FLAGS]
  • --git-fetch-flags value - Flags to pass to "git fetch" command [$BUILDKITE_GIT_FETCH_FLAGS]
  • --git-mirrors-path value - Path to where mirrors of git repositories are stored [$BUILDKITE_GIT_MIRRORS_PATH]
  • --git-mirrors-lock-timeout value - Seconds to lock a git mirror during clone, should exceed your longest checkout (default: 300) [$BUILDKITE_GIT_MIRRORS_LOCK_TIMEOUT]
  • --bin-path value - Directory where the buildkite-agent binary lives [$BUILDKITE_BIN_PATH]
  • --build-path value - Directory where builds will be created [$BUILDKITE_BUILD_PATH]
  • --hooks-path value - Directory where the hook scripts are found [$BUILDKITE_HOOKS_PATH]
  • --plugins-path value - Directory where the plugins are saved to [$BUILDKITE_PLUGINS_PATH]
  • --command-eval - Allow running of arbitrary commands [$BUILDKITE_COMMAND_EVAL]
  • --plugins-enabled - Allow plugins to be run [$BUILDKITE_PLUGINS_ENABLED]
  • --plugin-validation - Validate plugin configuration [$BUILDKITE_PLUGIN_VALIDATION]
  • --local-hooks-enabled - Allow local hooks to be run [$BUILDKITE_LOCAL_HOOKS_ENABLED]
  • --ssh-keyscan - Automatically run ssh-keyscan before checkout [$BUILDKITE_SSH_KEYSCAN]
  • --git-submodules - Enable git submodules [$BUILDKITE_GIT_SUBMODULES]
  • --pty - Run jobs within a pseudo terminal [$BUILDKITE_PTY]
  • --shell value - The shell to use to interpret build commands (default: "/bin/bash -e -c") [$BUILDKITE_SHELL]
  • --phases value - The specific phases to execute. The order they're defined is irrelevant. [$BUILDKITE_BOOTSTRAP_PHASES]
  • --cancel-signal value - The signal to use for cancellation (default: "SIGTERM") [$BUILDKITE_CANCEL_SIGNAL]
  • --redacted-vars value - Pattern of environment variable names containing sensitive values [$BUILDKITE_REDACTED_VARS]
  • --tracing-backend value - The name of the tracing backend to use. [$BUILDKITE_TRACING_BACKEND]
  • --debug - Enable debug mode [$BUILDKITE_AGENT_DEBUG]
  • --experiment value - Enable experimental features within the buildkite-agent [$BUILDKITE_AGENT_EXPERIMENT]
  • --profile value - Enable a profiling mode, either cpu, memory, mutex or block [$BUILDKITE_AGENT_PROFILE]