The 451 status code is now supported

In December 2015, the IETF ratified status code 451. A 451 response indicates that a resource is unavailable due to an external legal request.

The GitHub API will now respond with a 451 status code for resources it has been asked to take down due to a DMCA notice. For example:

curl https://api.github.com/repos/github/a-repository-that-s-been-taken-down
HTTP/1.1 451
Server: GitHub.com

{
 "message": "Repository access blocked",
 "block": {
   "reason": "dmca",
   "created_at": "2016-03-17T15:39:46-07:00"
 }
}

This 451 code will be returned for repositories and gists. Previously, the API responded with a 403 - Forbidden. Aside from the semantic difference, we feel that it's important for users to know precisely why their data cannot be served.

If you're receiving a 451 due to a DMCA takedown, please read our article on submitting a DMCA counter notice and know your rights. For more information, see GitHub's DMCA Takedown Policy.

New webhook event actions are coming

We will soon begin introducing new action values for several existing webhook events. If you currently subscribe to webhooks but do not check the payload's action value, you may end up incorrectly processing events after this change is released. To ensure that your webhook processing is not affected by these new action values, you should audit your webhook processing logic by April 15th, 2016.

We are providing an advance notice to warn of these changes. In the future, we may continue adding new actions without providing further warning.

A brief overview of GitHub webhook actions

Webhook events can have multiple actions. For example, the IssuesEvent has several possible actions. These include opened when the issue is created, closed when the issue is closed, and assigned when the issue is assigned to someone. Historically, we haven't added new actions to webhook events that have only one action. However, as GitHub's feature set grows, we may occasionally add new actions to existing event types. We encourage you to take some time and ensure that your application explicitly checks the action before doing any processing.

What to avoid when working with event actions

Here's an example of functionality that will not work when attempting to process an IssuesEvent. In this example, the process_closed method will be called for any event action which is not opened or assigned. This means that the process_closed method will be called for events with the closed action, but also other events with actions other than opened or assigned that are delivered to the webhook.

# The following is not future-proof!
case action
when "opened"
  process_opened
when "assigned"
  process_assigned
else
  process_closed
end

How to work with new event actions

We suggest that you explicitly check event actions and act accordingly. In this example, the closed action is checked first before calling the process_closed method. Additionally, for unknown actions, we log that something new was encountered:

# The following is recommended
case action
when "opened"
  process_opened
when "assigned"
  process_assigned
when "closed"
  process_closed
else
  puts "Ooohh, something new from GitHub!"
end

We may also add new webhook event types from time to time. If your webhook is configured to "Send me everything", your code should also explicitly check for the event type in a similar way as we have done with checking for the action type above. Take a look at our integrators best practices guide for more tips.

If you have any questions or feedback, please get in touch.

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!