diff --git a/pages/agent/v3/help/_pipeline_upload.md b/pages/agent/v3/help/_pipeline_upload.md index f8ad2741f1..59e2b091ab 100644 --- a/pages/agent/v3/help/_pipeline_upload.md +++ b/pages/agent/v3/help/_pipeline_upload.md @@ -56,8 +56,8 @@ $ ./script/dynamic_step_generator | buildkite-agent pipeline upload --format value #

In dry-run mode, specifies the form to output the pipeline in. Must be one of: json,yaml (default: "json")
Environment variable: $BUILDKITE_PIPELINE_UPLOAD_DRY_RUN_FORMAT

--no-interpolation #

Skip variable interpolation into the pipeline prior to upload
Environment variable: $BUILDKITE_PIPELINE_NO_INTERPOLATION

--reject-secrets #

When true, fail the pipeline upload early if the pipeline contains secrets
Environment variable: $BUILDKITE_AGENT_PIPELINE_UPLOAD_REJECT_SECRETS

---jwks-file-path value #

EXPERIMENTAL: Path to a file containing a JWKS. Passing this flag enables pipeline signing
Environment variable: $BUILDKITE_PIPELINE_UPLOAD_JWKS_FILE_PATH

---signing-key-id value #

EXPERIMENTAL: The JWKS key ID to use when signing the pipeline. Required when using a JWKS
Environment variable: $BUILDKITE_PIPELINE_UPLOAD_SIGNING_KEY_ID

+--jwks-file value #

EXPERIMENTAL: Path to a file containing a JWKS. Passing this flag enables pipeline signing
Environment variable: $BUILDKITE_AGENT_JWKS_FILE

+--jwks-key-id value #

EXPERIMENTAL: The JWKS key ID to use when signing the pipeline. Required when using a JWKS
Environment variable: $BUILDKITE_AGENT_JWKS_KEY_ID

--agent-access-token value #

The access token used to identify the agent
Environment variable: $BUILDKITE_AGENT_ACCESS_TOKEN

--endpoint value #

The Agent API endpoint (default: "https://agent.buildkite.com/v3")
Environment variable: $BUILDKITE_AGENT_ENDPOINT

--no-http2 #

Disable HTTP2 when communicating with the Agent API.
Environment variable: $BUILDKITE_NO_HTTP2

diff --git a/pages/agent/v3/help/_start.md b/pages/agent/v3/help/_start.md index cfa3ee8e67..ac69954cc9 100644 --- a/pages/agent/v3/help/_start.md +++ b/pages/agent/v3/help/_start.md @@ -96,10 +96,10 @@ $ buildkite-agent start --token xxx --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. (default: 0)
Environment variable: $BUILDKITE_SIGNAL_GRACE_PERIOD_SECONDS

--tracing-backend value #

Enable tracing for build jobs by specifying a backend, "datadog" or "opentelemetry"
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

---job-verification-jwks-path value #

EXPERIMENTAL: Path to a file containing a JSON Web Key Set (JWKS), used to verify job signatures.
Environment variable: $BUILDKITE_AGENT_JWKS_FILE_PATH

---job-signing-jwks-path value #

EXPERIMENTAL: Path to a file containing a signing key. Passing this flag enables pipeline signing for all pipelines uploaded by this agent. For hmac-sha256, the raw file content is used as the shared key
Environment variable: $BUILDKITE_PIPELINE_UPLOAD_JWKS_FILE_PATH

---job-signing-key-id value #

EXPERIMENTAL: The JWKS key ID to use when signing the pipeline. Required when using a JWKS
Environment variable: $BUILDKITE_PIPELINE_UPLOAD_SIGNING_KEY_ID

---job-verification-failure-behavior value #

EXPERIMENTAL: The behavior when a job is received without a signature. One of: [block warn]. Defaults to block (default: "block")
Environment variable: $BUILDKITE_AGENT_JOB_VERIFICATION_NO_SIGNATURE_BEHAVIOR

+--verification-jwks-file value #

EXPERIMENTAL: Path to a file containing a JSON Web Key Set (JWKS), used to verify job signatures.
Environment variable: $BUILDKITE_AGENT_VERIFICATION_JWKS_FILE

+--signing-jwks-file value #

EXPERIMENTAL: Path to a file containing a signing key. Passing this flag enables pipeline signing for all pipelines uploaded by this agent. For hmac-sha256, the raw file content is used as the shared key
Environment variable: $BUILDKITE_AGENT_SIGNING_JWKS_FILE

+--signing-jwks-key-id value #

EXPERIMENTAL: The JWKS key ID to use when signing the pipeline. If ommitted, and the signing JWKS conatins only one key, that key will be used.
Environment variable: $BUILDKITE_AGENT_SIGNING_JWKS_KEY_ID

+--verification-failure-behavior value #

EXPERIMENTAL: The behavior when a job is received without a signature. One of: [block warn]. Defaults to block (default: "block")
Environment variable: $BUILDKITE_AGENT_JOB_VERIFICATION_NO_SIGNATURE_BEHAVIOR

--token value #

Your account agent token
Environment variable: $BUILDKITE_AGENT_TOKEN

--endpoint value #

The Agent API endpoint (default: "https://agent.buildkite.com/v3")
Environment variable: $BUILDKITE_AGENT_ENDPOINT

--no-http2 #

Disable HTTP2 when communicating with the Agent API.
Environment variable: $BUILDKITE_NO_HTTP2

diff --git a/pages/agent/v3/help/_tool_keygen.md b/pages/agent/v3/help/_tool_keygen.md new file mode 100644 index 0000000000..51228d3ab1 --- /dev/null +++ b/pages/agent/v3/help/_tool_keygen.md @@ -0,0 +1,47 @@ + + +### Usage + +`buildkite-agent tool keygen [options...]` + +### Description + +This (experimental!) 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. Valid algorithms are: [HS256 HS384 HS512 PS256 PS384 PS512 ES256 ES384 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

+ + diff --git a/pages/agent/v3/help/_tool_sign.md b/pages/agent/v3/help/_tool_sign.md new file mode 100644 index 0000000000..a7de8b9c69 --- /dev/null +++ b/pages/agent/v3/help/_tool_sign.md @@ -0,0 +1,49 @@ + + +### Usage + +`buildkite-agent tool sign-pipeline [options...] [pipeline-file]` + +### Description + +This (experimental!) 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. + +### 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

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

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

+ +