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/v3/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 value #

The command to run
Environment variable: $BUILDKITE_COMMAND

--job value #

The ID of the job being run
Environment variable: $BUILDKITE_JOB_ID

--repository value #

The repository to clone and run the job from
Environment variable: $BUILDKITE_REPO

--commit value #

The commit to checkout in the repository
Environment variable: $BUILDKITE_COMMIT

--branch value #

The branch the commit is in
Environment variable: $BUILDKITE_BRANCH

--tag value #

The tag the commit
Environment variable: $BUILDKITE_TAG

--refspec value #

Optional refspec to override git fetch
Environment variable: $BUILDKITE_REFSPEC

--plugins value #

The plugins for the job
Environment variable: $BUILDKITE_PLUGINS

--pullrequest value #

The number/id of the pull request this commit belonged to
Environment variable: $BUILDKITE_PULL_REQUEST

--agent value #

The name of the agent running the job
Environment variable: $BUILDKITE_AGENT_NAME

--queue value #

The name of the queue the agent belongs to, if tagged
Environment variable: $BUILDKITE_AGENT_META_DATA_QUEUE

--organization value #

The slug of the organization that the job is a part of
Environment variable: $BUILDKITE_ORGANIZATION_SLUG

--pipeline value #

The slug of the pipeline that the job is a part of
Environment variable: $BUILDKITE_PIPELINE_SLUG

--pipeline-provider value #

The id of the SCM provider that the repository is hosted on
Environment variable: $BUILDKITE_PIPELINE_PROVIDER

--artifact-upload-paths value #

Paths to files to automatically upload at the end of a job
Environment variable: $BUILDKITE_ARTIFACT_PATHS

--artifact-upload-destination value #

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
Environment variable: $BUILDKITE_CLEAN_CHECKOUT

--git-clone-flags value #

Flags to pass to "git clone" command (default: "-v")
Environment variable: $BUILDKITE_GIT_CLONE_FLAGS

--git-clone-mirror-flags value #

Flags to pass to "git clone" command when mirroring (default: "-v")
Environment variable: $BUILDKITE_GIT_CLONE_MIRROR_FLAGS

--git-clean-flags value #

Flags to pass to "git clean" command (default: "-ffxdq")
Environment variable: $BUILDKITE_GIT_CLEAN_FLAGS

--git-fetch-flags value #

Flags to pass to "git fetch" command
Environment variable: $BUILDKITE_GIT_FETCH_FLAGS

--git-mirrors-path value #

Path to where mirrors of git repositories are stored
Environment variable: $BUILDKITE_GIT_MIRRORS_PATH

--git-mirrors-lock-timeout value #

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
Environment variable: $BUILDKITE_GIT_MIRRORS_SKIP_UPDATE

--bin-path value #

Directory where the buildkite-agent binary lives
Environment variable: $BUILDKITE_BIN_PATH

--build-path value #

Directory where builds will be created
Environment variable: $BUILDKITE_BUILD_PATH

--hooks-path value #

Directory where the hook scripts are found
Environment variable: $BUILDKITE_HOOKS_PATH

--plugins-path value #

Directory where the plugins are saved to
Environment variable: $BUILDKITE_PLUGINS_PATH

--command-eval #

Allow running of arbitrary commands
Environment variable: $BUILDKITE_COMMAND_EVAL

--plugins-enabled #

Allow plugins to be run
Environment variable: $BUILDKITE_PLUGINS_ENABLED

--plugin-validation #

Validate plugin configuration
Environment variable: $BUILDKITE_PLUGIN_VALIDATION

--plugins-always-clone-fresh #

Always make a new clone of plugin source, even if already present
Environment variable: $BUILDKITE_PLUGINS_ALWAYS_CLONE_FRESH

--local-hooks-enabled #

Allow local hooks to be run
Environment variable: $BUILDKITE_LOCAL_HOOKS_ENABLED

--ssh-keyscan #

Automatically run ssh-keyscan before checkout
Environment variable: $BUILDKITE_SSH_KEYSCAN

--git-submodules #

Enable git submodules
Environment variable: $BUILDKITE_GIT_SUBMODULES

--pty #

Run jobs within a pseudo terminal
Environment variable: $BUILDKITE_PTY

--shell value #

The shell to use to interpret build commands (default: "/bin/bash -e -c")
Environment variable: $BUILDKITE_SHELL

--phases value #

The specific phases to execute. The order they're defined is irrelevant.
Environment variable: $BUILDKITE_BOOTSTRAP_PHASES

--cancel-signal value #

The signal to use for cancellation (default: "SIGTERM")
Environment variable: $BUILDKITE_CANCEL_SIGNAL

--redacted-vars value #

Pattern of environment variable names containing sensitive values
Environment variable: $BUILDKITE_REDACTED_VARS

--tracing-backend value #

The name of the tracing backend to use.
Environment variable: $BUILDKITE_TRACING_BACKEND

--debug #

Enable debug mode. Synonym for `--log-level debug`. Takes precedence over `--log-level`
Environment variable: $BUILDKITE_AGENT_DEBUG

--log-level value #

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 value #

Enable experimental features within the buildkite-agent
Environment variable: $BUILDKITE_AGENT_EXPERIMENT

--profile value #

Enable a profiling mode, either cpu, memory, mutex or block
Environment variable: $BUILDKITE_AGENT_PROFILE