LFE Docs

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.

Statuses can include a context to indicate what service is providing that status. For example, you may have your continuous integration service push statuses with a context of ci, and a security audit tool push statuses with a context of security. You can then use the combined status endpoint to retrieve the whole status for a commit.

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

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.

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. Default: "default"

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/Hello-World/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/Hello-World/statuses/1",
  "context": "continuous-integration/jenkins",
  "creator": {
    "login": "octocat",
    "id": 1,
    "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
  }
}

List Statuses for a specific Ref

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

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

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

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
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"
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/Hello-World/statuses/1",
    "context": "continuous-integration/jenkins",
    "creator": {
      "login": "octocat",
      "id": 1,
      "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
    }
  }
]

Get the combined Status for a specific Ref

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 100. This field paginates if there are over 100 contexts.

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

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",
  "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
  "total_count": 2,
  "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/Hello-World/statuses/1",
      "context": "continuous-integration/jenkins"
    },
    {
      "created_at": "2012-08-20T01:19:13Z",
      "updated_at": "2012-08-20T01:19:13Z",
      "state": "success",
      "target_url": "https://ci.example.com/2000/output",
      "description": "Testing has completed successfully",
      "id": 2,
      "url": "https://api.github.com/repos/octocat/Hello-World/statuses/2",
      "context": "security/brakeman"
    }
  ],
  "repository": {
    "id": 1296269,
    "owner": {
      "login": "octocat",
      "id": 1,
      "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
    },
    "name": "Hello-World",
    "full_name": "octocat/Hello-World",
    "description": "This your first repo!",
    "private": false,
    "fork": false,
    "url": "https://api.github.com/repos/octocat/Hello-World",
    "html_url": "https://github.com/octocat/Hello-World"
  },
  "commit_url": "https://api.github.com/repos/octocat/Hello-World/6dcb09b5b57875f334f61aebed695e2e4193db5e",
  "url": "https://api.github.com/repos/octocat/Hello-World/6dcb09b5b57875f334f61aebed695e2e4193db5e/status"
}