Statuses

The Status API allows external services to mark commits with a success, failure, error, or pending state, which is then reflected in pull requests involving those commits.

Statuses can also include an optional description and target_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. The target_url would be the full URL to the build output, and the description would be the high level summary of what happened with the build.

Note that the repo:status OAuth scope grants targeted access to Statuses without also granting access to repository code, while the repo scope grants permission to code as well as statuses.

Create a Status

Users with push access can create commit statuses for a given ref:

POST /repos/:owner/:repo/statuses/:sha

Parameters

Name Type Description
state string Required. The state of the status. Can be one of pending, success, error, or failure.
target_url string 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 A short description of the status.
context string A string label to differentiate this status from the status of other systems.

Example

{
  "state": "success",
  "target_url": "https://example.com/build/status",
  "description": "The build succeeded!",
  "context": "continuous-integration/jenkins"
}

Response

Status: 201 Created
Location: https://api.github.com/repos/octocat/example/statuses/1
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
{
  "created_at": "2012-07-20T01:19:13Z",
  "updated_at": "2012-07-20T01:19:13Z",
  "state": "success",
  "target_url": "https://ci.example.com/1000/output",
  "description": "Build has completed successfully",
  "id": 1,
  "url": "https://api.github.com/repos/octocat/example/statuses/1",
  "context": "continuous-integration/jenkins",
  "creator": {
    "login": "octocat",
    "id": 1,
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "somehexcode",
    "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
  }
}

List Statuses for a specific Ref

Users with pull access can view commit statuses for a given ref:

GET /repos/:owner/:repo/statuses/:ref

If you send an Accept header with the Combined Status API preview media type, application/vnd.github.she-hulk-preview+json, this endpoint is also available at /repos/:owner/:repo/commits/:ref/statuses.

Statuses are returned in reverse chronological order. The first status in the list will be the latest one.

Parameters

Name Type Description
ref string Required. Ref to list the statuses from. It can be a SHA, a branch name, or a tag name.

Response

Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
[
  {
    "created_at": "2012-07-20T01:19:13Z",
    "updated_at": "2012-07-20T01:19:13Z",
    "state": "success",
    "target_url": "https://ci.example.com/1000/output",
    "description": "Build has completed successfully",
    "id": 1,
    "url": "https://api.github.com/repos/octocat/example/statuses/1",
    "context": "continuous-integration/jenkins",
    "creator": {
      "login": "octocat",
      "id": 1,
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "gravatar_id": "somehexcode",
      "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
    }
  }
]

Get the combined Status for a specific Ref

The Combined status endpoint is currently available for developers to preview. During the preview period, the API may change without advance notice. Please see the blog post for full details.

To access this endpoint during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.she-hulk-preview+json

Users with pull access can access a combined view of commit statuses for a given ref.

GET /repos/:owner/:repo/commits/:ref/status

The most recent status for each context is returned (up to 25), as well as a combined state. The state is pending to start, failure if any status reports as error or failure, pending if any context’s latest status is pending, and success if the latest status for all contexts is success. (null is considered a distinct context)

Parameters

Name Type Description
ref string Required. Ref to fetch the status for. It can be a SHA, a branch name, or a tag name.

Response

Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
[
  {
    "state": "success",
    "name": "octocat/Hello-World",
    "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
    "statuses": [
      {
        "created_at": "2012-07-20T01:19:13Z",
        "updated_at": "2012-07-20T01:19:13Z",
        "state": "success",
        "target_url": "https://ci.example.com/1000/output",
        "description": "Build has completed successfully",
        "id": 1,
        "url": "https://api.github.com/repos/octocat/example/statuses/1",
        "context": "continuous-integration/jenkins"
      },
      {
        "created_at": "2012-07-20T01:19:13Z",
        "updated_at": "2012-07-20T01:19:13Z",
        "state": "success",
        "target_url": "https://ci.example.com/1000/output",
        "description": "Build has completed successfully",
        "id": 1,
        "url": "https://api.github.com/repos/octocat/example/statuses/1",
        "context": "security/brakeman"
      }
    ],
    "commit_url": "https://api.github.com/repos/octocat/Hello-World/6dcb09b5b57875f334f61aebed695e2e4193db5e",
    "repository_url": "https://api.github.com/repos/octocat/Hello-World"
  }
]