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

Flags to pass to "git checkout" command (default: "-f")
Environment variable: $BUILDKITE_GIT_CHECKOUT_FLAGS

--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-submodule-clone-config value #

Comma separated key=value git config pairs applied before git submodule clone commands. For example, `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-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

--sockets-path value #

Directory where the agent will place sockets (default: "$HOME/.buildkite-agent/sockets")
Environment variable: $BUILDKITE_SOCKETS_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

--tracing-backend value #

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

--tracing-service-name value #

Service name to use when reporting traces. (default: "buildkite-agent")
Environment variable: $BUILDKITE_TRACING_SERVICE_NAME

--no-job-api #

Disables the Job API, which gives commands in jobs some abilities to introspect and mutate the state of the job.
Environment variable: $BUILDKITE_AGENT_NO_JOB_API

--disable-warnings-for value #

A list of warning IDs to disable
Environment variable: $BUILDKITE_AGENT_DISABLE_WARNINGS_FOR

--kubernetes-container-id value #

This is intended to be used only by the Buildkite k8s stack (github.com/buildkite/agent-stack-k8s); it sets an ID number used to identify this container within the pod (default: 0)
Environment variable: $BUILDKITE_CONTAINER_ID

--cancel-signal value #

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

--cancel-grace-period value #

The number of seconds a canceled or timed out job is given to gracefully terminate and upload its artifacts (default: 10)
Environment variable: $BUILDKITE_CANCEL_GRACE_PERIOD

--signal-grace-period-seconds value #

The number of seconds given to a subprocess to handle being sent `cancel-signal`. After this period has elapsed, SIGKILL will be sent. Negative values are taken relative to `cancel-grace-period`. The default is `cancel-grace-period` - 1. (default: -1)
Environment variable: $BUILDKITE_SIGNAL_GRACE_PERIOD_SECONDS

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

--redacted-vars value #

Pattern of environment variable names containing sensitive values (default: "*_PASSWORD", "*_SECRET", "*_TOKEN", "*_PRIVATE_KEY", "*_ACCESS_KEY", "*_SECRET_KEY", "*_CONNECTION_STRING")
Environment variable: $BUILDKITE_REDACTED_VARS

--strict-single-hooks #

Enforces that only one checkout hook, and only one command hook, can be run
Environment variable: $BUILDKITE_STRICT_SINGLE_HOOKS

--kubernetes-exec #

This is intended to be used only by the Buildkite k8s stack (github.com/buildkite/agent-stack-k8s); it enables a Unix socket for transporting logs and exit statuses between containers in a pod
Environment variable: $BUILDKITE_KUBERNETES_EXEC