Commit Status API

Today, we shipped an API for third party services to attach statuses to commits.

We created this API to allow services to color the discussion on pull requests. For example, we use this API internally with our continuous integration (CI) setup to automatically update the status of every commit on every branch. Now, when we discuss pull requests, we can easily and automatically ensure they are safe to merge.

We also designed this API to be flexible. The API allows the service to determine the meaning of whether a commit is successful or not. As a result, the API can be used for just about anything — like design reviews or ensuring contributor license agreements are filed.

Pull Requests

Pull requests show the status of the most recent commit, as well as the (optional) description and URL metadata attached to the status.

Every commit in the pull request features a status indicator.

The merge button for the pull request will also take status into account.

The merge indicator for the pull request takes status into account and offers a warning if the status is not ‘success’. The pull request can still be merged if the status is not successful though – we just warn you about it.

Services Available Today

Travis CI already pushes status information for all Travis-enabled repositories without any additional configuration required. For example, this pull request in Gollum already has statuses attached. See their blog post for more details.

Sprint.ly offers status integration for project management. For enabled repositories, they push status updates when tickets change state. Check out their blog post for the more details.

Using the Commit Status API

Integrating with our Status API is simple. Each status includes a state, a SHA, a repository, and an optional URL and description. The state reflects whether or not a SHA (commit) is successful at that point in time. The states we currently support are “pending”, “success”, “failure”, and “error”. If the status provides a URL or description, we display it in our UI.

Statuses cannot be changed once added to a commit (they’re completely immutable), but any number of statuses may be attached to a single commit. We only display the most recent status for any given commit in our UI.

For more details on the nitty gritty see the API docs.

We are very excited to see what integrations you, the community, develop around this API!

Written by

Rob Sanheim

@rsanheim