Skip to main content
Nous publions des mises à jour fréquentes de notre documentation, et la traduction de cette page peut encore être en cours. Pour obtenir les informations les plus actuelles, consultez la documentation anglaise.
L’API REST est maintenant versionnée. Pour plus d’informations, consultez « À propos des versions de l’API ».

États de validation

Utilisez l’API REST pour interagir avec les états de validation.

À propos des états de validation

Vous pouvez utiliser l’API REST pour permettre aux services externes de marquer les validations avec un état error, failure, pending ou success, qui est ensuite reflété dans les demandes de tirage impliquant ces validations. Les états peuvent également inclure description et target_url en option ; nous vous recommandons vivement de les fournir, car ils rendent les états beaucoup plus utiles dans l’interface utilisateur GitHub.

Par exemple, une utilisation courante est de permettre aux services d’intégration continue de marquer les validations comme des builds validées ou ayant échoué à l’aide de l’état. Le target_url serait l’URL complète de la sortie de la build, et description le résumé de haut niveau de ce qui s’est passé avec la build.

Les états peuvent inclure un context pour indiquer quel service fournit cet état. Par exemple, vous pouvez avoir vos états push de service d’intégration continue avec un contexte de ci, et des états push d’outil d’audit de sécurité avec un contexte de security. Vous pouvez ensuite utiliser l’API REST pour Obtenir l’état combiné d’une référence spécifique pour récupérer l’état entier d’une validation.

Notez que l’étendue OAuth repo:status accorde un accès ciblé aux états sans accorder également l’accès au code du référentiel, tandis que l’étendue repo accorde l’autorisation au code ainsi qu’aux états.

Si vous développez une application GitHub et souhaitez fournir des informations plus détaillées sur un service externe, vous pouvez utiliser l’API REST pour gérer les vérifications. Pour plus d’informations, consultez « Vérifications ».

Get the combined status for a specific reference

Compatible avec GitHub Apps

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

Paramètres

En-têtes
Nom, Type, Description
acceptstring

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

Paramètres de chemin d’accès
Nom, Type, Description
ownerstringObligatoire

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

repostringObligatoire

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

refstringObligatoire

ref parameter

Paramètres de requête
Nom, Type, Description
per_pageinteger

The number of results per page (max 100).

Default: 30

pageinteger

Page number of the results to fetch.

Default: 1

Codes de statut de réponse HTTP

Code d’étatDescription
200

OK

404

Resource not found

Exemples de code

get/repos/{owner}/{repo}/commits/{ref}/status
curl \ -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

Compatible avec GitHub Apps

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.

Paramètres

En-têtes
Nom, Type, Description
acceptstring

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

Paramètres de chemin d’accès
Nom, Type, Description
ownerstringObligatoire

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

repostringObligatoire

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

refstringObligatoire

ref parameter

Paramètres de requête
Nom, Type, Description
per_pageinteger

The number of results per page (max 100).

Default: 30

pageinteger

Page number of the results to fetch.

Default: 1

Codes de statut de réponse HTTP

Code d’étatDescription
200

OK

301

Moved permanently

Exemples de code

get/repos/{owner}/{repo}/commits/{ref}/statuses
curl \ -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

Compatible avec GitHub Apps

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.

Paramètres

En-têtes
Nom, Type, Description
acceptstring

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

Paramètres de chemin d’accès
Nom, Type, Description
ownerstringObligatoire

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

repostringObligatoire

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

shastringObligatoire
Paramètres du corps
Nom, Type, Description
statestringObligatoire

The state of the status.

Peut être: error, failure, pending, success

target_urlstring 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

descriptionstring or null

A short description of the status.

contextstring

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

Default: default

Codes de statut de réponse HTTP

Code d’étatDescription
201

Created

Exemples de code

post/repos/{owner}/{repo}/statuses/{sha}
curl \ -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 } }