buildkite-agent bootstrap

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

Running the bootstrap

Usage

buildkite-agent bootstrap [options...]

Description

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 buildkite.com, 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 https://buildkite.com/docs/agent/hooks for more details.

Example

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

Options

`--command string` #	The command to run Environment variable: `$BUILDKITE_COMMAND`
`--job string` #	The ID of the job being run Environment variable: `$BUILDKITE_JOB_ID`
`--repository string` #	The repository to clone and run the job from Environment variable: `$BUILDKITE_REPO`
`--commit string` #	The commit to checkout in the repository Environment variable: `$BUILDKITE_COMMIT`
`--branch string` #	The branch the commit is in Environment variable: `$BUILDKITE_BRANCH`
`--tag string` #	The tag the commit Environment variable: `$BUILDKITE_TAG`
`--refspec string` #	Optional refspec to override git fetch Environment variable: `$BUILDKITE_REFSPEC`
`--plugins string` #	The plugins for the job Environment variable: `$BUILDKITE_PLUGINS`
`--secrets string` #	Secrets to be loaded into the job environment Environment variable: `$BUILDKITE_SECRETS_CONFIG`
`--pullrequest string` #	The number/id of the pull request this commit belonged to Environment variable: `$BUILDKITE_PULL_REQUEST`
`--pull-request-head-commit string` #	The expected head commit for a pull request build Environment variable: `$BUILDKITE_PULL_REQUEST_HEAD_COMMIT`
`--pull-request-using-merge-refspec` #	Whether the agent should attempt to checkout the pull request commit using the merge refspec. This feature is in private preview and requires backend enablement—contact support to enable (default: false) Environment variable: `$BUILDKITE_PULL_REQUEST_USING_MERGE_REFSPEC`
`--agent string` #	The name of the agent running the job Environment variable: `$BUILDKITE_AGENT_NAME`
`--queue string` #	The name of the queue the agent belongs to, if tagged Environment variable: `$BUILDKITE_AGENT_META_DATA_QUEUE`
`--organization string` #	The slug of the organization that the job is a part of Environment variable: `$BUILDKITE_ORGANIZATION_SLUG`
`--pipeline string` #	The slug of the pipeline that the job is a part of Environment variable: `$BUILDKITE_PIPELINE_SLUG`
`--pipeline-provider string` #	The id of the SCM provider that the repository is hosted on Environment variable: `$BUILDKITE_PIPELINE_PROVIDER`
`--artifact-upload-paths string` #	Paths to files to automatically upload at the end of a job Environment variable: `$BUILDKITE_ARTIFACT_PATHS`
`--artifact-upload-destination string` #	A custom location to upload artifact paths to (for example, s3://my-custom-bucket/and/prefix) Environment variable: `$BUILDKITE_ARTIFACT_UPLOAD_DESTINATION`
`--clean-checkout` #	Whether or not the bootstrap should remove the existing repository before running the command (default: false) Environment variable: `$BUILDKITE_CLEAN_CHECKOUT`
`--skip-checkout` #	Skip the git checkout phase entirely Environment variable: `$BUILDKITE_SKIP_CHECKOUT`
`--checkout-override-mode string` #	Controls which sources may override the agent's checkout settings; one of [strict from-job none]. `strict` makes the agent authoritative against pipeline/step env, secrets, hooks, plugins, and the Job API. `from-job` (default) lets hooks, plugins, and the Job API set checkout vars, blocks secrets, and keeps the agent's checkout flags authoritative over pipeline/step env; pipeline/step env may still set the checkout timeout, submodules, skip-checkout, and skip-fetch-existing-commits toggles that the agent leaves unset, matching earlier agent behavior, and may set the sparse-checkout paths and mode outright. `none` additionally lets pipeline/step env and secrets set them. All mirror configuration and submodule clone config stay agent-authoritative in every mode. The checkout SSH key and Git LFS toggle are not governed by this flag and stay job-settable in every mode. Disabling command-eval forces this to `strict`. (default: "from-job") Environment variable: `$BUILDKITE_CHECKOUT_OVERRIDE_MODE`
`--git-checkout-flags string` #	Flags to pass to "git checkout" command (default: "-f") Environment variable: `$BUILDKITE_GIT_CHECKOUT_FLAGS`
`--git-clone-flags string` #	Flags to pass to "git clone" command (default: "-v") Environment variable: `$BUILDKITE_GIT_CLONE_FLAGS`
`--git-clone-mirror-flags string` #	Flags to pass to "git clone" command when mirroring (default: "-v") Environment variable: `$BUILDKITE_GIT_CLONE_MIRROR_FLAGS`
`--git-clean-flags string` #	Flags to pass to "git clean" command (default: "-ffxdq") Environment variable: `$BUILDKITE_GIT_CLEAN_FLAGS`
`--git-commit-verification string` #	Verify that the commit being built exists on the specified branch; one of strict or off (default: "strict") Environment variable: `$BUILDKITE_GIT_COMMIT_VERIFICATION`
`--git-fetch-flags string` #	Flags to pass to "git fetch" command (default: "-v --prune") Environment variable: `$BUILDKITE_GIT_FETCH_FLAGS`
`--git-sparse-checkout-paths string` #	Comma-separated list of paths for git sparse checkout. When set, only the listed paths are materialized in the working tree. Paths are interpreted according to --git-sparse-checkout-mode. Environment variable: `$BUILDKITE_GIT_SPARSE_CHECKOUT_PATHS`
`--git-sparse-checkout-mode string` #	Changes how the sparse checkout paths are interpreted; available modes are [cone no-cone]. `cone` treats each path as a directory to include, which is git's default and enables faster pattern matching, but it accepts only directory names. `no-cone` treats each path as a gitignore-style pattern, which allows globs and exclusions such as `!/docs/`, and requires git >= 2.35. Git LFS objects are not scoped to the sparse paths in `no-cone` mode. (default: "cone") Environment variable: `$BUILDKITE_GIT_SPARSE_CHECKOUT_MODE`
`--git-ssh-key string` #	SSH private key to use for git checkout Environment variable: `$BUILDKITE_GIT_SSH_KEY`
`--git-remote-mirror-url string` #	Backend-provided remote Git mirror used as an optional checkout source Environment variable: `$BUILDKITE_GIT_REMOTE_MIRROR_URL`
`--git-mirrors-path string` #	Path to where mirrors of git repositories are stored Environment variable: `$BUILDKITE_GIT_MIRRORS_PATH`
`--git-mirror-checkout-mode string` #	Changes how clones of a mirror are made; available modes are [dissociate reference]. In `dissociate` mode, clones from a mirror uses the git clone `--dissociate` flag, which copies underlying objects from the mirror, making the clone robust to changes in the mirror such as garbage collection, at the expense of additional disk usage and setup time. `reference` mode does not pass `--dissociate`, which causes the clone to directly use objects from the mirror, which is more fragile and can cause the clone to break under entirely normal operation of the mirror, but is slightly faster to clone and uses less disk space. (default: "reference") Environment variable: `$BUILDKITE_GIT_MIRROR_CHECKOUT_MODE`
`--git-mirrors-lock-timeout int` #	Seconds to lock a git mirror during clone, should exceed your longest checkout (default: 300) Environment variable: `$BUILDKITE_GIT_MIRRORS_LOCK_TIMEOUT`
`--git-mirrors-skip-update` #	Skip updating the Git mirror (default: false) Environment variable: `$BUILDKITE_GIT_MIRRORS_SKIP_UPDATE`
`--git-mirrors-lfs-cache` #	Cache Git LFS objects in the Git mirror when Git LFS is enabled for the checkout. The job's LFS objects are fetched into the mirror while its update lock is held, and each checkout reuses them instead of downloading from the LFS server again. Opt-in because it grows the mirror on disk without pruning, extends the time the mirror lock is held, and may not be faster than downloading from the LFS server when the mirror is on a slow or shared network volume. Requires --git-mirrors-path (default: false) Environment variable: `$BUILDKITE_GIT_MIRRORS_LFS_CACHE`
`--git-submodule-clone-config string` #	Comma separated key=value git config pairs applied before git submodule clone commands such as `update --init`. If the config is needed to be applied to all git commands, supply it in a global git config file for the system that the agent runs in instead Environment variable: `$BUILDKITE_GIT_SUBMODULE_CLONE_CONFIG`
`--git-checkout-timeout int` #	Seconds to allow for each git checkout attempt before it is killed and retried (0 means no timeout) (default: 0) Environment variable: `$BUILDKITE_GIT_CHECKOUT_TIMEOUT`
`--git-skip-fetch-existing-commits` #	Skip git fetch if the commit already exists in the local git directory (default: false) Environment variable: `$BUILDKITE_GIT_SKIP_FETCH_EXISTING_COMMITS`
`--git-fetch-base-branch string` #	Also fetch the base branch during checkout, so every command in the job can diff against its current tip; one of [strict optimistic off]. `optimistic` warns and carries on when the fetch fails, `strict` fails the job, and `off` (default) skips the fetch. A transient failure is retried briefly under `optimistic` and on the same budget as the job's own fetch under `strict`; a base branch the remote does not have fails without retrying. The base branch is the first non-empty value of {$BUILDKITE_PULL_REQUEST_BASE_BRANCH, $BUILDKITE_PIPELINE_DEFAULT_BRANCH}; nothing is fetched when it is the branch being built, and under `strict` a job with neither set fails. `strict` also rejects a $BUILDKITE_GIT_FETCH_FLAGS that asks for a fetch writing no ref (--dry-run, --prefetch, --negotiate-only), which git reports as success (default: "off") Environment variable: `$BUILDKITE_GIT_FETCH_BASE_BRANCH`
`--checkout-attempts int` #	Number of checkout attempts (including the initial attempt). Failed attempts are retried with exponential backoff (factor of 2, starting at 1s: 1s, 2s, 4s, ...) (default: 6) Environment variable: `$BUILDKITE_CHECKOUT_ATTEMPTS`
`--bin-path string` #	Directory where the buildkite-agent binary lives Environment variable: `$BUILDKITE_BIN_PATH`
`--build-path string` #	Path to where the builds will run from Environment variable: `$BUILDKITE_BUILD_PATH`
`--hooks-path string` #	Directory where the hook scripts are found Environment variable: `$BUILDKITE_HOOKS_PATH`
`--additional-hooks-paths string` #	Additional directories to look for agent hooks Environment variable: `$BUILDKITE_ADDITIONAL_HOOKS_PATHS`
`--sockets-path string` #	Directory where the agent will place sockets (default: "$HOME/.buildkite-agent/sockets") Environment variable: `$BUILDKITE_SOCKETS_PATH`
`--plugins-path string` #	Directory where the plugins are saved to Environment variable: `$BUILDKITE_PLUGINS_PATH`
`--command-eval` #	Allow running of arbitrary commands (default: true) Environment variable: `$BUILDKITE_COMMAND_EVAL`
`--plugins-enabled` #	Allow plugins to be run (default: true) Environment variable: `$BUILDKITE_PLUGINS_ENABLED`
`--plugin-validation` #	Validate plugin configuration (default: false) Environment variable: `$BUILDKITE_PLUGIN_VALIDATION`
`--plugins-always-clone-fresh` #	Always make a new clone of plugin source, even if already present (default: false) Environment variable: `$BUILDKITE_PLUGINS_ALWAYS_CLONE_FRESH`
`--local-hooks-enabled` #	Allow local hooks to be run (default: true) Environment variable: `$BUILDKITE_LOCAL_HOOKS_ENABLED`
`--ssh-keyscan` #	Accept new SSH host keys for the default checkout instead of requiring known hosts (default: true) Environment variable: `$BUILDKITE_SSH_KEYSCAN`
`--git-submodules` #	Enable git submodules (default: true) Environment variable: `$BUILDKITE_GIT_SUBMODULES`
`--git-lfs-enabled` #	Enable Git LFS object download during checkout (default: false) Environment variable: `$BUILDKITE_GIT_LFS_ENABLED`
`--pty` #	Run jobs within a pseudo terminal (default: true) Environment variable: `$BUILDKITE_PTY`
`--shell string` #	The shell to use to interpret build commands (default: "/bin/bash -e -c") Environment variable: `$BUILDKITE_SHELL`
`--hooks-shell string` #	The shell to use to interpret hooks commands Environment variable: `$BUILDKITE_HOOKS_SHELL`
`--phases string` #	The specific phases to execute. The order they're defined is irrelevant. Environment variable: `$BUILDKITE_BOOTSTRAP_PHASES`
`--opentelemetry-tracing` #	Enable tracing for build jobs with OpenTelemetry OTLP. Configure OTLP with standard OTEL_EXPORTER_OTLP_* env vars (default: false) Environment variable: `$BUILDKITE_OPENTELEMETRY_TRACING`
`--telemetry-service-name string` #	Service name to use when reporting traces. (default: "buildkite-agent") Environment variable: `$BUILDKITE_TELEMETRY_SERVICE_NAME`
`--tracing-traceparent string` #	W3C Trace Parent for tracing Environment variable: `$BUILDKITE_TRACING_TRACEPARENT`
`--tracing-tracestate string` #	W3C Trace State for tracing Environment variable: `$BUILDKITE_TRACING_TRACESTATE`
`--no-job-api` #	Disables the Job API, which gives commands in jobs some abilities to introspect and mutate the state of the job (default: false) Environment variable: `$BUILDKITE_AGENT_NO_JOB_API`
`--job-logs-otlp` #	Export job logs directly as OpenTelemetry log records using the OTEL_EXPORTER_OTLP_LOGS_* / OTEL_EXPORTER_OTLP_* environment configuration (default: false) Environment variable: `$BUILDKITE_JOB_LOGS_OTLP`
`--disable-warnings-for string` #	A list of warning IDs to disable Environment variable: `$BUILDKITE_AGENT_DISABLE_WARNINGS_FOR`
`--cancel-signal string` #	The signal to use for cancellation (default: "SIGTERM") Environment variable: `$BUILDKITE_CANCEL_SIGNAL`
`--cancel-signal-timeout duration` #	The amount of time given to a subprocess to handle the cancel signal before SIGKILL is sent (default: 10s) Environment variable: `$BUILDKITE_CANCEL_SIGNAL_TIMEOUT`
`--cancel-cleanup-timeout duration` #	Extra time for a stopping agent to upload logs and artifacts after a job process exits or is killed, before the agent forcefully exits (default: 5s) Environment variable: `$BUILDKITE_CANCEL_CLEANUP_TIMEOUT`
`--debug` #	Enable debug mode. Synonym for `--log-level debug`. Takes precedence over `--log-level` (default: false) Environment variable: `$BUILDKITE_AGENT_DEBUG`
`--log-level string` #	Set the log level for the agent, making logging more or less verbose. Defaults to notice. Allowed values are: debug, info, error, warn, fatal (default: "notice") Environment variable: `$BUILDKITE_AGENT_LOG_LEVEL`
`--experiment string` #	Enable experimental features within the buildkite-agent Environment variable: `$BUILDKITE_AGENT_EXPERIMENT`
`--profile string` #	Enable a profiling mode, either cpu, memory, mutex or block Environment variable: `$BUILDKITE_AGENT_PROFILE`
`--redacted-vars string` #	Pattern of environment variable names containing sensitive values (default: "_PASSWORD", "_SECRET", "_TOKEN", "_PRIVATE_KEY", "_SSH_KEY", "_ACCESS_KEY", "_SECRET_KEY", "_CONNECTION_STRING", "_API_KEY") Environment variable*: `$BUILDKITE_REDACTED_VARS`
`--strict-single-hooks` #	Enforces that only one checkout hook, and only one command hook, can be run (default: false) Environment variable: `$BUILDKITE_STRICT_SINGLE_HOOKS`