REST API 现在已版本化。 更多信息，请参阅“关于 API 版本控制”。

提交状态的 REST API 端点

使用 REST API 与提交状态进行交互。

关于提交状态

您可以使用 REST API 允许外部服务使用error、failure、pending 或 success 状态标记提交，这些状态随后会反映在包含这些提交的拉取请求中。状态还可以包含可选的description 和 target_url，我们强烈建议您提供它们，因为它们使 GitHub UI 中的状态更有用。

例如，一个常见用途是持续集成服务使用状态将提交标记为通过或失败的构建。target_url 将是构建输出的完整 URL，description 将是构建发生情况的高级摘要。

状态可以包含一个context 来指示哪个服务提供了该状态。例如，您的持续集成服务可能会推送带有ci 上下文的 状态，而安全审计工具可能会推送带有security 上下文的 状态。然后，您可以使用 REST API 获取特定引用的组合状态 来检索提交的整个状态。

请注意，repo:status OAuth 范围 授予对状态的定向访问权限，**而不会**同时授予对仓库代码的访问权限，而repo 范围则同时授予对代码和状态的权限。

如果您正在开发 GitHub 应用并希望提供有关外部服务的更详细信息，您可能希望使用 REST API 来管理检查。更多信息，请参阅“提交状态的 REST API 端点”。

获取特定引用的组合状态

拥有仓库拉取访问权限的用户可以访问给定引用提交状态的组合视图。引用可以是 SHA、分支名称或标签名称。

此外，还会返回组合的state。state 之一是

  • 如果任何上下文报告为error 或 failure，则为failure
  • 如果没有状态或上下文为pending，则为pending
  • 如果所有上下文的最新状态均为success，则为success

“获取特定引用的组合状态”的细粒度访问令牌

此端点适用于以下细粒度令牌类型:

细粒度令牌必须具有以下权限集

  • “提交状态”仓库权限（读取）

如果仅请求公共资源，则无需身份验证或上述权限即可使用此端点。

“获取特定引用的组合状态”的参数

标头
accept 字符串

建议设置为application/vnd.github+json。

路径参数
owner 字符串 必需

仓库的帐户所有者。名称不区分大小写。

repo 字符串 必需

不包含.git 扩展名的仓库名称。名称不区分大小写。

ref 字符串 必需

提交引用。可以是提交 SHA、分支名称 (heads/BRANCH_NAME) 或标签名称 (tags/TAG_NAME)。更多信息，请参阅 Git 文档中的“Git 引用”。

查询参数
per_page 整数

每页的结果数（最大 100）。更多信息，请参阅“在 REST API 中使用分页”。

默认值： 30

page 整数

要获取的结果的页码。更多信息，请参阅“在 REST API 中使用分页”。

默认值： 1

“获取特定引用的组合状态”的 HTTP 响应状态代码

状态代码描述
200

OK

404

资源未找到

“获取特定引用的组合状态”的代码示例

请求示例

get/repos/{owner}/{repo}/commits/{ref}/status
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/commits/REF/status

响应

状态：200
{ "state": "success", "statuses": [ { "url": "https://api.github.com/repos/octocat/Hello-World/statuses/6dcb09b5b57875f334f61aebed695e2e4193db5e", "avatar_url": "https://github.com/images/error/hubot_happy.gif", "id": 1, "node_id": "MDY6U3RhdHVzMQ==", "state": "success", "description": "构建已成功完成", "target_url": "https://ci.example.com/1000/output", "context": "continuous-integration/jenkins", "created_at": "2012-07-20T01:19:13Z", "updated_at": "2012-07-20T01:19:13Z" }, { "url": "https://api.github.com/repos/octocat/Hello-World/statuses/6dcb09b5b57875f334f61aebed695e2e4193db5e", "avatar_url": "https://github.com/images/error/other_user_happy.gif", "id": 2, "node_id": "MDY6U3RhdHVzMg==", "state": "success", "description": "测试已成功完成", "target_url": "https://ci.example.com/2000/output", "context": "security/brakeman", "created_at": "2012-08-20T01:19:13Z", "updated_at": "2012-08-20T01:19:13Z" } ], "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e", "total_count": 2, "repository": { "id": 1296269, "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5", "name": "Hello-World", "full_name": "octocat/Hello-World", "owner": { "login": "octocat", "id": 1, "node_id": "MDQ6VXNlcjE=", "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "", "url": "https://api.github.com/users/octocat", "html_url": "https://github.com/octocat", "followers_url": "https://api.github.com/users/octocat/followers", "following_url": "https://api.github.com/users/octocat/following{/other_user}", "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}", "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}", "subscriptions_url": "https://api.github.com/users/octocat/subscriptions", "organizations_url": "https://api.github.com/users/octocat/orgs", "repos_url": "https://api.github.com/users/octocat/repos", "events_url": "https://api.github.com/users/octocat/events{/privacy}", "received_events_url": "https://api.github.com/users/octocat/received_events", "type": "User", "site_admin": false }, "private": false, "html_url": "https://github.com/octocat/Hello-World", "description": "这是你的第一个仓库！", "fork": false, "url": "https://api.github.com/repos/octocat/Hello-World", "archive_url": "https://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}", "assignees_url": "https://api.github.com/repos/octocat/Hello-World/assignees{/user}", "blobs_url": "https://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}", "branches_url": "https://api.github.com/repos/octocat/Hello-World/branches{/branch}", "collaborators_url": "https://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}", "comments_url": "https://api.github.com/repos/octocat/Hello-World/comments{/number}", "commits_url": "https://api.github.com/repos/octocat/Hello-World/commits{/sha}", "compare_url": "https://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}", "contents_url": "https://api.github.com/repos/octocat/Hello-World/contents/{+path}", "contributors_url": "https://api.github.com/repos/octocat/Hello-World/contributors", "deployments_url": "https://api.github.com/repos/octocat/Hello-World/deployments", "downloads_url": "https://api.github.com/repos/octocat/Hello-World/downloads", "events_url": "https://api.github.com/repos/octocat/Hello-World/events", "forks_url": "https://api.github.com/repos/octocat/Hello-World/forks", "git_commits_url": "https://api.github.com/repos/octocat/Hello-World/git/commits{/sha}", "git_refs_url": "https://api.github.com/repos/octocat/Hello-World/git/refs{/sha}", "git_tags_url": "https://api.github.com/repos/octocat/Hello-World/git/tags{/sha}", "git_url": "git:github.com/octocat/Hello-World.git", "issue_comment_url": "https://api.github.com/repos/octocat/Hello-World/issues/comments{/number}", "issue_events_url": "https://api.github.com/repos/octocat/Hello-World/issues/events{/number}", "issues_url": "https://api.github.com/repos/octocat/Hello-World/issues{/number}", "keys_url": "https://api.github.com/repos/octocat/Hello-World/keys{/key_id}", "labels_url": "https://api.github.com/repos/octocat/Hello-World/labels{/name}", "languages_url": "https://api.github.com/repos/octocat/Hello-World/languages", "merges_url": "https://api.github.com/repos/octocat/Hello-World/merges", "milestones_url": "https://api.github.com/repos/octocat/Hello-World/milestones{/number}", "notifications_url": "https://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}", "pulls_url": "https://api.github.com/repos/octocat/Hello-World/pulls{/number}", "releases_url": "https://api.github.com/repos/octocat/Hello-World/releases{/id}", "ssh_url": "[email protected]:octocat/Hello-World.git", "stargazers_url": "https://api.github.com/repos/octocat/Hello-World/stargazers", "statuses_url": "https://api.github.com/repos/octocat/Hello-World/statuses/{sha}", "subscribers_url": "https://api.github.com/repos/octocat/Hello-World/subscribers", "subscription_url": "https://api.github.com/repos/octocat/Hello-World/subscription", "tags_url": "https://api.github.com/repos/octocat/Hello-World/tags", "teams_url": "https://api.github.com/repos/octocat/Hello-World/teams", "trees_url": "https://api.github.com/repos/octocat/Hello-World/git/trees{/sha}", "hooks_url": "http://api.github.com/repos/octocat/Hello-World/hooks" }, "commit_url": "https://api.github.com/repos/octocat/Hello-World/6dcb09b5b57875f334f61aebed695e2e4193db5e", "url": "https://api.github.com/repos/octocat/Hello-World/6dcb09b5b57875f334f61aebed695e2e4193db5e/status" }

列出引用提交状态

拥有仓库拉取访问权限的用户可以查看给定引用的提交状态。该引用可以是 SHA、分支名称或标签名称。状态按反向时间顺序返回。列表中的第一个状态将是最新的状态。

此资源也可通过旧版路由访问：GET /repos/:owner/:repo/statuses/:ref。

“列出引用提交状态”的细粒度访问令牌

此端点适用于以下细粒度令牌类型:

细粒度令牌必须具有以下权限集

  • “提交状态”仓库权限（读取）

如果仅请求公共资源，则无需身份验证或上述权限即可使用此端点。

“列出引用提交状态”的参数

标头
accept 字符串

建议设置为application/vnd.github+json。

路径参数
owner 字符串 必需

仓库的帐户所有者。名称不区分大小写。

repo 字符串 必需

不包含.git 扩展名的仓库名称。名称不区分大小写。

ref 字符串 必需

提交引用。可以是提交 SHA、分支名称 (heads/BRANCH_NAME) 或标签名称 (tags/TAG_NAME)。更多信息，请参阅 Git 文档中的“Git 引用”。

查询参数
per_page 整数

每页的结果数（最大 100）。更多信息，请参阅“在 REST API 中使用分页”。

默认值： 30

page 整数

要获取的结果的页码。更多信息，请参阅“在 REST API 中使用分页”。

默认值： 1

“列出引用提交状态”的HTTP响应状态代码

状态代码描述
200

OK

301

永久移动

“列出引用提交状态”的代码示例

请求示例

get/repos/{owner}/{repo}/commits/{ref}/statuses
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/commits/REF/statuses

响应

状态：200
[ { "url": "https://api.github.com/repos/octocat/Hello-World/statuses/6dcb09b5b57875f334f61aebed695e2e4193db5e", "avatar_url": "https://github.com/images/error/hubot_happy.gif", "id": 1, "node_id": "MDY6U3RhdHVzMQ==", "state": "success", "description": "构建已成功完成", "target_url": "https://ci.example.com/1000/output", "context": "continuous-integration/jenkins", "created_at": "2012-07-20T01:19:13Z", "updated_at": "2012-07-20T01:19:13Z", "creator": { "login": "octocat", "id": 1, "node_id": "MDQ6VXNlcjE=", "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "", "url": "https://api.github.com/users/octocat", "html_url": "https://github.com/octocat", "followers_url": "https://api.github.com/users/octocat/followers", "following_url": "https://api.github.com/users/octocat/following{/other_user}", "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}", "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}", "subscriptions_url": "https://api.github.com/users/octocat/subscriptions", "organizations_url": "https://api.github.com/users/octocat/orgs", "repos_url": "https://api.github.com/users/octocat/repos", "events_url": "https://api.github.com/users/octocat/events{/privacy}", "received_events_url": "https://api.github.com/users/octocat/received_events", "type": "User", "site_admin": false } } ]

创建提交状态

拥有仓库推送访问权限的用户可以为给定的 SHA 创建提交状态。

注意：每个仓库中每个sha和context最多有1000个状态限制。尝试创建超过1000个状态将导致验证错误。

“创建提交状态”的细粒度访问令牌

此端点适用于以下细粒度令牌类型:

细粒度令牌必须具有以下权限集

  • “提交状态”仓库权限（写入）

“创建提交状态”的参数

标头
accept 字符串

建议设置为application/vnd.github+json。

路径参数
owner 字符串 必需

仓库的帐户所有者。名称不区分大小写。

repo 字符串 必需

不包含.git 扩展名的仓库名称。名称不区分大小写。

sha 字符串 必需
主体参数
state 字符串 必需

状态的状态。

可以是以下之一：error，failure，pending，success

target_url 字符串或null

与该状态关联的目标URL。此URL将从GitHub UI链接，允许用户轻松查看状态的来源。
例如，如果您的持续集成系统正在发布构建状态，则需要为此特定SHA提供构建输出的深层链接
http://ci.example.com/user/repo/build/sha

description 字符串或null

状态的简短描述。

context 字符串

一个字符串标签，用于将此状态与其他系统的状态区分开来。此字段不区分大小写。

默认值：default

“创建提交状态”的HTTP响应状态代码

状态代码描述
201

已创建

“创建提交状态”的代码示例

请求示例

post/repos/{owner}/{repo}/statuses/{sha}
curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/statuses/SHA \ -d '{"state":"success","target_url":"https://example.com/build/status","description":"构建成功！","context":"continuous-integration/jenkins"}'

响应

状态：201
{ "url": "https://api.github.com/repos/octocat/Hello-World/statuses/6dcb09b5b57875f334f61aebed695e2e4193db5e", "avatar_url": "https://github.com/images/error/hubot_happy.gif", "id": 1, "node_id": "MDY6U3RhdHVzMQ==", "state": "success", "description": "构建已成功完成", "target_url": "https://ci.example.com/1000/output", "context": "continuous-integration/jenkins", "created_at": "2012-07-20T01:19:13Z", "updated_at": "2012-07-20T01:19:13Z", "creator": { "login": "octocat", "id": 1, "node_id": "MDQ6VXNlcjE=", "avatar_url": "https://github.com/images/error/octocat_happy.gif", "gravatar_id": "", "url": "https://api.github.com/users/octocat", "html_url": "https://github.com/octocat", "followers_url": "https://api.github.com/users/octocat/followers", "following_url": "https://api.github.com/users/octocat/following{/other_user}", "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}", "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}", "subscriptions_url": "https://api.github.com/users/octocat/subscriptions", "organizations_url": "https://api.github.com/users/octocat/orgs", "repos_url": "https://api.github.com/users/octocat/repos", "events_url": "https://api.github.com/users/octocat/events{/privacy}", "received_events_url": "https://api.github.com/users/octocat/received_events", "type": "User", "site_admin": false } }