buildkite-agent tool

The Buildkite Agent's tool subcommands are used for performing tasks that are expected to be called by a human as part of setting up a pipeline, rather than during the execution of a job. Any and all of these subcommand may be removed in the future into a separate CLI tool, so they should all be considered experimental.

Experimental feature

The tool subcommand may be removed from the Buildkite Agent in the future.

Generate a JSON Web Key Set

Usage

buildkite-agent tool keygen [options...]

Description

This command generates a new JWS key pair, used for signing and verifying jobs in Buildkite.

The pair is written as a JSON Web Key Set (JWKS) to two files, a private JWKS file and a public JWKS file. The private JWKS should be used as for signing, and the public JWKS for verification.

For more information about JWS, see https://tools.ietf.org/html/rfc7515 and for information about JWKS, see https://tools.ietf.org/html/rfc7517

Options

`--alg value` #	The JWS signing algorithm to use for the key pair. Defaults to 'EdDSA'. Valid algorithms are: [PS512 ES512 EdDSA] Environment variable: `$BUILDKITE_AGENT_KEYGEN_ALG`
`--key-id value` #	The ID to use for the keys generated. If none is provided, a random one will be generated Environment variable: `$BUILDKITE_AGENT_KEYGEN_KEY_ID`
`--private-jwks-file value` #	The filename to write the private key to. Defaults to a name based on the key id in the current directory Environment variable: `$BUILDKITE_AGENT_KEYGEN_PRIVATE_JWKS_FILE`
`--public-jwks-file value` #	The filename to write the public keyset to. Defaults to a name based on the key id in the current directory Environment variable: `$BUILDKITE_AGENT_KEYGEN_PUBLIC_JWKS_FILE`
`--no-color` #	Don't show colors in logging Environment variable: `$BUILDKITE_AGENT_NO_COLOR`
`--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`

Sign a pipeline

Usage

buildkite-agent tool sign [options...] [pipeline-file]

Description

This command takes a pipeline in YAML format as input, and annotates the appropriate parts of the pipeline with signatures. This can then be input into the YAML steps editor in the Buildkite UI so that the agents running these steps can verify the signatures.

If a token is provided using the graphql-token flag, the tool will attempt to retrieve the pipeline definition and repo using the Buildkite GraphQL API. If update is also set, it will update the pipeline definition with the signed version using the GraphQL API too.

Examples

Retrieving the pipeline from the GraphQL API and signing it:

$ buildkite-agent tool sign \
    --graphql-token <graphql token> \
    --organization-slug <your org slug> \
    --pipeline-slug <slug of the pipeline whose steps you want to sign \
    --jwks-file /path/to/private/key.json \
    --update

Signing a pipeline from a file:

$ buildkite-agent tool sign pipeline.yml \
    --jwks-file /path/to/private/key.json \
    --repo <repo url for your pipeline>
# or
$ cat pipeline.yml | buildkite-agent tool sign \
    --jwks-file /path/to/private/key.json \
    --repo <repo url for your pipeline>

Options

`--graphql-token value` #	A token for the buildkite graphql API. This will be used to populate the value of the repository URL, and download the pipeline definition. Both `repo` and `pipeline-file` will be ignored in preference of values from the GraphQL API if the token in provided. Environment variable: `$BUILDKITE_GRAPHQL_TOKEN`
`--update` #	Update the pipeline using the GraphQL API after signing it. This can only be used if `graphql-token` is provided. Environment variable: `$BUILDKITE_TOOL_SIGN_UPDATE`
`--no-confirm` #	Show confirmation prompts before updating the pipeline with the GraphQL API. Environment variable: `$BUILDKITE_TOOL_SIGN_NO_CONFIRM`
`--jwks-file value` #	Path to a file containing a JWKS. Environment variable: `$BUILDKITE_AGENT_JWKS_FILE`
`--jwks-key-id value` #	The JWKS key ID to use when signing the pipeline. If none is provided and the JWKS file contains only one key, that key will be used. Environment variable: `$BUILDKITE_AGENT_JWKS_KEY_ID`
`--debug-signing` #	Enable debug logging for pipeline signing. This can potentially leak secrets to the logs as it prints each step in full before signing. Requires debug logging to be enabled Environment variable: `$BUILDKITE_AGENT_DEBUG_SIGNING`
`--organization-slug value` #	The organization slug. Required to connect to the GraphQL API. Environment variable: `$BUILDKITE_ORGANIZATION_SLUG`
`--pipeline-slug value` #	The pipeline slug. Required to connect to the GraphQL API. Environment variable: `$BUILDKITE_PIPELINE_SLUG`
`--graphql-endpoint value` #	The endpoint for the Buildkite GraphQL API. This is only needed if you are using the the graphql-token flag, and is mostly useful for development purposes (default: "https://graphql.buildkite.com/v1") Environment variable: `$BUILDKITE_GRAPHQL_ENDPOINT`
`--repo value` #	The URL of the pipeline's repository, which is used in the pipeline signature. If the GraphQL token is provided, this will be ignored. Environment variable: `$BUILDKITE_REPO`
`--no-color` #	Don't show colors in logging Environment variable: `$BUILDKITE_AGENT_NO_COLOR`
`--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`