Skip to main content
REST API теперь версия. Дополнительные сведения см. в разделе "О управлении версиями API".

Конечные точки REST API для состояния фиксации

Используйте REST API для взаимодействия с состояниями фиксации.

Сведения о состоянии фиксации

С помощью REST API можно разрешить внешним службам пометить фиксации с errorпомощью состояния , failure``pendingили success состояния, которое затем отражается в запросах на вытягивание с участием этих фиксаций. Состояния также могут включать дополнительные параметры description и target_url, поэтому мы настоятельно рекомендуем их указывать — с ними состояния будут еще более полезными в пользовательском интерфейсе GitHub.

Например, службы непрерывной интеграции с помощью состояний показывают передачу фиксаций или сбои сборки. Параметр target_url — это полный URL-адрес выходных данных сборки, а description — краткая сводка того, что произошло со сборкой.

Состояния могут содержать context, который показывает, какая служба предоставляет это состояние. Например, ваша служба непрерывной интеграции может передавать состояния с контекстом ci, а средство аудита безопасности — с контекстом security. Затем можно использовать REST API для получения объединенного состояния для определенной ссылки , чтобы получить все состояние фиксации.

Обратите внимание на то, что repo:status область OAuth предоставляет целевой доступ к состояниям без доступа к коду репозитория, а область repo — и к коду, и к состояниям.

Если вы разрабатываете приложение GitHub и хотите предоставить более подробную информацию о внешней службе, вы можете использовать REST API для управления проверка. Дополнительные сведения см. в разделе Конечные точки REST API для проверка.

Get the combined status for a specific reference

Users with pull access in a repository can access a combined view of commit statuses for a given ref. The ref can be a SHA, a branch name, or a tag name.

Additionally, a combined state is returned. The state is one of:

  • failure if any of the contexts report as error or failure
  • pending if there are no statuses or a context is pending
  • success if the latest status for all contexts is success

Подробные маркеры доступа для "Get the combined status for a specific reference

Эта конечная точка работает со следующими точными типами маркеров:

Маркер с точной детализацией должен иметь следующий набор разрешений.:

  • "Commit statuses" repository permissions (read)

Эту конечную точку можно использовать без проверки подлинности или указанных выше разрешений, если запрашиваются только общедоступные ресурсы.

Параметры для "Get the combined status for a specific reference"

Заголовки
Имя., Тип, Description
accept string

Setting to application/vnd.github+json is recommended.

Параметры пути
Имя., Тип, Description
owner string Обязательное поле

The account owner of the repository. The name is not case sensitive.

repo string Обязательное поле

The name of the repository without the .git extension. The name is not case sensitive.

ref string Обязательное поле

The commit reference. Can be a commit SHA, branch name (heads/BRANCH_NAME), or tag name (tags/TAG_NAME). For more information, see "Git References" in the Git documentation.

Параметры запроса
Имя., Тип, Description
per_page integer

The number of results per page (max 100). For more information, see "Using pagination in the REST API."

По умолчанию.: 30

page integer

The page number of the results to fetch. For more information, see "Using pagination in the REST API."

По умолчанию.: 1

Коды состояния http-ответа для "Get the combined status for a specific reference"

Код состоянияОписание
200

OK

404

Resource not found

Примеры кода для "Get the combined status for a specific reference"

Пример запроса

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

Response

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": "git@github.com: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" }

List commit statuses for a reference

Users with pull access in a repository can view commit statuses for a given ref. The ref can be a SHA, a branch name, or a tag name. Statuses are returned in reverse chronological order. The first status in the list will be the latest one.

This resource is also available via a legacy route: GET /repos/:owner/:repo/statuses/:ref.

Подробные маркеры доступа для "List commit statuses for a reference

Эта конечная точка работает со следующими точными типами маркеров:

Маркер с точной детализацией должен иметь следующий набор разрешений.:

  • "Commit statuses" repository permissions (read)

Эту конечную точку можно использовать без проверки подлинности или указанных выше разрешений, если запрашиваются только общедоступные ресурсы.

Параметры для "List commit statuses for a reference"

Заголовки
Имя., Тип, Description
accept string

Setting to application/vnd.github+json is recommended.

Параметры пути
Имя., Тип, Description
owner string Обязательное поле

The account owner of the repository. The name is not case sensitive.

repo string Обязательное поле

The name of the repository without the .git extension. The name is not case sensitive.

ref string Обязательное поле

The commit reference. Can be a commit SHA, branch name (heads/BRANCH_NAME), or tag name (tags/TAG_NAME). For more information, see "Git References" in the Git documentation.

Параметры запроса
Имя., Тип, Description
per_page integer

The number of results per page (max 100). For more information, see "Using pagination in the REST API."

По умолчанию.: 30

page integer

The page number of the results to fetch. For more information, see "Using pagination in the REST API."

По умолчанию.: 1

Коды состояния http-ответа для "List commit statuses for a reference"

Код состоянияОписание
200

OK

301

Moved permanently

Примеры кода для "List commit statuses for a reference"

Пример запроса

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

Response

Status: 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": "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", "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 } } ]

Create a commit status

Users with push access in a repository can create commit statuses for a given SHA.

Note: there is a limit of 1000 statuses per sha and context within a repository. Attempts to create more than 1000 statuses will result in a validation error.

Подробные маркеры доступа для "Create a commit status

Эта конечная точка работает со следующими точными типами маркеров:

Маркер с точной детализацией должен иметь следующий набор разрешений.:

  • "Commit statuses" repository permissions (write)

Параметры для "Create a commit status"

Заголовки
Имя., Тип, Description
accept string

Setting to application/vnd.github+json is recommended.

Параметры пути
Имя., Тип, Description
owner string Обязательное поле

The account owner of the repository. The name is not case sensitive.

repo string Обязательное поле

The name of the repository without the .git extension. The name is not case sensitive.

sha string Обязательное поле
Параметры запроса
Имя., Тип, Description
state string Обязательное поле

The state of the status.

Возможные значения: error, failure, pending, success

target_url string or null

The target URL to associate with this status. This URL will be linked from the GitHub UI to allow users to easily see the source of the status.
For example, if your continuous integration system is posting build status, you would want to provide the deep link for the build output for this specific SHA:
http://ci.example.com/user/repo/build/sha

description string or null

A short description of the status.

context string

A string label to differentiate this status from the status of other systems. This field is case-insensitive.

По умолчанию.: default

Коды состояния http-ответа для "Create a commit status"

Код состоянияОписание
201

Created

Примеры кода для "Create a commit status"

Пример запроса

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":"The build succeeded!","context":"continuous-integration/jenkins"}'

Response

Status: 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": "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", "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 } }