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

提交状态的 REST API 端点

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

关于提交状态

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

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

状态可以包括一个 context 来指示提供该状态的服务。例如，你可以让你的持续集成服务推送状态，其中 context 为 ci，而安全审计工具推送状态，其中 context 为 security。然后，你可以使用 REST API 获取特定引用的组合状态以检索提交的整个状态。

请注意，repo:status OAuth 范围授予对状态的定向访问权限，不授予对存储库代码的访问权限，而 repo 范围授予对代码和状态的访问权限。

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

获取特定引用合并的状态

在存储库中具有拉取权限的用户可以访问给定引用提交状态的合并视图。引用可以是 SHA、分支名称或标签名称。

此外，还返回合并的 state。state 之一

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

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

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

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

“提交状态”存储库权限（读取）

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

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

标头
名称、类型、描述
`accept` string 建议设置为 `application/vnd.github+json`。

路径参数
名称、类型、描述
`owner` string 必需存储库的帐户所有者。名称不区分大小写。
`repo` string 必需存储库的名称，不带 `.git` 扩展名。名称不区分大小写。
`ref` string 必需提交引用。可以是提交 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": "Build has completed successfully",
      "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": "Testing has completed successfully",
      "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": "This your first repo!",
    "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"
}

列出引用的提交状态

拥有存储库中拉取权限的用户可以查看给定 ref 的提交状态。ref 可以是 SHA、分支名称或标签名称。状态按时间倒序返回。列表中的第一个状态将是最新状态。

此资源还可以通过传统路由获取：GET /repos/:owner/:repo/statuses/:ref。

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

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

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

“提交状态”存储库权限（读取）

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

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

标头
名称、类型、描述
`accept` string 建议设置为 `application/vnd.github+json`。

路径参数
名称、类型、描述
`owner` string 必需存储库的帐户所有者。名称不区分大小写。
`repo` string 必需存储库的名称，不带 `.git` 扩展名。名称不区分大小写。
`ref` string 必需提交引用。可以是提交 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` string 建议设置为 `application/vnd.github+json`。

路径参数
名称、类型、描述
`owner` string 必需存储库的帐户所有者。名称不区分大小写。
`repo` string 必需存储库的名称，不带 `.git` 扩展名。名称不区分大小写。
`sha` 字符串必需

正文参数
名称、类型、描述
`状态` 字符串必需状态的状态。可以为以下之一: `错误`, `失败`, `待处理`, `成功`
`目标 URL` 字符串或 null 要与此状态关联的目标 URL。此 URL 将从 GitHub UI 链接，以允许用户轻松查看状态的来源。例如，如果你的持续集成系统正在发布构建状态，则需要为此特定 SHA 提供构建输出的深度链接 `http://ci.example.com/user/repo/build/sha`
`说明` 字符串或 null 状态的简短说明。
`上下文` 字符串一个字符串标签，用于区分此状态与其他系统的状态。此字段不区分大小写。默认: `默认`

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

状态代码	说明
`201`	已创建

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

请求示例

发布/repos/{所有者}/{仓库}/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 } }