buildkite-agent-runtime

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Buildkite Agent Runtime

Buildkite Agent 运行时

The

buildkite-agent

binary provides subcommands for interacting with Buildkite from within running job steps — creating annotations, uploading artifacts, sharing state between jobs, generating dynamic pipelines, requesting OIDC tokens, and more. This skill covers the command syntax, flags, and patterns for every in-job subcommand.

buildkite-agent

二进制文件提供了在运行的作业步骤中与 Buildkite 交互的子命令——创建注释、上传工件、在作业间共享状态、生成动态流水线、请求OIDC令牌等。本技能涵盖了所有作业内子命令的命令语法、标志和使用模式。

Quick Start

快速入门

A step that runs tests, annotates failures, uploads coverage, and stores a result flag for downstream jobs:

yaml

steps:
  - label: ":test_tube: Tests"
    command: |
      if ! make test 2>&1 | tee test-output.txt; then
        buildkite-agent annotate --style "error" --context "test-failures" < test-output.txt
        buildkite-agent meta-data set "tests-passed" "false"
        exit 1
      fi
      buildkite-agent annotate "All tests passed :white_check_mark:" --style "success" --context "test-results"
      buildkite-agent artifact upload "coverage/**/*"
      buildkite-agent meta-data set "tests-passed" "true"

A downstream step reading that state:

yaml

  - label: ":rocket: Deploy"
    command: |
      PASSED=$(buildkite-agent meta-data get "tests-passed")
      if [[ "$PASSED" != "true" ]]; then
        echo "Tests did not pass, skipping deploy"
        exit 0
      fi
      scripts/deploy.sh
    depends_on: "test-step"

一个运行测试、标记失败、上传覆盖率并为下游作业存储结果标志的步骤：

yaml

steps:
  - label: ":test_tube: Tests"
    command: |
      if ! make test 2>&1 | tee test-output.txt; then
        buildkite-agent annotate --style "error" --context "test-failures" < test-output.txt
        buildkite-agent meta-data set "tests-passed" "false"
        exit 1
      fi
      buildkite-agent annotate "All tests passed :white_check_mark:" --style "success" --context "test-results"
      buildkite-agent artifact upload "coverage/**/*"
      buildkite-agent meta-data set "tests-passed" "true"

读取该状态的下游步骤：

yaml

  - label: ":rocket: Deploy"
    command: |
      PASSED=$(buildkite-agent meta-data get "tests-passed")
      if [[ "$PASSED" != "true" ]]; then
        echo "Tests did not pass, skipping deploy"
        exit 0
      fi
      scripts/deploy.sh
    depends_on: "test-step"

Annotations

注释

Surface build results directly on the build page. Annotations support Markdown and HTML.

在构建页面直接展示构建结果。注释支持Markdown和HTML格式。

Creating annotations

创建注释

bash

undefined

bash

undefined

Simple text annotation

简单文本注释

buildkite-agent annotate "Deploy completed successfully" --style "success" --context "deploy"

Pipe from a file

从文件导入内容

buildkite-agent annotate --style "error" --context "test-failures" < test-output.md

undefined

buildkite-agent annotate --style "error" --context "test-failures" < test-output.md

undefined

Key flags

关键标志

Flag	Short	Default	Description
`--style`	`-s`	`default`	Visual style: `default` , `info` , `warning` , `error` , `success`
`--context`	`-c`	random UUID	Unique ID — reusing a context replaces the annotation
`--append`	—	`false`	Append to existing annotation with same context instead of replacing
`--priority`	—	`3`	Display priority (1-10). Higher numbers appear first
`--job`	—	current job	Job ID to annotate (rarely needed)

标志	简写	默认值	描述
`--style`	`-s`	`default`	视觉样式： `default` 、 `info` 、 `warning` 、 `error` 、 `success`
`--context`	`-c`	随机UUID	唯一ID——重复使用相同context会替换原注释
`--append`	—	`false`	向具有相同context的现有注释追加内容，而非替换
`--priority`	—	`3`	显示优先级（1-10），数值越高越靠前显示
`--job`	—	当前作业	要添加注释的作业ID（很少需要）

Replacing vs appending

替换与追加

Same
--context
without
--append
replaces the annotation; with
--append
appends below existing content.
Always use a stable
```
--context
```
value so reruns update the same annotation instead of creating duplicates.

For pipeline-level
notify:
configuration, see the buildkite-pipelines skill.

**相同
```
--context
```
且不带
```
--append
```
**会替换注释；**带
```
--append
```
**会在现有内容下方追加。
始终使用稳定的
```
--context
```
值，以便重新运行时更新同一注释，而非创建重复项。

关于流水线级别的
notify:
配置，请查看buildkite-pipelines技能。

Artifacts

工件

Upload files as build artifacts, download them in later steps or other builds, and search by glob.

将文件上传为构建工件，可在后续步骤或其他构建中下载，也可通过通配符搜索。

Upload

上传

bash

undefined

bash

undefined

Upload a single file

上传单个文件

buildkite-agent artifact upload "pkg/release.tar.gz"

Upload with glob pattern

使用通配符模式上传

buildkite-agent artifact upload "dist/**/*"

undefined

buildkite-agent artifact upload "dist/**/*"

undefined

Download

下载

bash

undefined

bash

undefined

Download to current directory

下载到当前目录

buildkite-agent artifact download "pkg/release.tar.gz" .

Download from a specific step

从指定步骤下载

buildkite-agent artifact download "dist/*" . --step "build-step"

undefined

buildkite-agent artifact download "dist/*" . --step "build-step"

undefined

Search

搜索

bash

undefined

bash

undefined

List matching artifacts

列出匹配的工件

buildkite-agent artifact search "pkg/*.tar.gz" --build "$BUILDKITE_BUILD_ID"


For complete flag tables, see `references/flag-reference.md`.

> For the declarative `artifact_paths:` YAML key, see the **buildkite-pipelines** skill. For `bk artifact` CLI commands, see the **buildkite-cli** skill.

buildkite-agent artifact search "pkg/*.tar.gz" --build "$BUILDKITE_BUILD_ID"


完整的标志表格请查看`references/flag-reference.md`。

> 关于声明式`artifact_paths:` YAML键，请查看**buildkite-pipelines**技能。关于`bk artifact` CLI命令，请查看**buildkite-cli**技能。

Meta-data

元数据

A build-wide key-value store for sharing state between jobs. Set a value in one job, read it in any other job in the same build.

构建级别的键值存储，用于在作业间共享状态。在一个作业中设置值，可在同一构建的任何其他作业中读取。

Set

设置

bash

buildkite-agent meta-data set "release-version" "1.4.2"

bash

buildkite-agent meta-data set "release-version" "1.4.2"

Get

获取

bash

VERSION=$(buildkite-agent meta-data get "release-version")

Use

--default

to return a fallback value instead of a non-zero exit when the key is missing:

buildkite-agent meta-data get "deploy-env" --default "staging"

bash

VERSION=$(buildkite-agent meta-data get "release-version")

使用

--default

可在键不存在时返回回退值，而非返回非零退出码：

buildkite-agent meta-data get "deploy-env" --default "staging"

。

Check existence

检查存在性

bash

undefined

bash

undefined

Returns exit code 0 if exists, 100 if not

若存在返回退出码0，不存在返回100

if buildkite-agent meta-data exists "release-version"; then echo "Version already set" fi

undefined

if buildkite-agent meta-data exists "release-version"; then echo "Version already set" fi

undefined

Common patterns

常见模式

Block step field values are stored automatically as meta-data. Retrieve them by field key:

bash

undefined

阻塞步骤字段值会自动存储为元数据。可通过字段键检索：

bash

undefined

After a block step with fields: [{key: "release-name", text: "Release Name"}]

在包含字段的阻塞步骤之后：[{key: "release-name", text: "Release Name"}]

RELEASE_NAME=$(buildkite-agent meta-data get "release-name")


**Raw webhook payloads** are available in webhook-triggered builds, while the webhook data remains cached. Read the special `buildkite:webhook` key when automation needs fields that are not promoted to first-class environment variables, such as the original pull request comment body.

```bash
WEBHOOK="$(buildkite-agent meta-data get "buildkite:webhook")"
COMMENT_BODY="$(jq -r '.comment.body' <<< "$WEBHOOK")"

RELEASE_NAME=$(buildkite-agent meta-data get "release-name")


**原始webhook负载**在webhook触发的构建中可用，同时webhook数据会被缓存。当自动化需要未提升为一级环境变量的字段（如原始拉取请求评论内容）时，读取特殊的`buildkite:webhook`键。

```bash
WEBHOOK="$(buildkite-agent meta-data get "buildkite:webhook")"
COMMENT_BODY="$(jq -r '.comment.body' <<< "$WEBHOOK")"

Pipeline Upload

流水线上传

Dynamically add steps to a running build. The core mechanism behind dynamic pipelines — generate YAML at runtime and upload it.

向运行中的构建动态添加步骤。这是动态流水线的核心机制——在运行时生成YAML并上传。

Basic usage

基本用法

bash

undefined

bash

undefined

Upload a specific file

上传指定文件

buildkite-agent pipeline upload .buildkite/deploy-steps.yml

Pipe generated YAML from stdin

从标准输入导入生成的YAML

./scripts/generate-pipeline.sh | buildkite-agent pipeline upload

undefined

./scripts/generate-pipeline.sh | buildkite-agent pipeline upload

undefined

Replace mode

替换模式

By default, uploaded steps are appended after the current step. Use

--replace

to replace the entire remaining pipeline:

bash

undefined

默认情况下，上传的步骤会追加到当前步骤之后。使用

--replace

可替换整个剩余流水线：

bash

undefined

Replace all remaining steps with the uploaded ones

用上传的步骤替换所有剩余步骤

buildkite-agent pipeline upload --replace .buildkite/new-pipeline.yml

undefined

buildkite-agent pipeline upload --replace .buildkite/new-pipeline.yml

undefined

Key flags

关键标志

Flag	Default	Description
`--replace`	`false`	Replace remaining pipeline steps instead of appending
`--no-interpolation`	`false`	Skip environment variable interpolation in the uploaded YAML
`--dry-run`	`false`	Validate and output the pipeline without uploading

For pipeline YAML syntax and step types, see the buildkite-pipelines skill.

标志	默认值	描述
`--replace`	`false`	替换剩余流水线步骤，而非追加
`--no-interpolation`	`false`	跳过上传YAML中的环境变量插值
`--dry-run`	`false`	验证并输出流水线，但不上传

关于流水线YAML语法和步骤类型，请查看buildkite-pipelines技能。

OIDC Tokens

OIDC令牌

Request short-lived OpenID Connect tokens from within a job step for authenticating to external services (cloud providers, package registries) without static credentials.

在作业步骤内请求短期OpenID Connect令牌，用于向外部服务（云提供商、包注册表）认证，无需静态凭据。

Basic token request

基本令牌请求

bash

undefined

bash

undefined

Request a token for a specific audience

请求针对特定受众的令牌

TOKEN=$(buildkite-agent oidc request-token --audience "https://packages.buildkite.com/my-org/my-registry")

undefined

TOKEN=$(buildkite-agent oidc request-token --audience "https://packages.buildkite.com/my-org/my-registry")

undefined

Cloud provider authentication

云提供商认证

bash

undefined

bash

undefined

AWS — request token with STS audience

AWS — 请求带有STS受众的令牌

TOKEN=$(buildkite-agent oidc request-token --audience "sts.amazonaws.com")

undefined

TOKEN=$(buildkite-agent oidc request-token --audience "sts.amazonaws.com")

undefined

Key flags

关键标志

Flag	Default	Description
`--audience`	Buildkite endpoint	Target service URL — must match the OIDC provider audience configuration
`--lifetime`	`0` (API default)	Token lifetime in seconds. When 0 or omitted, the API chooses a default lifetime
`--claim`	—	Optional claims to include (e.g., `organization_id,pipeline_id` ). Repeatable
`--aws-session-tag`	—	Claims to map as AWS session tags. Repeatable

For end-to-end OIDC auth flows, cloud provider setup, and token claim details, see the buildkite-secure-delivery skill.

标志	默认值	描述
`--audience`	Buildkite端点	目标服务URL——必须与OIDC提供商的受众配置匹配
`--lifetime`	`0` （API默认值）	令牌有效期（秒）。设为0或省略时，由API选择默认有效期
`--claim`	—	可选要包含的声明（如 `organization_id,pipeline_id` ），可重复使用
`--aws-session-tag`	—	要映射为AWS会话标签的声明，可重复使用

关于端到端OIDC认证流程、云提供商设置和令牌声明详情，请查看buildkite-secure-delivery技能。

Step Management

步骤管理

Read or modify step attributes at runtime. Useful for conditional logic within steps and build automation.

在运行时读取或修改步骤属性，适用于步骤内的条件逻辑和构建自动化。

Get step attributes

获取步骤属性

bash

undefined

bash

undefined

Get a step's label (--step is required)

获取步骤的标签（必须指定--step）

LABEL=$(buildkite-agent step get "label" --step "$BUILDKITE_STEP_KEY")

Get another step's state

获取另一个步骤的状态

STATE=$(buildkite-agent step get "state" --step "deploy-step")

Get the entire step as JSON

以JSON格式获取整个步骤的信息

buildkite-agent step get --step "test-step" --format json

undefined

buildkite-agent step get --step "test-step" --format json

undefined

Update step attributes

更新步骤属性

bash

undefined

bash

undefined

Update a step's label dynamically

动态更新步骤的标签

buildkite-agent step update "label" ":rocket: Deploying v${VERSION}" --step "$BUILDKITE_STEP_KEY"

Append to an existing label

向现有标签追加内容

buildkite-agent step update "label" " (retried)" --step "build-step" --append

undefined

buildkite-agent step update "label" " (retried)" --step "build-step" --append

undefined

Cancel a step

取消步骤

bash

undefined

bash

undefined

Cancel all unfinished jobs for a step

取消某一步骤的所有未完成作业

buildkite-agent step cancel --step "optional-step"

Force-cancel a running step

强制取消正在运行的步骤

buildkite-agent step cancel --step "stuck-step" --force

undefined

buildkite-agent step cancel --step "stuck-step" --force

undefined

Key flags

关键标志

Flag	Default	Description
`--step`	—	Step key or UUID to target (required — uses `$BUILDKITE_STEP_ID` env var if set)
`--build`	current build	Build UUID (for cross-build operations)
`--format`	—	Output format for `get` (use `json` for complex attributes)
`--append`	`false`	Append to existing value instead of replacing ( `step update` only)
`--force`	`false`	Force cancel even if the step is running ( `step cancel` only)

标志	默认值	描述
`--step`	—	目标步骤的键或UUID（必填——若设置了 `$BUILDKITE_STEP_ID` 环境变量则使用该值）
`--build`	当前构建	构建UUID（用于跨构建操作）
`--format`	—	`get` 命令的输出格式（复杂属性使用 `json` ）
`--append`	`false`	向现有值追加内容而非替换（仅 `step update` 可用）
`--force`	`false`	即使步骤正在运行也强制取消（仅 `step cancel` 可用）

Distributed Locks

分布式锁

Coordinate parallel jobs within a build using distributed mutex locks. Prevents race conditions when multiple jobs access shared resources.

使用分布式互斥锁协调构建中的并行作业，防止多个作业访问共享资源时出现竞争条件。

Acquire / release pattern

获取/释放模式

bash

#!/bin/bash
set -euo pipefail

bash

#!/bin/bash
set -euo pipefail

Acquire lock — blocks until available, returns a token

获取锁——阻塞直到可用，返回令牌

token=$(buildkite-agent lock acquire "database-migration") trap 'buildkite-agent lock release "database-migration" "${token}"' EXIT

Critical section — only one job runs this at a time

临界区——同一时间只有一个作业运行此部分代码

bundle exec rails db:migrate

undefined

bundle exec rails db:migrate

undefined

Do / done pattern (one-time setup)

Do/Done模式（一次性设置）

Run a setup task exactly once across all parallel jobs:

bash

#!/bin/bash
echo "+++ Setting up shared test environment"

if [[ $(buildkite-agent lock do "test-env-setup") == "do" ]]; then
  echo "Downloading test assets..."
  curl -o /tmp/test-data.zip https://releases.example.com/data.zip
  unzip /tmp/test-data.zip -d /tmp/shared-test-files/
  buildkite-agent lock done "test-env-setup"
else
  echo "Assets already prepared by another job"
fi

在所有并行作业中仅运行一次设置任务：

bash

#!/bin/bash
echo "+++ Setting up shared test environment"

if [[ $(buildkite-agent lock do "test-env-setup") == "do" ]]; then
  echo "Downloading test assets..."
  curl -o /tmp/test-data.zip https://releases.example.com/data.zip
  unzip /tmp/test-data.zip -d /tmp/shared-test-files/
  buildkite-agent lock done "test-env-setup"
else
  echo "Assets already prepared by another job"
fi

All jobs continue here

所有作业在此处继续执行

run-tests.sh

undefined

run-tests.sh

undefined

Key flags

关键标志

Subcommand	Flags	Description
`lock acquire <name>`	`--lock-wait-timeout`	Maximum wait duration (e.g. `30s` , `5m` ). Default: wait forever
`lock release <name> <token>`	—	Release with the token from `acquire`
`lock do <name>`	—	Returns `do` if lock acquired, `done` if already completed
`lock done <name>`	—	Mark a `do` lock as completed

子命令	标志	描述
`lock acquire <name>`	`--lock-wait-timeout`	最大等待时长（如 `30s` 、 `5m` ），默认：无限等待
`lock release <name> <token>`	—	使用 `acquire` 返回的令牌释放锁
`lock do <name>`	—	获取锁则返回 `do` ，已完成则返回 `done`
`lock done <name>`	—	将 `do` 锁标记为已完成

Environment

环境变量

Inspect and modify the job's environment variables. Primarily useful for debugging lifecycle hooks and understanding what environment changes hooks made.

bash

undefined

检查和修改作业的环境变量，主要用于调试生命周期钩子，以及了解钩子对环境的修改。

bash

undefined

Dump all environment variables as JSON

以JSON格式导出所有环境变量

buildkite-agent env dump | jq .

Get a specific variable

获取特定变量

buildkite-agent env get "BUILDKITE_BRANCH"

Set variables for subsequent hooks and the command (KEY=value format)

为后续钩子和命令设置变量（KEY=value格式）

buildkite-agent env set DEPLOY_TARGET=production "APP_NAME=My App"

undefined

buildkite-agent env set DEPLOY_TARGET=production "APP_NAME=My App"

undefined

Key flags

关键子命令

Subcommand	Description
`env dump`	Dump all environment variables (JSON format by default)
`env get <keys...>`	Get one or more specific variables. Use `--format` for output format ( `plain` , `json` , `json-pretty` )
`env set KEY=value [...]`	Set variables for subsequent phases. Accepts multiple `KEY=value` pairs
`env unset <key>`	Remove a variable from subsequent phases

子命令	描述
`env dump`	导出所有环境变量（默认JSON格式）
`env get <keys...>`	获取一个或多个特定变量，使用 `--format` 指定输出格式（ `plain` 、 `json` 、 `json-pretty` ）
`env set KEY=value [...]`	为后续阶段设置变量，支持多个 `KEY=value` 对
`env unset <key>`	从后续阶段移除变量

Debugging hooks

调试钩子

The

env dump

command is particularly useful in lifecycle hooks to see what prior hooks changed:

bash

#!/bin/bash

env dump

命令在生命周期钩子中特别有用，可查看之前的钩子对环境的修改：

bash

#!/bin/bash

.buildkite/hooks/pre-command

echo "--- Environment after environment hook:" buildkite-agent env dump | jq 'keys'


> For agent lifecycle hooks and `buildkite-agent.cfg` configuration, see the [agent hooks](https://buildkite.com/docs/agent/hooks) and [agent configuration](https://buildkite.com/docs/agent/self-hosted/configure) documentation.

echo "--- Environment after environment hook:" buildkite-agent env dump | jq 'keys'


> 关于Agent生命周期钩子和`buildkite-agent.cfg`配置，请查看[Agent钩子](https://buildkite.com/docs/agent/hooks)和[Agent配置](https://buildkite.com/docs/agent/self-hosted/configure)文档。

Secrets

机密

Retrieve cluster secrets at runtime from within job steps. Secrets retrieved this way are automatically added to the log redactor.

在运行时从作业步骤中检索集群机密，以此方式检索的机密会自动添加到日志编辑器中。

Basic usage

基本用法

bash

undefined

bash

undefined

Get a secret value

获取机密值

SECRET_VAR=$(buildkite-agent secret get "deploy-key")

Pass directly to a tool

直接传递给工具

cli-tool --token "$(buildkite-agent secret get "api-token")"

undefined

cli-tool --token "$(buildkite-agent secret get "api-token")"

undefined

Key flags

关键标志

Flag	Default	Description
`--format`	`default`	Output format: `default` (single secret prints value, multiple prints JSON), `json` , or `env` (KEY="value" pairs)
`--skip-redaction`	`false`	Do not add the secret value to the log redactor
`--job`	current job	Job ID context

Multiple secret keys can be requested at once:

buildkite-agent secret get KEY1 KEY2 KEY3

By default,

secret get

automatically registers retrieved values with the log redactor, masking them as

[REDACTED]

in subsequent output.

For setting up cluster secrets, see the Buildkite Secrets documentation. For the declarative
secrets:
pipeline YAML key, see the buildkite-pipelines skill.

标志	默认值	描述
`--format`	`default`	输出格式： `default` （单个机密打印值，多个打印JSON）、 `json` 或 `env` （KEY="value"格式）
`--skip-redaction`	`false`	不将机密值添加到日志编辑器
`--job`	当前作业	作业ID上下文

可同时请求多个机密键：

buildkite-agent secret get KEY1 KEY2 KEY3

。

默认情况下，

secret get

会自动将检索到的值注册到日志编辑器中，在后续输出中会将其屏蔽为

[REDACTED]

。

关于集群机密的设置，请查看Buildkite Secrets文档。关于声明式
secrets:
流水线YAML键，请查看buildkite-pipelines技能。

Log Redaction

日志编辑

Add values to the build log redactor at runtime so they are masked in all subsequent output. Use this for dynamically-retrieved secrets that were not declared via

secrets:

buildkite-agent secret get

在运行时将值添加到构建日志编辑器中，使其在所有后续输出中被屏蔽。适用于未通过

secrets:

或

buildkite-agent secret get

声明的动态检索机密。

Basic usage

基本用法

bash

undefined

bash

undefined

Fetch a token from an external source

从外部源获取令牌

DYNAMIC_TOKEN=$(curl -s https://vault.example.com/token)

Register it with the redactor before using it

在使用前将其注册到编辑器

echo "$DYNAMIC_TOKEN" | buildkite-agent redactor add

Now any log output containing the token value shows [REDACTED]

现在任何包含令牌值的日志输出都会显示为[REDACTED]

echo "Using token: $DYNAMIC_TOKEN"

Output: Using token: [REDACTED]

输出：Using token: [REDACTED]

undefined

undefined

Multiple values

多个值

bash

undefined

bash

undefined

Redact multiple values

屏蔽多个值

echo "$SECRET1" | buildkite-agent redactor add echo "$SECRET2" | buildkite-agent redactor add

undefined

echo "$SECRET1" | buildkite-agent redactor add echo "$SECRET2" | buildkite-agent redactor add

undefined

When to use redactor vs secret get

使用编辑器还是secret get

Scenario	Use
Secret stored in Buildkite cluster secrets	`buildkite-agent secret get` (auto-redacts)
Secret from external vault (HashiCorp Vault, AWS SSM, etc.)	Fetch externally, then `buildkite-agent redactor add`
Computed sensitive value (temporary token, derived key)	`buildkite-agent redactor add`

场景	使用方式
存储在Buildkite集群机密中的机密	`buildkite-agent secret get` （自动屏蔽）
来自外部Vault（HashiCorp Vault、AWS SSM等）的机密	从外部获取，然后使用 `buildkite-agent redactor add`
计算得出的敏感值（临时令牌、派生密钥）	`buildkite-agent redactor add`

Tool Signing

工具签名

Sign pipeline YAML so that agents can verify step integrity before execution. The

tool sign

command takes a pipeline file (not individual steps) and annotates it with signatures.

对流水线YAML进行签名，以便Agent在执行前验证步骤完整性。

tool sign

命令接收流水线文件（而非单个步骤），并为其添加签名注释。

Sign a pipeline from a file

对文件中的流水线签名

bash

undefined

bash

undefined

Sign a pipeline YAML file using a local JWKS key

使用本地JWKS密钥对流水线YAML文件签名

buildkite-agent tool sign pipeline.yml
--jwks-file /path/to/private-key.json
--repo "git@github.com:org/repo.git"

undefined

buildkite-agent tool sign pipeline.yml
--jwks-file /path/to/private-key.json
--repo "git@github.com:org/repo.git"

undefined

Sign via the GraphQL API

通过GraphQL API签名

bash

undefined

bash

undefined

Retrieve, sign, and update a pipeline via the Buildkite GraphQL API

通过Buildkite GraphQL API检索、签名并更新流水线

buildkite-agent tool sign
--graphql-token "$BUILDKITE_GRAPHQL_TOKEN"
--organization-slug my-org
--pipeline-slug my-pipeline
--jwks-file /path/to/private-key.json
--update

undefined

buildkite-agent tool sign
--graphql-token "$BUILDKITE_GRAPHQL_TOKEN"
--organization-slug my-org
--pipeline-slug my-pipeline
--jwks-file /path/to/private-key.json
--update

undefined

Generate a signing key pair

生成签名密钥对

bash

undefined

bash

undefined

Generate a new JWS key pair (private + public JWKS files)

生成新的JWS密钥对（私钥+公钥JWKS文件）

buildkite-agent tool keygen

undefined

buildkite-agent tool keygen

undefined

Key flags

关键标志

Command	Flag	Description
`tool sign`	`--jwks-file`	Path to JWKS private key file for signing
`tool sign`	`--jwks-key-id`	Key ID to use from the JWKS file
`tool sign`	`--repo`	Repository URL (required when signing from a file)
`tool sign`	`--signing-aws-kms-key`	AWS KMS key ID for signing (alternative to JWKS)
`tool sign`	`--signing-gcp-kms-key`	GCP KMS key ID for signing (alternative to JWKS)
`tool sign`	`--graphql-token`	Token for retrieving/updating pipeline via GraphQL API
`tool sign`	`--update`	Update the pipeline in Buildkite after signing (requires `--graphql-token` )
`tool keygen`	`--alg`	JWS signing algorithm (default: `EdDSA` )
`tool keygen`	`--key-id`	Key ID for the generated pair (default: random)

Note: There is no
tool verify
command. Signature verification is handled internally by the agent when it receives a job.

For pipeline signing configuration and rollout strategy, see the buildkite-secure-delivery skill.

命令	标志	描述
`tool sign`	`--jwks-file`	用于签名的JWKS私钥文件路径
`tool sign`	`--jwks-key-id`	JWKS文件中要使用的密钥ID
`tool sign`	`--repo`	仓库URL（对文件签名时必填）
`tool sign`	`--signing-aws-kms-key`	用于签名的AWS KMS密钥ID（JWKS的替代方案）
`tool sign`	`--signing-gcp-kms-key`	用于签名的GCP KMS密钥ID（JWKS的替代方案）
`tool sign`	`--graphql-token`	通过GraphQL API检索/更新流水线的令牌
`tool sign`	`--update`	签名后在Buildkite中更新流水线（需要 `--graphql-token` ）
`tool keygen`	`--alg`	JWS签名算法（默认： `EdDSA` ）
`tool keygen`	`--key-id`	生成密钥对的ID（默认：随机值）

注意： 没有
tool verify
命令。签名验证由Agent在接收作业时内部处理。

关于流水线签名配置和部署策略，请查看buildkite-secure-delivery技能。

Common Mistakes

常见错误

Mistake	What happens	Fix
Missing `--context` on `annotate`	Each call creates a new annotation instead of updating	Always pass `--context` with a stable identifier
Using `--append` without matching `--context`	Append has no effect — creates a new annotation	Ensure `--context` matches the annotation to append to
Forgetting to quote artifact glob patterns	Shell expands globs before `buildkite-agent` sees them	Always quote: `"dist/*/"` not `dist/*/`
Reading `meta-data get` before the writing job completes	Key does not exist, command fails with non-zero exit	Use `depends_on` or `wait` to enforce ordering, or use `--default`
Using `pipeline upload --replace` unintentionally	Removes all remaining steps in the build	Only use `--replace` when intentionally rebuilding the entire pipeline
Not releasing locks on script failure	Lock held indefinitely, blocking other jobs	Use `trap ... EXIT` to release locks on any exit
Passing `--audience` that doesn't match OIDC provider config	Token rejected by the target service	Audience must exactly match the provider's configured audience URL
Using `--skip-redaction` with actual secrets	Secret values appear in plain text in build logs	Only use `--skip-redaction` for non-sensitive configuration values
Calling `env set` expecting it to affect the current shell	Variable is set for subsequent hooks/phases, not the current script	Use `export VAR=value` for current-script variables; `env set` for cross-phase
Passing large values via environment variables	OS-level env size limits cause silent truncation or job failure	Switch to file-based approaches (artifacts, meta-data with files) for payloads larger than a few KB
Uploading pipeline YAML with unescaped `$` in `--no-interpolation` mode off	Variables interpolated unexpectedly, producing malformed YAML	Use `--no-interpolation` when YAML contains literal `$` characters

错误	后果	修复方案
`annotate` 命令缺少 `--context`	每次调用都会创建新注释，而非更新	始终传递带有稳定标识符的 `--context`
使用 `--append` 但未匹配 `--context`	追加无效，创建新注释	确保 `--context` 与要追加的注释匹配
忘记给工件通配符模式加引号	Shell在 `buildkite-agent` 处理前展开通配符	始终加引号： `"dist/*/"` 而非 `dist/*/`
在写入作业完成前读取 `meta-data get`	键不存在，命令以非零退出码失败	使用 `depends_on` 或 `wait` 强制排序，或使用 `--default`
无意使用 `pipeline upload --replace`	移除构建中所有剩余步骤	仅在有意重建整个流水线时使用 `--replace`
脚本失败时未释放锁	锁被无限持有，阻塞其他作业	使用 `trap ... EXIT` 确保在任何退出场景下释放锁
传递的 `--audience` 与OIDC提供商配置不匹配	目标服务拒绝令牌	Audience必须与提供商配置的受众URL完全匹配
对实际机密使用 `--skip-redaction`	机密值以明文形式出现在构建日志中	仅对非敏感配置值使用 `--skip-redaction`
调用 `env set` 期望影响当前Shell	变量仅对后续钩子/阶段生效，而非当前脚本	对当前脚本变量使用 `export VAR=value` ；对跨阶段变量使用 `env set`
通过环境变量传递大值	操作系统级别的环境变量大小限制导致静默截断或作业失败	对于大于几KB的负载，切换到基于文件的方式（工件、带文件的元数据）
在 `--no-interpolation` 模式关闭时上传包含未转义 `$` 的流水线YAML	变量被意外插值，生成格式错误的YAML	当YAML包含字面量 `$` 字符时，使用 `--no-interpolation`

Additional Resources

额外资源

Reference Files

参考文件

references/flag-reference.md
— Complete flag tables for all subcommands including upload, download, search, shasum, annotate, meta-data, pipeline upload, oidc, step, lock, env, secret, redactor, and tool
references/patterns-and-recipes.md
— Advanced multi-subcommand patterns: test failure annotation pipelines, cross-job state machines, OIDC-authenticated Docker push, parallel job coordination with locks, environment debugging

references/flag-reference.md
— 所有子命令的完整标志表格，包括upload、download、search、shasum、annotate、meta-data、pipeline upload、oidc、step、lock、env、secret、redactor和tool
references/patterns-and-recipes.md
— 高级多子命令模式：测试失败注释流水线、跨作业状态机、OIDC认证的Docker推送、并行作业锁协调、环境调试