Merge remote-tracking branch 'docs-public/main' into ev-packages-api-…

…registry-tokens-delete

data/nav.yml

@@ -557,11 +557,17 @@
             - name: "Members"
               path: "apis/rest-api/organizations/members"
               pill: "beta"
-        - name: "Packages"
+        - name: "Packages "
+          # Keep space at end to prevent "Packages" in global nav bar being
+          # highlighted when any child page of "API > REST > Packages" is selected.
           children:
+            - name: "Registries"
+              path: "apis/rest-api/packages/registries"
             - name: "Registry Tokens"
               path: "apis/rest-api/packages/registry-tokens"
-        - name: "Pipelines"
+        - name: "Pipelines "
+          # Keep space at end to prevent "Pipelines" in global nav bar being
+          # highlighted when any child page of "API > REST > Pipelines" is selected.
           children:
             - name: "Overview"
               path: "apis/rest-api/pipelines"

pages/agent/v3/help/_annotate.md

@@ -56,7 +56,7 @@ $ ./script/dynamic_annotation_generator | buildkite-agent annotate --style "succ
 <tr id="context"><th><code>--context value</code> <a class="Docs__attribute__link" href="#context">#</a></th><td><p>The context of the annotation used to differentiate this annotation from others<br /><strong>Environment variable</strong>: <code>$BUILDKITE_ANNOTATION_CONTEXT</code></p></td></tr>
 <tr id="style"><th><code>--style value</code> <a class="Docs__attribute__link" href="#style">#</a></th><td><p>The style of the annotation (`success`, `info`, `warning` or `error`)<br /><strong>Environment variable</strong>: <code>$BUILDKITE_ANNOTATION_STYLE</code></p></td></tr>
 <tr id="append"><th><code>--append </code> <a class="Docs__attribute__link" href="#append">#</a></th><td><p>Append to the body of an existing annotation<br /><strong>Environment variable</strong>: <code>$BUILDKITE_ANNOTATION_APPEND</code></p></td></tr>
-<tr id="priority"><th><code>--priority value</code> <a class="Docs__attribute__link" href="#priority">#</a></th><td><p>Priority of the annotation (1 to 10). By default annotations have a priority of 3. Annotations with a priority of 10 will be shown first, and annotations with a priority of 1 will be shown last. (default: 0)<br /><strong>Environment variable</strong>: <code>$BUILDKITE_ANNOTATION_PRIORITY</code></p></td></tr>
+<tr id="priority"><th><code>--priority value</code> <a class="Docs__attribute__link" href="#priority">#</a></th><td><p>The priority of the annotation (`1` to `10`). Annotations with a priority of `10` are shown first, while annotations with a priority of `1` are shown last. (default: 3)<br /><strong>Environment variable</strong>: <code>$BUILDKITE_ANNOTATION_PRIORITY</code></p></td></tr>
 <tr id="job"><th><code>--job value</code> <a class="Docs__attribute__link" href="#job">#</a></th><td><p>Which job should the annotation come from<br /><strong>Environment variable</strong>: <code>$BUILDKITE_JOB_ID</code></p></td></tr>
 <tr id="agent-access-token"><th><code>--agent-access-token value</code> <a class="Docs__attribute__link" href="#agent-access-token">#</a></th><td><p>The access token used to identify the agent<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_ACCESS_TOKEN</code></p></td></tr>
 <tr id="endpoint"><th><code>--endpoint value</code> <a class="Docs__attribute__link" href="#endpoint">#</a></th><td><p>The Agent API endpoint (default: "<code>https://agent.buildkite.com/v3</code>")<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_ENDPOINT</code></p></td></tr>

pages/agent/v3/help/_bootstrap.md

@@ -103,6 +103,7 @@ $ buildkite-agent bootstrap --build-path builds
 <tr id="redacted-vars"><th><code>--redacted-vars value</code> <a class="Docs__attribute__link" href="#redacted-vars">#</a></th><td><p>Pattern of environment variable names containing sensitive values (default: "*_PASSWORD", "*_SECRET", "*_TOKEN", "*_PRIVATE_KEY", "*_ACCESS_KEY", "*_SECRET_KEY", "*_CONNECTION_STRING")<br /><strong>Environment variable</strong>: <code>$BUILDKITE_REDACTED_VARS</code></p></td></tr>
 <tr id="strict-single-hooks"><th><code>--strict-single-hooks </code> <a class="Docs__attribute__link" href="#strict-single-hooks">#</a></th><td><p>Enforces that only one checkout hook, and only one command hook, can be run<br /><strong>Environment variable</strong>: <code>$BUILDKITE_STRICT_SINGLE_HOOKS</code></p></td></tr>
 <tr id="kubernetes-exec"><th><code>--kubernetes-exec </code> <a class="Docs__attribute__link" href="#kubernetes-exec">#</a></th><td><p>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<br /><strong>Environment variable</strong>: <code>$BUILDKITE_KUBERNETES_EXEC</code></p></td></tr>
+<tr id="trace-context-encoding"><th><code>--trace-context-encoding value</code> <a class="Docs__attribute__link" href="#trace-context-encoding">#</a></th><td><p>Sets the inner encoding for BUILDKITE_TRACE_CONTEXT. Must be either json or gob (default: "gob")<br /><strong>Environment variable</strong>: <code>$BUILDKITE_TRACE_CONTEXT_ENCODING</code></p></td></tr>
 </table>
 
 <!-- vale on -->

pages/agent/v3/help/_pipeline_upload.md

@@ -58,6 +58,7 @@ $ ./script/dynamic_step_generator | buildkite-agent pipeline upload
 <tr id="reject-secrets"><th><code>--reject-secrets </code> <a class="Docs__attribute__link" href="#reject-secrets">#</a></th><td><p>When true, fail the pipeline upload early if the pipeline contains secrets<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_PIPELINE_UPLOAD_REJECT_SECRETS</code></p></td></tr>
 <tr id="jwks-file"><th><code>--jwks-file value</code> <a class="Docs__attribute__link" href="#jwks-file">#</a></th><td><p>Path to a file containing a JWKS. Passing this flag enables pipeline signing<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_JWKS_FILE</code></p></td></tr>
 <tr id="jwks-key-id"><th><code>--jwks-key-id value</code> <a class="Docs__attribute__link" href="#jwks-key-id">#</a></th><td><p>The JWKS key ID to use when signing the pipeline. Required when using a JWKS<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_JWKS_KEY_ID</code></p></td></tr>
+<tr id="signing-aws-kms-key"><th><code>--signing-aws-kms-key value</code> <a class="Docs__attribute__link" href="#signing-aws-kms-key">#</a></th><td><p>The AWS KMS key identifier which is used to sign pipelines.<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_AWS_KMS_KEY</code></p></td></tr>
 <tr id="debug-signing"><th><code>--debug-signing </code> <a class="Docs__attribute__link" href="#debug-signing">#</a></th><td><p>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<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_DEBUG_SIGNING</code></p></td></tr>
 <tr id="agent-access-token"><th><code>--agent-access-token value</code> <a class="Docs__attribute__link" href="#agent-access-token">#</a></th><td><p>The access token used to identify the agent<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_ACCESS_TOKEN</code></p></td></tr>
 <tr id="endpoint"><th><code>--endpoint value</code> <a class="Docs__attribute__link" href="#endpoint">#</a></th><td><p>The Agent API endpoint (default: "<code>https://agent.buildkite.com/v3</code>")<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_ENDPOINT</code></p></td></tr>

pages/agent/v3/help/_start.md

@@ -103,6 +103,7 @@ $ buildkite-agent start --token xxx
 <tr id="verification-jwks-file"><th><code>--verification-jwks-file value</code> <a class="Docs__attribute__link" href="#verification-jwks-file">#</a></th><td><p>Path to a file containing a JSON Web Key Set (JWKS), used to verify job signatures.<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_VERIFICATION_JWKS_FILE</code></p></td></tr>
 <tr id="signing-jwks-file"><th><code>--signing-jwks-file value</code> <a class="Docs__attribute__link" href="#signing-jwks-file">#</a></th><td><p>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<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_SIGNING_JWKS_FILE</code></p></td></tr>
 <tr id="signing-jwks-key-id"><th><code>--signing-jwks-key-id value</code> <a class="Docs__attribute__link" href="#signing-jwks-key-id">#</a></th><td><p>The JWKS key ID to use when signing the pipeline. If omitted, and the signing JWKS contains only one key, that key will be used.<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_SIGNING_JWKS_KEY_ID</code></p></td></tr>
+<tr id="signing-aws-kms-key"><th><code>--signing-aws-kms-key value</code> <a class="Docs__attribute__link" href="#signing-aws-kms-key">#</a></th><td><p>The KMS KMS key ID, or key alias used when signing and verifying the pipeline.<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_SIGNING_AWS_KMS_KEY</code></p></td></tr>
 <tr id="debug-signing"><th><code>--debug-signing </code> <a class="Docs__attribute__link" href="#debug-signing">#</a></th><td><p>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<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_DEBUG_SIGNING</code></p></td></tr>
 <tr id="verification-failure-behavior"><th><code>--verification-failure-behavior value</code> <a class="Docs__attribute__link" href="#verification-failure-behavior">#</a></th><td><p>The behavior when a job is received without a signature. One of: [block warn]. Defaults to block (default: "block")<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_JOB_VERIFICATION_NO_SIGNATURE_BEHAVIOR</code></p></td></tr>
 <tr id="disable-warnings-for"><th><code>--disable-warnings-for value</code> <a class="Docs__attribute__link" href="#disable-warnings-for">#</a></th><td><p>A list of warning IDs to disable<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_DISABLE_WARNINGS_FOR</code></p></td></tr>
@@ -118,6 +119,7 @@ $ buildkite-agent start --token xxx
 <tr id="redacted-vars"><th><code>--redacted-vars value</code> <a class="Docs__attribute__link" href="#redacted-vars">#</a></th><td><p>Pattern of environment variable names containing sensitive values (default: "*_PASSWORD", "*_SECRET", "*_TOKEN", "*_PRIVATE_KEY", "*_ACCESS_KEY", "*_SECRET_KEY", "*_CONNECTION_STRING")<br /><strong>Environment variable</strong>: <code>$BUILDKITE_REDACTED_VARS</code></p></td></tr>
 <tr id="strict-single-hooks"><th><code>--strict-single-hooks </code> <a class="Docs__attribute__link" href="#strict-single-hooks">#</a></th><td><p>Enforces that only one checkout hook, and only one command hook, can be run<br /><strong>Environment variable</strong>: <code>$BUILDKITE_STRICT_SINGLE_HOOKS</code></p></td></tr>
 <tr id="kubernetes-exec"><th><code>--kubernetes-exec </code> <a class="Docs__attribute__link" href="#kubernetes-exec">#</a></th><td><p>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<br /><strong>Environment variable</strong>: <code>$BUILDKITE_KUBERNETES_EXEC</code></p></td></tr>
+<tr id="trace-context-encoding"><th><code>--trace-context-encoding value</code> <a class="Docs__attribute__link" href="#trace-context-encoding">#</a></th><td><p>Sets the inner encoding for BUILDKITE_TRACE_CONTEXT. Must be either json or gob (default: "gob")<br /><strong>Environment variable</strong>: <code>$BUILDKITE_TRACE_CONTEXT_ENCODING</code></p></td></tr>
 <tr id="tags-from-ec2"><th><code>--tags-from-ec2 </code> <a class="Docs__attribute__link" href="#tags-from-ec2">#</a></th><td><p>Include the host's EC2 meta-data as tags (instance-id, instance-type, and ami-id)<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_TAGS_FROM_EC2</code></p></td></tr>
 <tr id="tags-from-gcp"><th><code>--tags-from-gcp </code> <a class="Docs__attribute__link" href="#tags-from-gcp">#</a></th><td><p>Include the host's Google Cloud instance meta-data as tags (instance-id, machine-type, preemptible, project-id, region, and zone)<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_TAGS_FROM_GCP</code></p></td></tr>
 </table>

pages/agent/v3/help/_tool_sign.md

@@ -61,6 +61,7 @@ $ cat pipeline.yml | buildkite-agent tool sign \
 <tr id="no-confirm"><th><code>--no-confirm </code> <a class="Docs__attribute__link" href="#no-confirm">#</a></th><td><p>Show confirmation prompts before updating the pipeline with the GraphQL API.<br /><strong>Environment variable</strong>: <code>$BUILDKITE_TOOL_SIGN_NO_CONFIRM</code></p></td></tr>
 <tr id="jwks-file"><th><code>--jwks-file value</code> <a class="Docs__attribute__link" href="#jwks-file">#</a></th><td><p>Path to a file containing a JWKS.<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_JWKS_FILE</code></p></td></tr>
 <tr id="jwks-key-id"><th><code>--jwks-key-id value</code> <a class="Docs__attribute__link" href="#jwks-key-id">#</a></th><td><p>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.<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_JWKS_KEY_ID</code></p></td></tr>
+<tr id="signing-aws-kms-key"><th><code>--signing-aws-kms-key value</code> <a class="Docs__attribute__link" href="#signing-aws-kms-key">#</a></th><td><p>The AWS KMS key identifier which is used to sign pipelines.<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_AWS_KMS_KEY</code></p></td></tr>
 <tr id="debug-signing"><th><code>--debug-signing </code> <a class="Docs__attribute__link" href="#debug-signing">#</a></th><td><p>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<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_DEBUG_SIGNING</code></p></td></tr>
 <tr id="organization-slug"><th><code>--organization-slug value</code> <a class="Docs__attribute__link" href="#organization-slug">#</a></th><td><p>The organization slug. Required to connect to the GraphQL API.<br /><strong>Environment variable</strong>: <code>$BUILDKITE_ORGANIZATION_SLUG</code></p></td></tr>
 <tr id="pipeline-slug"><th><code>--pipeline-slug value</code> <a class="Docs__attribute__link" href="#pipeline-slug">#</a></th><td><p>The pipeline slug. Required to connect to the GraphQL API.<br /><strong>Environment variable</strong>: <code>$BUILDKITE_PIPELINE_SLUG</code></p></td></tr>

pages/agent/v3/signed_pipelines.md

@@ -102,6 +102,12 @@ verification-jwks-file=<path to public key set>
 
 This ensures that whenever those agents upload steps to Buildkite, they'll generate signatures using the private key you generated earlier. It also ensures that those agents verify the signatures of any steps they run, using the public key.
 
+```ini
+verification-failure-behavior=<warn>
+```
+
+This setting determines the Buildkite agent's response when it receives a job without a proper signature, and also specifies how strictly the agent should enforce signature verification for incoming jobs. The agent will warn about missing or invalid signatures, but will still proceed to execute the job. If not explicitly specified, the default behavior is `block`, which prevents any job without a valid signature from running, ensuring a secure pipeline environment by default.
+
 On instances that verify jobs, add:
 
 ```ini

pages/apis/agent_api.md

@@ -1,12 +1,12 @@
 # Agent REST API overview
 
-The Agent REST API is used for agent registration, agent deregistration, starting jobs on agents, finishing jobs on agents, and agent metrics.
+The agent REST API endpoint is used for agent registration, agent deregistration, starting jobs on agents, finishing jobs on agents, and agent metrics.
 
 The only publicly available endpoint is `/metrics`. The [Buildkite metrics agent](https://github.com/buildkite/buildkite-agent-metrics) uses the data returned by the metrics endpoint for agent autoscaling.
 
-All other endpoints in the Agent API are intended only for use by the Buildkite Agent, therefore stability and backwards compatibility are not guaranteed, and changes won't be announced.
+All other endpoints in the agent API are intended only for use by the Buildkite Agent, therefore stability and backwards compatibility are not guaranteed, and changes won't be announced.
 
-The current version of the Agent API is v3.
+The current version of the agent API is v3.
 
 ## Schema
 
@@ -24,9 +24,9 @@ curl https://agent.buildkite.com
 
 ## Authentication
 
-Unlike the [Buildkite REST API](/docs/apis/rest-api), which uses an [API access token](/docs/apis/rest-api#authentication), the Agent REST API uses an [Agent registration token](/docs/agent/v3/tokens) for authentication.
+Unlike the [Buildkite REST API](/docs/apis/rest-api), which uses an [API access token](/docs/apis/rest-api#authentication), the agent REST API uses an [agent token](/docs/agent/v3/tokens) for authentication.
 
-To authenticate using an Agent registration token, set the `Authorization` HTTP header to the word `Token`, followed by a space, followed by the access token. For example:
+To authenticate using an agent token, set the `Authorization` HTTP header to the word `Token`, followed by a space, followed by the agent token. For example:
 
 ```bash
 curl -H "Authorization: Token $TOKEN" https://agent.buildkite.com/v3/metrics

pages/apis/agent_api/metrics.md

@@ -4,7 +4,7 @@ toc: false
 
 # Metrics API
 
-The Metrics API endpoint provides information on idle and busy agents, jobs, and queues for the [Agent registration token](/docs/agent/v3/tokens) supplied in the request `Authorization` header.
+The metrics API endpoint provides information on idle and busy agents, jobs, and queues for the [Agent registration token](/docs/agent/v3/tokens) supplied in the request `Authorization` header.
 
 ## Get metrics
 

pages/apis/rest_api/access_token.md

@@ -1,8 +1,8 @@
 # Access token API
 
-The Access token API allows you to inspect and revoke an API access token. This can be useful if you find a token, can't identify its owner, and you want to revoke it.
+The access token API endpoint allows you to inspect and revoke an API access token. This can be useful if you find a token, can't identify its owner, and you want to revoke it.
 
->📘
+> 📘
 > All the endpoints expect the token to be provided using the <a href="/docs/apis/rest-api#authentication">Authorization HTTP header</a>.
 
 

pages/apis/rest_api/agents.md

@@ -1,6 +1,5 @@
 # Agents API
 
-
 ## List agents
 
 Returns a [paginated list](<%= paginated_resource_docs_url %>) of an organization's agents. The list only includes connected agents - agents in a disconnected state are not returned.

pages/apis/rest_api/analytics/flaky_tests.md

@@ -1,6 +1,6 @@
 # Flaky tests API
 
-The Flaky test API endpoint provides information about tests detected as flaky in a test suite.
+The flaky test API endpoint provides information about tests detected as flaky in a test suite.
 
 ## List all flaky tests
 

pages/apis/rest_api/clusters.md

@@ -1,6 +1,6 @@
 # Clusters API
 
-The clusters API lets you create and manage clusters in your organization.
+The clusters API endpoint lets you create and manage clusters in your organization.
 
 ## Clusters
 

pages/apis/rest_api/meta.md

@@ -1,6 +1,6 @@
 # Meta API
 
-The Meta API provides information about Buildkite, including a list of Buildkite's IP addresses.
+The meta API endpoint provides information about Buildkite, including a list of Buildkite's IP addresses.
 
 It does not require authentication.
 

pages/apis/rest_api/organizations.md

@@ -1,6 +1,6 @@
 # Organizations API
 
-The organizations API:
+The organizations API endpoint:
 
 - allows you to list organizations and retrieve information about an organization
 

pages/apis/rest_api/organizations/members.md

@@ -1,6 +1,6 @@
 # Organization members API
 
-The organization members API allows users to view all members of an organization.
+The organization members API endpoint allows users to view all members of an organization.
 
 ## Organization member data model