buildkite-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Buildkite API

Do not treat REST as read-only and GraphQL as the write API. Default to REST for builds, pipelines, organization administration, hosted resources, diagnostics, and notification-service writes. Use GraphQL when typed nested reads avoid several requests or for GraphQL-only mutations.

To execute API calls interactively from the terminal, see the buildkite-cli skill for
bk api
commands. With the Buildkite MCP server, prefer purpose-built tools for supported reads and actions.

不要将REST视为只读接口、GraphQL视为写入接口。对于构建、流水线、组织管理、托管资源、诊断以及通知服务写入操作，默认使用REST。当类型化嵌套读取可以避免多次请求，或者需要使用仅支持GraphQL的突变时，使用GraphQL。

如需从终端交互式执行API调用，请查看buildkite-cli Skill中的
bk api
命令。使用Buildkite MCP服务器时，优先选择针对受支持读取和操作的专用工具。

Quick Start

快速入门

List lightweight build records with REST:

bash

curl -sS -H "Authorization: Bearer $BUILDKITE_API_TOKEN" \
  "https://api.buildkite.com/v2/organizations/my-org/pipelines/my-pipeline/builds?exclude_jobs=true&exclude_pipeline=true&per_page=5" \
  | jq '.[] | {number, state, branch}'

Query selected nested fields with GraphQL:

bash

curl -sS -X POST "https://graphql.buildkite.com/v1" \
  -H "Authorization: Bearer $BUILDKITE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ pipeline(slug: \"my-org/my-pipeline\") { builds(first: 5) { edges { node { number state message } } } } }"}' \
  | jq '.data.pipeline.builds.edges[].node'

使用REST列出轻量构建记录：

bash

curl -sS -H "Authorization: Bearer $BUILDKITE_API_TOKEN" \
  "https://api.buildkite.com/v2/organizations/my-org/pipelines/my-pipeline/builds?exclude_jobs=true&exclude_pipeline=true&per_page=5" \
  | jq '.[] | {number, state, branch}'

使用GraphQL查询选定的嵌套字段：

bash

curl -sS -X POST "https://graphql.buildkite.com/v1" \
  -H "Authorization: Bearer $BUILDKITE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ pipeline(slug: \"my-org/my-pipeline\") { builds(first: 5) { edges { node { number state message } } } } }"}' \
  | jq '.data.pipeline.builds.edges[].node'

Authentication and access

认证与访问

Pass a personal API access token as a bearer token. Scope tokens to the required organizations and grant the minimum scopes. Treat an HTTP

as potentially meaning either absent or unavailable: several permission-gated and feature-gated resources deliberately do not disclose existence.

bash

curl -sS -H "Authorization: Bearer $BUILDKITE_API_TOKEN" \
  "https://api.buildkite.com/v2/organizations"

For short-lived credentials, public-key API access tokens (preview) can authenticate REST API access with an RS256-signed JWT. Set the access token UUID as

iss

, keep

iat

within 10 seconds of the current time, and set

exp

no more than five minutes after

iat

. The JWT inherits the token's organization access and scopes.

Common scopes include:

Capability	Scopes
Builds, pipelines, and artifacts	`read_builds` / `write_builds` , `read_pipelines` / `write_pipelines` , `read_artifacts` / `write_artifacts`
Job logs, environments, and agents	`read_build_logs` / `write_build_logs` , `read_job_env` , `read_agents` / `write_agents`
Organization members	`read_organizations` / `write_organizations`
Organization settings	`read_organization_settings` / `write_organization_settings`
Audit events	`read_audit_events`
Repository connections and discovery	`read_organization_repository_connections`
Notification services	`read_notification_services` / `write_notification_services`
Organization invitations	`read_organization_invitations` / `write_organization_invitations`
Teams	`read_teams` / `write_teams`
Hosted and cluster resources	`read_clusters` / `write_clusters`

Scopes are necessary but not always sufficient. Treat

and permission-gated

responses as access or availability boundaries, not evidence that another payload or endpoint should be tried. Use observable organization state and known caller context when available; otherwise report the required role, permission, or feature and ask an administrator to verify it. See API token scopes for the full catalogue.

将个人API访问令牌作为Bearer令牌传递。为令牌设置所需组织的范围，并授予最小必要权限。将HTTP

响应视为资源可能不存在或不可访问：多个受权限和功能限制的资源会故意不披露其存在。

bash

curl -sS -H "Authorization: Bearer $BUILDKITE_API_TOKEN" \
  "https://api.buildkite.com/v2/organizations"

对于短期凭证，公钥API访问令牌（预览版）可通过RS256签名的JWT对REST API访问进行认证。将访问令牌UUID设置为

iss

，确保

iat

与当前时间的偏差在10秒内，并将

exp

设置为不晚于

iat

后5分钟。JWT会继承该令牌的组织访问权限和范围。

常见权限范围包括：

功能	权限范围
构建、流水线和制品	`read_builds` / `write_builds` , `read_pipelines` / `write_pipelines` , `read_artifacts` / `write_artifacts`
作业日志、环境和Agent	`read_build_logs` / `write_build_logs` , `read_job_env` , `read_agents` / `write_agents`
组织成员	`read_organizations` / `write_organizations`
组织设置	`read_organization_settings` / `write_organization_settings`
审计事件	`read_audit_events`
仓库连接与发现	`read_organization_repository_connections`
通知服务	`read_notification_services` / `write_notification_services`
组织邀请	`read_organization_invitations` / `write_organization_invitations`
团队	`read_teams` / `write_teams`
托管与集群资源	`read_clusters` / `write_clusters`

权限范围是必要条件，但并非总是充分条件。将

响应和受权限限制的

响应视为访问或可用性边界，而非应该尝试其他负载或端点的依据。如果有可观察的组织状态和已知的调用者上下文，则使用这些信息；否则报告所需的角色、权限或功能，并请求管理员进行验证。完整的权限范围列表请参见API令牌范围。

REST API

Use

https://api.buildkite.com/v2

as the base URL and

Content-Type: application/json

for JSON request bodies. Most organization-scoped resources begin with

/organizations/{org.slug}

; user, organization-list, and other top-level resources do not.

For build metadata and status reads, default to

exclude_jobs=true&exclude_pipeline=true

. Fetch jobs from the Jobs API only when job details are required.

使用

https://api.buildkite.com/v2

作为基础URL，JSON请求体需设置

Content-Type: application/json

。大多数组织范围的资源以

/organizations/{org.slug}

开头；用户、组织列表及其他顶级资源则无需前缀。

对于构建元数据和状态读取，默认使用

exclude_jobs=true&exclude_pipeline=true

。仅当需要作业详情时，才从Jobs API获取作业信息。

Capability map

功能映射

Use this map to select a resource family, then open the linked reference for exact schemas and response behavior.

Family	Protocol and access	Scope, permission, or gate	Key boundary and docs
Organization settings	REST read/write	`read_organization_settings` / `write_organization_settings` ; organization admin; field gates	Read before writing; API allowlist changes can lock out the caller. API settings and pipeline settings
Audit events	REST read-only	`read_audit_events` ; organization admin; Enterprise	Cursor-paginated independently of settings. Audit events
Members and invitations	REST read/write	`read_organizations` / `write_organizations` , `read_organization_invitations` / `write_organization_invitations` ; organization admin for member updates and all invitation operations	Member `PATCH` changes only `role` and `sso_mode` and cannot target the caller; pending invitations are not memberships. Members and invitations
Teams activation	REST enable-only; GraphQL `Organization.isTeamsEnabled` state read	`write_teams` ; organization access; `change_teams_enabled` ; plan gate when disabled	Idempotent `POST /organizations/{org.slug}/teams/enable` ; may create Everyone when no teams exist; no REST read or disable route. Teams
Repository connections	REST read-only	`read_organization_repository_connections` ; organization admin; provider support	Connections have no API mutations; unsupported discovery providers return `422` . Connections and discovery
Pipeline setup	REST read/write	`read_pipelines` / `write_pipelines` ; pipeline access	Create validates and mutates together; there is no REST dry run. Pipelines
Notification services	REST read/write lifecycle	`read_notification_services` / `write_notification_services` ; organization admin or Manage Notification Services	OAuth Slack Workspace and Linear require initial browser authorization; preserve omitted secrets. Notification services
Inbound GitHub processing	REST read/write	`read_pipelines` / `write_pipelines` ; Full Access; provider and feature gates	Processing controls do not register a repository webhook or configure the GitHub App. Pipelines
Build lifecycle	REST read/write	`read_builds` / `write_builds` ; pipeline access	Rebuild replays the original context instead of fetching current source-control state. Builds
Hosted resources	REST mixed access	`read_clusters` / `write_clusters` ; manage-cluster permission; hosted-agent and resource gates	Cluster read/update exposes hosted Git mirror and container cache settings only to cluster managers; image creation is asynchronous with no update; cache deletion is explicit. Clusters, images, network ranges, and cache volumes
Diagnostics	REST read-only	`read_builds` , `read_agents`	Signal and agent lifecycle fields are evidence, not proof that retry is safe. Jobs and agents
Artifacts	REST read/write; GraphQL deletion	`read_artifacts` / `write_artifacts` for REST; GraphQL API access; Build & Read access or higher on the artifact's pipeline for deletion	Filter before pagination and confirm deletion explicitly. Artifacts

使用此映射选择资源类别，然后打开链接参考获取精确的Schema和响应行为。

类别	协议与访问权限	范围、权限或限制	关键边界与文档
组织设置	REST 读写	`read_organization_settings` / `write_organization_settings` ；组织管理员；字段限制	先读取再写入；API白名单更改可能导致调用者被锁定。API设置和流水线设置
审计事件	REST 只读	`read_audit_events` ；组织管理员；企业版	独立于设置的游标分页。审计事件
成员与邀请	REST 读写	`read_organizations` / `write_organizations` , `read_organization_invitations` / `write_organization_invitations` ；成员更新和所有邀请操作需组织管理员权限	成员 `PATCH` 仅能修改 `role` 和 `sso_mode` ，且无法修改调用者自身信息；待处理邀请不属于正式成员身份。成员和邀请
团队激活	REST 仅启用；GraphQL读取 `Organization.isTeamsEnabled` 状态	`write_teams` ；组织访问权限； `change_teams_enabled` ；禁用时受计划限制	`POST /organizations/{org.slug}/teams/enable` 操作具有幂等性；无团队时可能会创建“所有人”团队；无REST读取或禁用路由。团队
仓库连接	REST 只读	`read_organization_repository_connections` ；组织管理员；提供商支持	连接无API突变接口；不支持的发现提供商会返回 `422` 。连接和发现
流水线设置	REST 读写	`read_pipelines` / `write_pipelines` ；流水线访问权限	创建操作会同时进行验证和突变；无REST试运行模式。流水线
通知服务	REST 读写生命周期	`read_notification_services` / `write_notification_services` ；组织管理员或「管理通知服务」权限	OAuth Slack工作区和Linear需初始浏览器授权；保留未返回的密钥。通知服务
入站GitHub处理	REST 读写	`read_pipelines` / `write_pipelines` ；完全访问权限；提供商和功能限制	处理控制不会注册仓库webhook或配置GitHub应用。流水线
构建生命周期	REST 读写	`read_builds` / `write_builds` ；流水线访问权限	重建操作会重放原始上下文，而非获取当前源代码控制状态。构建
托管资源	REST 混合访问	`read_clusters` / `write_clusters` ；集群管理权限；托管Agent和资源限制	集群读取/更新仅向集群管理员公开托管Git镜像和容器缓存设置；镜像创建为异步操作且无法更新；缓存删除需显式执行。集群、镜像、网络范围和缓存卷
诊断	REST 只读	`read_builds` , `read_agents`	信号和Agent生命周期字段仅作为诊断依据，不能证明重试是安全的。作业和Agent
制品	REST 读写；GraphQL 删除	REST需 `read_artifacts` / `write_artifacts` ；GraphQL需API访问权限；删除需制品所在流水线的「构建与读取」或更高权限	先过滤再分页，并显式确认删除操作。制品

Pagination

分页

Most REST list responses return arrays and HTTP

Link

headers. Follow the URL marked

rel="next"

rather than constructing page numbers. Keep query filters on the initial request and use the server-provided next URL thereafter.

The Jobs API, invitations, notification services, and audit events use cursor-oriented bodies. Read records from

.items

and follow

.links.next

until it is

null

. Audit events also expose a

Link

header. Do not run array-only

jq

filters against these body shapes.

REST requests consume both organization and per-user quotas. On

, stop requests until the matching

RateLimit-Reset

RateLimit-User-Reset

window expires; do not retry in a tight loop. Remote Buildkite MCP server requests use a separate per-user limit, while local MCP server requests consume the organization REST quota.

大多数REST列表响应返回数组和HTTP

Link

头。请跟随标记为

rel="next"

的URL，而非自行构造页码。初始请求保留查询过滤器，后续使用服务器提供的下一页URL。

Jobs API、邀请、通知服务和审计事件使用基于游标的响应体。从

.items

读取记录，跟随

.links.next

直到其为

null

。审计事件还会返回

Link

头。请勿对这些响应体使用仅适用于数组的

jq

过滤器。

REST请求会消耗组织和用户个人配额。收到

响应时，需停止请求直至对应的

RateLimit-Reset

或

RateLimit-User-Reset

窗口过期；请勿频繁重试。远程Buildkite MCP服务器请求使用独立的用户个人限额，而本地MCP服务器请求会消耗组织REST配额。

Pipeline creation

流水线创建

Default to pipeline YAML in the REST

configuration

string. Include

cluster_id

when a cluster has been selected. Omission is valid when the organization allows unclustered pipelines; otherwise the server returns

with

Cluster must be specified

. Do not reject a create client-side solely because

cluster_id

is absent. Use

pipeline_template_uuid

when the user or organization workflow has selected a template. Send a visual

steps

array only for a known legacy visual-step workflow; no public organization field reliably identifies that mode before creation.

The create request performs server validation and mutation together. Validate YAML locally first when useful, but do not describe local schema validation as proof that repository access, provider setup, permissions, or server-side create constraints will pass. Report a

validation response instead of silently retrying with a different step source.

默认在REST的

configuration

字符串中使用流水线YAML。已选择集群时需包含

cluster_id

。若组织允许无集群流水线，则可省略该字段；否则服务器会返回

并提示

Cluster must be specified

。请勿仅因缺少

cluster_id

就拒绝客户端的创建请求。当用户或组织工作流已选择模板时，使用

pipeline_template_uuid

。仅当明确为遗留可视化步骤工作流时，才发送可视化

steps

数组；创建前没有公开的组织字段能可靠识别该模式。

创建请求会同时执行服务器验证和突变操作。必要时可先在本地验证YAML，但请勿将本地Schema验证视为仓库访问、提供商设置、权限或服务器端创建约束一定会通过的证明。收到

验证响应时需进行报告，而非静默重试不同的步骤源。

Organization administration

组织管理

Read settings before mutation, compare only managed fields, and send the smallest supported update. Preserve unknown or feature-gated fields. For API settings, model an allowlist change as a lockout-sensitive operation: verify the caller's source address, retain a rollback path, and avoid concurrent settings writes.

Treat invitations and memberships as different states. List invitations to reconcile pending requests, use show for any invitation state, and use

DELETE

only to revoke a pending invitation. Bulk invitation creation supports role, SSO mode, and team assignments, but validates the entire request atomically. A failure creates none of the requested invitations.

Update an existing member with

PATCH /organizations/{org.slug}/members/{user.uuid}

only after reading that membership. The request accepts only

role

(

admin

member

) and

sso_mode

(

optional

required

), requires

write_organizations

and organization-admin permission, and cannot update the caller's own membership. Send only the fields intended to change; use invitations for people who are not yet members.

Enable Teams only when the requested outcome explicitly requires team-based permissions. Do not use the mutation to probe availability. Read

Organization.isTeamsEnabled

through GraphQL when the current state is needed; when Teams is disabled, explain the plan and permission requirements before enabling it.

修改设置前先读取，仅比较受管理的字段，并发送最小化的支持更新。保留未知或受功能限制的字段。对于API设置，将白名单更改视为可能导致锁定的操作：验证调用者的源地址，保留回滚路径，避免并发设置写入。

将邀请和成员身份视为不同状态。列出邀请以核对待处理请求，使用查询操作获取任意邀请状态，仅使用

DELETE

撤销待处理邀请。批量创建邀请支持角色、SSO模式和团队分配，但会对整个请求进行原子验证。若验证失败，则不会创建任何请求的邀请。

仅在读取成员信息后，使用

PATCH /organizations/{org.slug}/members/{user.uuid}

更新现有成员。该请求仅接受

role

（

admin

或

member

）和

sso_mode

（

optional

或

required

），需要

write_organizations

权限和组织管理员权限，且无法更新调用者自身的成员信息。仅发送需要更改的字段；对于非成员用户，请使用邀请功能。

仅当请求结果明确需要基于团队的权限时，才启用Teams功能。请勿使用突变操作探查可用性。需要当前状态时，通过GraphQL读取

Organization.isTeamsEnabled

；禁用Teams时，需先说明计划和权限要求，再执行启用操作。

Hosted resources

托管资源

Read a cluster with

read_clusters

before changing hosted cache behavior. For callers with manage-cluster permission, cluster show responses include

hosted_git_mirror_enabled

and

hosted_container_cache_enabled

; callers without that permission do not receive these fields, so do not interpret absence as

false

. Update either boolean with

PUT /organizations/{org.slug}/clusters/{id}

using

write_clusters

and manage-cluster permission. Changing either value is supported only for hosted clusters; a non-hosted cluster returns

修改托管缓存行为前，使用

read_clusters

读取集群信息。对于具有集群管理权限的调用者，集群查询响应会包含

hosted_git_mirror_enabled

和

hosted_container_cache_enabled

字段；无该权限的调用者不会收到这些字段，因此请勿将字段缺失视为

false

。使用

PUT /organizations/{org.slug}/clusters/{id}

并配合

write_clusters

权限和集群管理权限，更新任意布尔值。仅托管集群支持修改这些值；非托管集群会返回

。

Artifact filtering

制品过滤

Apply

state

and

path

before pagination on build-level and job-level artifact lists. A path without

is exact; include

only when glob matching is intended. URL-encode paths and state filters rather than filtering a single page locally.

Download by artifact ID with

curl -L

because the download endpoint redirects. REST deletion requires

write_artifacts

; both REST and GraphQL deletion also require Build & Read access or higher on the artifact's pipeline. REST accepts the artifact UUID at either

/organizations/{org.slug}/jobs/{job.id}/artifacts/{id}

or the fully qualified pipeline/build/job route. The build-level artifact-list route has no corresponding delete operation. GraphQL

artifactDelete

accepts the artifact global ID and requires GraphQL API access. Require explicit confirmation for either path, and never turn filtered discovery into an automatic deletion loop.

If the organization uses customer-managed artifact storage, deleting the Buildkite artifact does not remove the underlying object. Do not infer the storage backend or delete external objects automatically; consult the organization's artifact-storage configuration and deletion runbook.

在构建级和作业级制品列表的分页前，先应用

state

和

path

过滤。不带

的路径为精确匹配；仅当需要通配符匹配时才包含

。对路径和状态过滤器进行URL编码，而非在本地对单页结果进行过滤。

使用

curl -L

按制品ID下载，因为下载端点会重定向。REST删除需要

write_artifacts

权限；REST和GraphQL删除还需制品所在流水线的「构建与读取」或更高权限。REST接受在

/organizations/{org.slug}/jobs/{job.id}/artifacts/{id}

或完整的流水线/构建/作业路径中传入制品UUID。构建级制品列表路由没有对应的删除操作。GraphQL

artifactDelete

接受制品全局ID，且需要GraphQL API访问权限。无论使用哪种方式，都需要显式确认，且绝不能将过滤发现转为自动删除循环。

若组织使用客户托管的制品存储，删除Buildkite制品不会移除底层对象。请勿自动推断存储后端或删除外部对象；请查阅组织的制品存储配置和删除手册。

Job and agent diagnostics

作业与Agent诊断

Query jobs directly once the build number is known. Prefer server-side

state

step_key

, and

group_key

filters to fetching every job and filtering locally. A step key matches every job for that step, including parallel jobs; a group key matches every job in that group. Follow each

.links.next

URL as returned so filters remain applied across cursor pages.

Use

signal

and

signal_reason

to distinguish signal termination from an ordinary nonzero exit. Inspect the embedded agent's

os_id

arch

queue

connected_at

disconnected_at

lost_at

, and

stopped_at

to correlate platform, routing, and lifecycle timing.

Treat this context as diagnostic evidence, not proof that retry is safe. Before retrying, inspect logs, side effects, retry history, and whether the command is idempotent. A lost agent can explain interruption without establishing that an external deployment or write did not complete.

已知构建编号后，直接查询作业信息。优先使用服务器端的

state

、

step_key

和

group_key

过滤器，而非获取所有作业后在本地过滤。步骤键会匹配该步骤的所有作业，包括并行作业；组键会匹配该组的所有作业。跟随服务器返回的每个

.links.next

URL，确保过滤器在游标分页中持续生效。

使用

signal

和

signal_reason

区分信号终止与普通非零退出。检查嵌入Agent的

os_id

、

arch

、

queue

、

connected_at

、

disconnected_at

、

lost_at

和

stopped_at

字段，关联平台、路由和生命周期时间。

将这些上下文视为诊断依据，而非重试安全的证明。重试前需检查日志、副作用、重试历史以及命令是否具有幂等性。Agent丢失可以解释中断，但无法证明外部部署或写入操作未完成。

GraphQL API

Use

https://graphql.buildkite.com/v1

. Prefer GraphQL when a typed query avoids several nested REST reads or when its mutation shape better fits the workflow. GraphQL access tokens use the Enable GraphQL API Access permission rather than granular REST scopes. Use global node IDs for mutation inputs, not REST UUIDs or pipeline slugs unless the schema explicitly requests them.

Scenario	Prefer	Reason
Trigger a build	REST	Straightforward body and identifiers
Filter builds, jobs, or artifacts	REST	Purpose-built server filters and pagination
Read audit events	REST	Dedicated read-only audit endpoint and cursor response
Fetch selected nested relationships	GraphQL	Typed field selection can avoid multiple calls
Delete an artifact	REST or GraphQL	REST accepts the artifact UUID; `artifactDelete` accepts a global ID. Apply the same confirmation and storage caveats to both
Use another GraphQL-only mutation	GraphQL	Follow the live schema and mutation-specific permissions

Check both top-level HTTP failures and the GraphQL

errors

array. A

response can still contain operation errors or partial data. See

references/graphql-reference.md

for pagination, global IDs, and artifact deletion.

使用

https://graphql.buildkite.com/v1

。当类型化查询可以避免多次嵌套REST读取，或其突变形状更符合工作流时，优先使用GraphQL。GraphQL访问令牌使用「启用GraphQL API访问」权限，而非细粒度的REST范围。突变输入使用全局节点ID，而非REST UUID或流水线slug，除非Schema明确要求。

场景	优先选择	原因
触发构建	REST	请求体和标识符更简洁
过滤构建、作业或制品	REST	专用的服务器过滤器和分页机制
读取审计事件	REST	专用的只读审计端点和游标响应
获取选定的嵌套关系	GraphQL	类型化字段选择可避免多次调用
删除制品	REST或GraphQL	REST接受制品UUID； `artifactDelete` 接受全局ID。两者均需遵循相同的确认步骤和存储注意事项
使用其他仅支持GraphQL的突变	GraphQL	遵循实时Schema和突变特定权限

同时检查顶级HTTP失败和GraphQL

errors

数组。

响应仍可能包含操作错误或部分数据。分页、全局ID和制品删除相关内容请参见

references/graphql-reference.md

。

Webhooks

Separate outbound notifications from inbound source-control processing:

Create and manage an outbound webhook as a notification service through the organization notification-services REST lifecycle.
Enable or disable Buildkite processing of inbound GitHub events with the pipeline
```
github-webhooks
```
REST resource.
Register an SCM webhook for an eligible GitHub App pipeline with
```
POST /pipelines/{slug}/webhook
```
; Buildkite then creates the provider-side delivery. This is separate from the processing toggle.
Configuring an organization GitHub App connection is a separate browser and organization-administration workflow.

For outbound handlers, branch on

X-Buildkite-Event

or the payload

event

. Do not assume every event has build, job, pipeline, and sender objects with an identical shape. Acknowledge quickly, process idempotently, and consult the webhooks reference for the selected event and current authentication fields.

For notification-service lifecycle and inbound GitHub delivery diagnosis, see
references/webhooks.md
.

区分出站通知与入站源代码控制处理：

通过组织通知服务REST生命周期创建和管理出站webhook。
使用流水线
```
github-webhooks
```
REST资源启用或禁用Buildkite对入站GitHub事件的处理。
使用
```
POST /pipelines/{slug}/webhook
```
为符合条件的GitHub App流水线注册SCM webhook；Buildkite随后会在提供商端创建交付。此操作独立于处理开关。
配置组织GitHub App连接是独立的浏览器和组织管理工作流。

对于出站处理器，根据

X-Buildkite-Event

或负载中的

event

进行分支处理。请勿假设每个事件都具有形状完全相同的构建、作业、流水线和发送者对象。快速确认接收，以幂等方式处理，并查阅webhooks参考获取所选事件和当前认证字段的信息。

通知服务生命周期和入站GitHub交付诊断相关内容请参见
references/webhooks.md
。

Common Mistakes

常见错误

Mistake	What happens	Fix
Assuming `cluster_id` is always required or always optional	Valid unclustered creation is rejected client-side, or clustered-only creation returns `422`	Include a selected cluster; otherwise let the server enforce whether the organization permits unclustered pipelines
Creating a REST pipeline without a valid step source	Creation returns `422`	Use YAML `configuration` , legacy visual `steps` , or `pipeline_template_uuid` as applicable; treat create validation as mutating
Updating settings without reading first	Feature-gated fields are overwritten or an IP allowlist locks out automation	Read, compare managed fields, and preserve a tested rollback path
Treating an invitation as active membership	Automation assumes access before acceptance or provisioning	Track pending invitations separately from members
Assuming repository connections have CRUD endpoints	Automation attempts unsupported mutations	Use list/show and repository discovery only
Replacing notification secrets because GET omits them	Working credentials are rotated unnecessarily	Account for provider-specific secret response behavior and preserve omitted secrets
Confusing outbound notification webhooks with inbound GitHub processing	The wrong endpoint is changed and repository delivery remains broken	Identify notification service, processing toggle, repository registration, and app connection separately
Filtering artifacts after reading one page	Matching artifacts on later pages are missed	Apply `state` and `path` on the API request before pagination
Retrying solely because signal or agent timing suggests interruption	Non-idempotent external effects may run twice	Inspect logs, side effects, and retry history before retrying

错误	后果	修复方案
假设 `cluster_id` 始终必填或始终可选	有效的无集群创建请求被客户端拒绝，或仅支持集群的创建请求返回 `422`	包含选定的集群；否则由服务器强制执行组织是否允许无集群流水线
创建REST流水线时未提供有效的步骤源	创建请求返回 `422`	根据情况使用YAML `configuration` 、遗留可视化 `steps` 或 `pipeline_template_uuid` ；将创建验证视为突变操作
未先读取就更新设置	受功能限制的字段被覆盖，或IP白名单导致自动化被锁定	先读取，比较受管理字段，并保留经过测试的回滚路径
将邀请视为活跃成员身份	自动化在用户接受邀请或完成配置前就假设其具有访问权限	单独跟踪待处理邀请与正式成员
假设仓库连接具有CRUD端点	自动化尝试执行不支持的突变操作	仅使用列表/查询和仓库发现功能
因GET请求未返回密钥而替换通知密钥	正常运行的凭证被不必要地轮换	考虑提供商特定的密钥响应行为，保留未返回的密钥
将出站通知webhook与入站GitHub处理混淆	修改了错误的端点，仓库交付仍无法正常工作	分别识别通知服务、处理开关、仓库注册和应用连接
读取单页结果后再过滤制品	遗漏后续页面中的匹配制品	在API请求中分页前应用 `state` 和 `path` 过滤
仅因信号或Agent时间表明中断就重试	非幂等的外部操作可能会执行两次	重试前检查日志、副作用和重试历史

Additional Resources

附加资源

Reference Files

参考文件

references/graphql-reference.md
— GraphQL pagination, global IDs, common queries, and safe artifact deletion
references/webhooks.md
— Notification-service lifecycle and boundaries between outbound and inbound webhook concepts
references/patterns.md
— Copy-paste REST workflows for audit inventory, repository-to-pipeline setup, notification reconciliation, and diagnostics

references/graphql-reference.md
— GraphQL分页、全局ID、常见查询和安全的制品删除方法
references/webhooks.md
— 通知服务生命周期以及出站与入站webhook概念的边界
references/patterns.md
— 可直接复用的REST工作流，用于审计清单、仓库到流水线设置、通知核对和诊断

buildkite-api

Original

Translation

Buildkite API

Buildkite API

Quick Start

快速入门

Authentication and access

认证与访问

REST API

REST API

Capability map

功能映射

Pagination

分页

Pipeline creation

流水线创建

Organization administration

组织管理

Hosted resources

托管资源

Artifact filtering

制品过滤

Job and agent diagnostics

作业与Agent诊断

GraphQL API

GraphQL API

Webhooks

Webhooks

Common Mistakes

常见错误

Additional Resources

附加资源

Reference Files

参考文件

Further Reading

扩展阅读