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`
`--secrets value` #	Secrets to be loaded into the job environment Environment variable: `$BUILDKITE_SECRETS_CONFIG`
`--pullrequest value` #	The number/id of the pull request this commit belonged to Environment variable: `$BUILDKITE_PULL_REQUEST`
`--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 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 (default: false) Environment variable: `$BUILDKITE_CLEAN_CHECKOUT`
`--skip-checkout` #	Skip the git checkout phase entirely Environment variable: `$BUILDKITE_SKIP_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 (default: "-v --prune") 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-mirror-checkout-mode value` #	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 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 (default: false) Environment variable: `$BUILDKITE_GIT_MIRRORS_SKIP_UPDATE`
`--git-submodule-clone-config value` #	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-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`
`--bin-path value` #	Directory where the buildkite-agent binary lives Environment variable: `$BUILDKITE_BIN_PATH`
`--build-path value` #	Path to where the builds will run from Environment variable: `$BUILDKITE_BUILD_PATH`
`--hooks-path value` #	Directory where the hook scripts are found Environment variable: `$BUILDKITE_HOOKS_PATH`
`--additional-hooks-paths value` #	Additional directories to look for agent hooks Environment variable: `$BUILDKITE_ADDITIONAL_HOOKS_PATHS`
`--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 (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` #	Automatically run ssh-keyscan before checkout (default: true) Environment variable: `$BUILDKITE_SSH_KEYSCAN`
`--git-submodules` #	Enable git submodules (default: true) Environment variable: `$BUILDKITE_GIT_SUBMODULES`
`--pty` #	Run jobs within a pseudo terminal (default: true) 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`
`--tracing-traceparent value` #	W3C Trace Parent for tracing Environment variable: `$BUILDKITE_TRACING_TRACEPARENT`
`--tracing-propagate-traceparent` #	Accept traceparent from Buildkite control plane (default: false) Environment variable: `$BUILDKITE_TRACING_PROPAGATE_TRACEPARENT`
`--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`
`--disable-warnings-for value` #	A list of warning IDs to disable Environment variable: `$BUILDKITE_AGENT_DISABLE_WARNINGS_FOR`
`--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 value (-1) means that the effective signal grace period is equal to `cancel-grace-period` minus 1. (default: -1) Environment variable: `$BUILDKITE_SIGNAL_GRACE_PERIOD_SECONDS`
`--debug` #	Enable debug mode. Synonym for `--log-level debug`. Takes precedence over `--log-level` (default: false) 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", "_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`
`--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`