buildkite-api

Buildkite API

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

如需在终端中交互式执行 API 调用，请参阅 buildkite-cli 技能中的 bk api 命令。使用 Buildkite MCP 服务时，对于受支持的读取和操作，优先使用专用工具。

快速开始

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

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 查询选定的嵌套字段：

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'

身份验证和访问权限

将个人 API 访问令牌作为 bearer token 传递。将令牌的作用范围限定为所需组织，并仅授予最低限度的权限范围。HTTP 404 可能表示资源不存在或不可用：某些受权限或功能限制的资源会有意不透露其是否存在。

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

作用范围是必要条件，但并非总是充分条件。应将 403 和受权限限制的 404 响应视为访问或可用性边界，而不是尝试其他负载或端点的依据。如有可观察到的组织状态和已知的调用者上下文，请据此判断；否则，请说明所需的角色、权限或功能，并请管理员进行核实。完整目录请参阅 API 令牌作用范围。

REST API

将 https://api.buildkite.com/v2 用作基础 URL，并为 JSON 请求正文设置 Content-Type: application/json。大多数组织范围的资源都以 /organizations/{org.slug} 开头；用户、组织列表和其他顶层资源除外。

读取构建元数据和状态时，默认使用 exclude_jobs=true&exclude_pipeline=true。只有在需要作业详情时，才从 Jobs API 获取作业。

能力映射

使用此映射选择资源类别，然后打开链接的参考文档，查看确切的架构和响应行为。

类别	协议和访问方式	范围、权限或门槛	关键边界和文档
组织设置	REST 读取/写入	read_organization_settings/write_organization_settings；组织管理员；字段门槛	写入前先读取；API 允许列表变更可能会导致调用方无法访问。API 设置 和流水线设置
审计事件	REST 只读	read_audit_events；组织管理员；Enterprise	分页游标独立于设置。审计事件
成员和邀请	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；如果不存在团队，可能会创建 Everyone；REST 不提供读取或禁用路由。团队
仓库连接	REST 只读	read_organization_repository_connections；组织管理员；提供商支持	连接不支持 API 修改；不受支持的发现提供商会返回 422。连接 和发现
流水线设置	REST 读取/写入	read_pipelines/write_pipelines；流水线访问权限	创建时会同时进行验证和修改；REST 不提供试运行。流水线
通知服务	REST 读取/写入生命周期	read_notification_services/write_notification_services；组织管理员或 Manage Notification Services	OAuth Slack Workspace 和 Linear 需要先在浏览器中授权；保留未提供的新密钥字段。通知服务
入站 GitHub 处理	REST 读取/写入	read_pipelines/write_pipelines；Full Access；提供商和功能门槛	处理控制不会注册仓库 webhook，也不会配置 GitHub App。流水线
构建生命周期	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 访问权限；删除构件需要在其所属流水线上拥有 Build & Read 或更高级别的访问权限	分页前先筛选，并明确确认删除操作。构件

分页

大多数 REST 列表响应会返回数组和 HTTP Link 标头。请遵循标记为 rel="next" 的 URL，而不要自行构造页码。在初始请求中保留查询筛选条件，之后使用服务端提供的下一页 URL。

Jobs API、邀请、通知服务和审计事件使用基于游标的请求体。从 .items 读取记录，并持续跟随 .links.next，直到其值为 null。审计事件还会提供 Link 标头。不要对这些请求体结构运行仅适用于数组的 jq 筛选器。

REST 请求会同时消耗组织配额和每用户配额。遇到 429 时，请停止请求，直到相应的 RateLimit-Reset 或 RateLimit-User-Reset 时间窗口结束；不要紧密循环重试。远程 Buildkite MCP 服务请求使用单独的每用户限制，而本地 MCP 服务请求会消耗组织 REST 配额。

创建流水线

默认在 REST configuration 字符串中使用流水线 YAML。选定集群后，请包含 cluster_id。如果组织允许未关联集群的流水线，则可以省略该字段；否则服务端会返回 422 和 Cluster must be specified。不要仅因为缺少 cluster_id 就在客户端拒绝创建。用户或组织工作流选定模板时，请使用 pipeline_template_uuid。仅在确认属于旧版可视化步骤工作流时，才发送可视化 steps 数组；在创建之前，没有公开的组织字段可以可靠地判断是否属于该模式。

创建请求会同时执行服务端验证和数据变更。必要时可以先在本地验证 YAML，但不要将本地架构验证描述为仓库访问、提供商配置、权限或服务端创建限制一定能通过的证明。遇到 422 验证响应时，请如实报告，不要悄悄改用其他步骤来源重试。

组织管理

变更前读取设置，仅比较受管理的字段，并发送范围最小的受支持更新。保留未知字段和受功能开关控制的字段。对于 API 设置，应将允许列表变更视为可能导致无法访问的操作：验证调用方的源地址，保留回滚途径，并避免并发写入设置。

邀请和成员资格是不同的状态。列出邀请以核对待处理请求；任何邀请状态都应使用 show 查看；仅对撤销待处理邀请使用 DELETE。批量创建邀请支持角色、SSO 模式和团队分配，但会对整个请求进行原子验证。验证失败时，不会创建任何请求中的邀请。

只有在读取该成员资格后，才能使用 PATCH /organizations/{org.slug}/members/{user.uuid} 更新现有成员。该请求仅接受 role（admin 或 member）和 sso_mode（optional 或 required），需要 write_organizations 和组织管理员权限，且无法更新调用方自己的成员资格。只发送计划变更的字段；尚未成为成员的人员应通过邀请添加。

仅当请求的结果明确需要基于团队的权限时，才启用 Teams。不要通过执行变更来探测是否可用。需要了解当前状态时，通过 GraphQL 读取 Organization.isTeamsEnabled；如果 Teams 已禁用，请先说明计划和权限要求，再启用它。

托管资源

更改托管缓存行为前，先使用 read_clusters 读取集群。对于拥有集群管理权限的调用方，集群 show 响应会包含 hosted_git_mirror_enabled 和 hosted_container_cache_enabled；没有该权限的调用方不会收到这些字段，因此不要将字段缺失解读为 false。使用 write_clusters 和集群管理权限，通过 PUT /organizations/{org.slug}/clusters/{id} 更新其中任一布尔值。仅托管集群支持更改这些值；非托管集群会返回 422。

制品筛选

在分页前，对构建级和作业级制品列表应用 state 和 path 筛选。没有 * 的路径表示精确匹配；仅在需要 glob 匹配时才添加 *。对路径和状态筛选器进行 URL 编码，不要只在本地筛选单页结果。

使用制品 ID 下载时需通过 curl -L，因为下载端点会重定向。REST 删除需要 write_artifacts；REST 和 GraphQL 删除还需要对制品所在的流水线拥有 Build & Read 或更高权限。REST 接受制品 UUID，可通过 /organizations/{org.slug}/jobs/{job.id}/artifacts/{id} 或完整限定的流水线／构建／作业路由访问。构建级制品列表路由没有对应的删除操作。GraphQL artifactDelete 接受制品全局 ID，并需要 GraphQL API 访问权限。无论使用哪种方式，都必须先获得明确确认，绝不要将筛选发现结果转化为自动删除循环。

如果组织使用客户管理的制品存储，删除 Buildkite 制品不会移除底层对象。不要推断存储后端，也不要自动删除外部对象；请查阅组织的制品存储配置和删除操作手册。

作业和 Agent 诊断

已知构建编号后，直接查询作业。优先使用服务器端的 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 丢失可以解释任务为何中断，但不能证明外部部署或写入未完成。

取消作业

使用 PUT /organizations/{org.slug}/jobs/{job.id}/cancel 取消单个命令作业，或使用嵌套路由 PUT /organizations/{org.slug}/pipelines/{pipeline.slug}/builds/{build.number}/jobs/{job.id}/cancel。不发送请求正文，并预期返回标准作业 JSON；该端点需要 write_builds。其他作业不会被直接取消，但除非该步骤设置了 soft_fail，否则被取消的作业会导致构建失败，并可能在其他步骤触发快速失败（cancel_on_build_failing），因此不要承诺其他作业不受影响。若要停止所有尚未完成的作业，请改用 PUT .../builds/{build.number}/cancel 取消构建。

只有处于 scheduled、reserved、assigned、accepted 或 running 状态的命令作业才能取消；其他状态会返回 422 和需要报告的原因，不应重试。处于 running 状态的作业会变为 canceling，直到其 Agent 完成；REST API 没有强制取消选项，因此不要将 200 视为已终止。请先与用户确认作业 UUID、名称和状态：中断命令可能留下部分外部副作用，而恢复操作意味着重试并创建新作业。绝不要通过循环取消作业来近似取消构建。有关状态、错误以及取消并轮询的脚本，请参阅 references/patterns.md。

GraphQL API

使用 https://graphql.buildkite.com/v1。当类型化查询能够避免多次嵌套 REST 读取，或其变更形状更适合工作流时，优先使用 GraphQL。GraphQL 访问令牌使用 Enable GraphQL API Access 权限，而不是细粒度 REST 作用域。变更输入请使用全局节点 ID，除非架构明确要求，否则不要使用 REST UUID 或流水线 slug。

场景	优先使用	原因
触发构建	REST	请求体和标识符都很直观
筛选构建、作业或制品	REST	专门设计的服务器端筛选和分页
读取审计事件	REST	专用的只读审计端点和游标响应
获取选定的嵌套关联	GraphQL	类型化字段选择可避免多次调用
删除制品	REST 或 GraphQL	REST 接受制品 UUID；artifactDelete 接受全局 ID。两者都遵循相同的确认要求和存储注意事项
使用其他仅限 GraphQL 的变更	GraphQL	遵循当前架构和变更专属权限

请同时检查顶层 HTTP 错误和 GraphQL errors 数组。即使响应状态为 200，仍可能包含操作错误或部分数据。分页、全局 ID 和制品删除请参阅 references/graphql-reference.md。

Webhook

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

• 通过组织通知服务 REST 生命周期，创建并管理出站 Webhook，作为通知服务使用。
• 使用流水线的 github-webhooks REST 资源，启用或禁用 Buildkite 对入站 GitHub 事件的处理。
• 对符合条件的 GitHub App 流水线，使用 POST /pipelines/{slug}/webhook 注册 SCM Webhook；随后 Buildkite 会创建提供方侧的投递。此操作与处理开关相互独立。
• 配置组织级 GitHub App 连接属于单独的浏览器和组织管理工作流。

对于出站处理程序，请根据 X-Buildkite-Event 或载荷中的 event 分支处理。不要假设每个事件的构建、作业、流水线和发送方对象都具有相同结构。请尽快确认收到，以幂等方式处理，并参阅 webhooks 参考，了解所选事件和当前的身份验证字段。

有关通知服务生命周期和入站 GitHub 投递诊断，请参阅 references/webhooks.md。

常见错误

错误	结果	修正方法
认为 cluster_id 总是必填或总是可选	客户端拒绝有效的非集群创建请求，或仅限集群的创建请求返回 422	指定一个已选集群；否则让服务端判断组织是否允许创建非集群流水线
创建 REST 流水线时未提供有效的步骤来源	创建请求返回 422	根据实际情况使用 YAML configuration、旧版可视化 steps 或 pipeline_template_uuid；将创建验证视为会产生变更的操作
未先读取设置就更新	功能受限的字段被覆盖，或 IP 允许列表导致自动化流程无法访问	读取设置、比较受管理字段，并保留经过测试的回滚路径
将邀请误认为已生效的成员资格	自动化流程在接受邀请或完成配置之前就假定已有访问权限	将待处理邀请与成员分别跟踪
认为仓库连接有 CRUD 端点	自动化流程尝试不受支持的变更	仅使用列表、查看和仓库发现功能
因 GET 响应未返回通知密钥而替换密钥	不必要地轮换了可用凭据	考虑各提供商对密钥响应的不同处理方式，并保留响应中未包含的密钥
混淆出站通知 Webhook 与入站 GitHub 处理	更改了错误的端点，仓库事件仍无法正常传递	分别确认通知服务、处理开关、仓库注册和应用连接
读取一页后再筛选工件	漏掉后续页面中的匹配工件	在分页前于 API 请求中应用 state 和 path
为停止单个作业而取消整个构建，或循环取消作业以停止构建	其他无关作业也被停止，或两次调用之间创建的作业仍在运行	对一个已确认的作业使用作业取消路由；要停止整个构建则使用构建取消路由
仅因信号或 Agent 时序表明发生中断就重试	非幂等的外部操作可能执行两次	重试前检查日志、副作用和重试历史

其他资源

参考文件

• references/graphql-reference.md — GraphQL 分页、全局 ID、常见查询和安全删除工件
• references/webhooks.md — 通知服务生命周期，以及出站与入站 Webhook 概念之间的界限
• references/patterns.md — 可直接复制粘贴的 REST 工作流，涵盖审计清单、从仓库到流水线的配置、通知协调、单个作业取消和诊断

延伸阅读

• Buildkite REST API 参考
• Buildkite GraphQL API 文档
• Buildkite Webhook 事件
• API 身份验证与令牌管理
• 面向大模型的 Buildkite 文档