Commit Reference SHA-1 Preview Period

We're introducing a new API media type to allow users to get the SHA-1 of a commit reference. This can be useful in working out if you have the latest version of a remote branch based on your local branch's SHA-1. Developers with read access to a repository can start experimenting with this new media type today during the preview period.

To get the commit reference's SHA-1, make a GET request to the repository's reference:

curl "https://api.github.com/repos/Homebrew/homebrew/commits/master" \
  -H "Accept: application/vnd.github.chitauri-preview+sha"

To check if a remote branch's SHA-1 is the same as your local branch's SHA-1, make a GET request to the repository's branch and provide the current SHA-1 for the local branch as the ETag:

curl "https://api.github.com/repos/Homebrew/homebrew/commits/master" \
  -H "Accept: application/vnd.github.chitauri-preview+sha" \
  -H "If-None-Match: \"814412cfbd631109df337e16c807207e78c0d24e\""

If the remote and your local branch point to the same SHA-1 then this call will return a 304 Unmodified status code (and not use your rate limit).

You can see an example of this API in a pull request to Homebrew/homebrew's updater: https://github.com/Homebrew/homebrew/pull/49219.

How can I try it?

To use this new API media type during the preview period, you’ll need to provide the following custom media type in the Accept header:

application/vnd.github.chitauri-preview+sha

During the preview period, we may change aspects of this API media type based on developer feedback. If we do, we will announce the changes here on the developer blog, but we will not provide any advance notice.

Take a look at the documentation and, if you have any questions, please get in touch.

Preview the Source Import API

We've added an API for source imports, which will let you start an import from a Git, Subversion, Mercurial, or Team Foundation Server source repository. This is the same functionality as the GitHub Importer.

To access the Source Import API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.barred-rock-preview

During the preview period, we may change aspects of these API methods based on developer feedback. If we do, we will announce the changes here on the developer blog, but we will not provide any advance notice.

If you have any questions or feedback, please let us know!

Issue Locking and Unlocking API Preview Period

We're introducing new API methods to allow repository collaborators to lock and unlock conversations. Developers with collaborator permissions on a repository can start experimenting with these new endpoints today during the preview period.

To lock a conversation, make a PUT request to the conversation's issue:

curl "https://api.github.com/repos/github/hubot/issues/1/lock" \
  -X PUT \
  -H "Authorization: token $TOKEN" \
  -H "Content-Length: 0" \
  -H "Accept: application/vnd.github.the-key-preview"

To unlock a conversation, make a similarly constructed DELETE request:

curl "https://api.github.com/repos/github/hubot/issues/1/lock" \
  -X DELETE \
  -H "Authorization: token $TOKEN" \
  -H "Accept: application/vnd.github.the-key-preview"

How can I try it?

Starting today, developers can preview these new API methods. To use them during the preview period, you’ll need to provide the following custom media type in the Accept header:

application/vnd.github.the-key-preview+json

During the preview period, we may change aspects of these API methods based on developer feedback. If we do, we will announce the changes here on the developer blog, but we will not provide any advance notice.

Take a look at the documentation and, if you have any questions, please get in touch.

API enhancements for working with organization permissions are now official

To allow API developers to take advantage of the improved organization permissions that launched in September 2015, we're making the API enhancements for working with organization permissions a part of the official GitHub API.

During the preview period, you needed to provide a custom media type in the Accept header to opt-in to the changes. Now that the preview period has ended, you no longer need to specify this custom media type.

If you have any questions or feedback, please get in touch with us!

Protected Branches API Preview Period

We're starting a preview period for the protected branches API. Protecting a branch prevents force-pushes to it as well as deleting it. You can also specify required status checks that are required to merge code into the branch.

To protect a branch, make a PATCH request to the URL of the branch:

curl "https://api.github.com/repos/github/hubot/branches/master" \
  -XPATCH \
  -H 'Authorization: token TOKEN' \
  -H "Accept: application/vnd.github.loki-preview" \
  -d '{
    "protection": {
      "enabled": true,
      "required_status_checks": {
        "enforcement_level": "everyone",
        "contexts": [
          "required-status"
        ]
      }
    }
  }'

How can I try it?

To access this functionality during the preview period, you’ll need to provide the following custom media type in the Accept header:

application/vnd.github.loki-preview+json

Take a look at the docs here.

If you have any questions, please get in touch.

Ensure your app is ready for Protected Branches

We’ve begun to roll out Protected Branches across GitHub. When you protect a branch in one of your repositories, you will be prevented from force pushing to that branch or deleting it. You can also configure required status checks for your protected branch. When configured, changing a branch to point at a new commit will fail unless that commit (or another commit with the same Git tree) has a Status in the success state for each required status check.

These restrictions apply to branch manipulations performed via the GitHub API as well. So when you protect a branch, you will no longer be able to delete the branch via the API or update it to point at a non-ancestor commit, even with "force": true. And if your branch has required status checks, you won’t be able to update it or merge pull requests into that branch until success Statuses have been posted to the target commit for all required status checks.

These restrictions are all represented by 422 errors:

curl -i -H 'Authorization: token TOKEN' \
   -X DELETE https://api.github.com/repos/octocat/hubot/git/refs/heads/master

HTTP/1.1 422 Unprocessable Entity
{
 "message": "Cannot delete a protected branch",
 "documentation_url": "https://help.github.com/articles/about-protected-branches"
}

Protected branches and required status checks are a great way to ensure your project’s conventions are followed. For example, you could write a Status integration that only posts a success Status when the pull request’s author has signed your project’s Contributor License Agreement. Or you could write one that only posts a success Status when three or more members of your @initech/senior-engineers team have left a comment saying they’ve reviewed the changes. If you configure these integrations as required status checks, you can be sure that these conditions have been satisfied before a pull request is merged. See our Status API guide to learn how to create integrations like these.

If you have any questions, please let us know.

Get the contents of a repository’s license

The License API Preview now allows you to retrieve the contents of a repository's open source license. As before, when the appropriate preview media type is passed, the repository endpoint will return information about the detected license, if any:

curl -H "Accept: application/vnd.github.drax-preview+json" https://api.github.com/repos/benbalter/gman

You can now also get the contents of the repository's license file, whether or not the license was successfully identified via the license contents endpoint:

curl -H "Accept: application/vnd.github.drax-preview+json" https://api.github.com/repos/benbalter/gman/license

Similar to the repository contents API, the license contents method also supports custom media types for retrieving the raw license content or rendered license HTML.

curl -H "Accept: application/vnd.github.drax-preview.raw" https://api.github.com/repos/benbalter/gman/license

For more information, see the license API documentation, and as always, if you have any questions or feedback, please get in touch with us.

More flexible options for listing repositories

The List your repositories API now offers additional parameters to help you fetch the exact set of repositories you're looking for:

• The visibility parameter lets you request only your public repositories, only your private repositories, or both.
• With the affiliation parameter, you can ask for repositories you own, repositories where you are a collaborator, repositories you have access to as an organization member, or any combination that suits your needs.

Use these new parameters separately, together, or in combination with other parameters to craft flexible queries that fetch the specific repositories you're seeking.

For full details, check out the documentation. If you have any questions, please get in touch!

Automatic redirects for renamed repositories

To help API clients gracefully handle renamed repositories, the API now automatically redirects to the repository’s new location.

Our thanks goes out to everyone that tried out this enhancement during the preview period. During the preview period, you needed to provide a custom media type in the Accept header to opt-in to the redirects. Now that the preview period has ended, you no longer need to specify this custom media type.

To learn more about these redirects and how they benefit your applications, be sure to check out the preview period announcement. As always, if you have any questions, we're here to help.

Licenses API update

We are expanding the Licenses API to make it more useful for auditing license usage across all repositories owned by a user or organization.

Before, license information was only returned for an individual repository:

GET /repos/github/hubot

Now, license information will also be included in reponses from endpoints that list multiple repositories, such as List organization repositories:

GET /orgs/github/repos

As before, to access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.drax-preview+json

For more information, see the Licenses API documentation, and if you have any questions or feedback, please let us know.