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`
`--trace-context-encoding value` #	Sets the inner encoding for BUILDKITE_TRACE_CONTEXT. Must be either json or gob (default: "gob") Environment variable: `$BUILDKITE_TRACE_CONTEXT_ENCODING`