The REST API is now versioned.For more information, see "About API versioning."

REST API endpoints for commit statuses

Use the REST API to interact with commit statuses.

About commit statuses

You can use the REST API to allow external services to mark commits with anerror,failure,pending, orsuccess state, which is then reflected in pull requests involving those commits. Statuses can also include an optionaldescription andtarget_url, and we highly recommend providing them as they make statuses much more useful in the GitHub UI.

As an example, one common use is for continuous integration services to mark commits as passing or failing builds using status. Thetarget_url would be the full URL to the build output, and thedescription would be the high level summary of what happened with the build.

Statuses can include acontext to indicate what service is providing that status. For example, you may have your continuous integration service push statuses with a context ofci, and a security audit tool push statuses with a context ofsecurity. You can then use the REST API toGet the combined status for a specific reference to retrieve the whole status for a commit.

Note that therepo:statusOAuth scope grants targeted access to statuseswithout also granting access to repository code, while therepo scope grants permission to code as well as statuses.

If you are developing a GitHub App and want to provide more detailed information about an external service, you may want to use the REST API to manage checks. For more information, seeREST API endpoints for checks.

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 combinedstate is returned. Thestate is one of:

failure if any of the contexts report aserror orfailure
pending if there are no statuses or a context ispending
success if the latest status for all contexts issuccess

Fine-grained access tokens for "Get the combined status for a specific reference"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Commit statuses" repository permissions (read)

This endpoint can be used without authentication or the aforementioned permissions if only public resources are requested.

Parameters for "Get the combined status for a specific reference"

Headers
Name, Type, Description
`accept`string Setting to`application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner`stringRequired The account owner of the repository. The name is not case sensitive.
`repo`stringRequired The name of the repository without the`.git` extension. The name is not case sensitive.
`ref`stringRequired 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.

Query parameters
Name, Type, Description
`per_page`integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default:`30`
`page`integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Default:`1`

HTTP response status codes for "Get the combined status for a specific reference"

Status code	Description
`200`	OK
`404`	Resource not found

Code samples for "Get the combined status for a specific reference"

Request example

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.

Fine-grained access tokens for "List commit statuses for a reference"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Commit statuses" repository permissions (read)

This endpoint can be used without authentication or the aforementioned permissions if only public resources are requested.

Parameters for "List commit statuses for a reference"

Headers
Name, Type, Description
`accept`string Setting to`application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner`stringRequired The account owner of the repository. The name is not case sensitive.
`repo`stringRequired The name of the repository without the`.git` extension. The name is not case sensitive.
`ref`stringRequired 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.

Query parameters
Name, Type, Description
`per_page`integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default:`30`
`page`integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Default:`1`

HTTP response status codes for "List commit statuses for a reference"

Status code	Description
`200`	OK
`301`	Moved permanently

Code samples for "List commit statuses for a reference"

Request example

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 persha andcontext within a repository. Attempts to create more than 1000 statuses will result in a validation error.

Fine-grained access tokens for "Create a commit status"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Commit statuses" repository permissions (write)

Parameters for "Create a commit status"

Headers
Name, Type, Description
`accept`string Setting to`application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner`stringRequired The account owner of the repository. The name is not case sensitive.
`repo`stringRequired The name of the repository without the`.git` extension. The name is not case sensitive.
`sha`stringRequired

Body parameters
Name, Type, Description
`state`stringRequired The state of the status. Can be one of:`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:`default`

HTTP response status codes for "Create a commit status"

Status code	Description
`201`	Created

Code samples for "Create a commit status"

Request example

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  }}

Movatterモバイル変換

REST API endpoints for commit statuses

Request example

Response

Request example

Response

Request example

Response