Deployment and DeploymentStatus API enhancements preview period

We've expanded our Deployments APIs to accommodate more powerful deployment practices and to lay the foundation for a more seamless integration of deployments within GitHub.

Link to a live deployment

To enable easy access to a live version of a deployment, we've added an environment_url field to the Deployments API. This environment will be exposed as a link in the Pull Request timeline to enable users to directly access a running version of their code without leaving the context of their work.

Note: To add some clarity, we've renamed the target_url field to log_url. We will continue accept target_url to support legacy uses, but we recommend modifying this to the new name to avoid confusion. Future API versions might not support target_url.

Inactive deployment status

We recognize that deployments in many common practices don't last forever. So, we've added a new inactive state to Deployment Statuses. You can use this state to communicate that a deployment is no longer active (e.g. something different has been deployed to the environment or the environment has been destroyed).

More information about environments

We've expanded our Deployments API to provide additional information about the environments associated with deployments.

We've added a new transient_environment field to allow you to communicate that an environment is specific to a deployment and will no longer exist at some point in the future (e.g. a temporary testing environment like a Heroku Review App). By pairing this with other additions, we can determine that an inactive deployment associated with a transient_environment has an environment_url that is no longer accessible.

Similarly, we've added a new production_environment field to allow you to communicate that an environment is one with which end users directly interact. We automatically set production_environment to true if the value for environment is "production".

Automatic creation of inactive statuses

Each time we receive a new successful deployment status, we automatically add a new inactive status to all previous deployments made within the relevant repository to the same environment (based on the value of environment) given the environment is both non-transient and non-production. You can opt out of this behavior by passing false with the new auto_inactive parameter.

For example, if feature-branch within https://github.com/user/repository is deployed to an environment named staging (which is a non-transient, non-production environment) and bugfix-branch within https://github.com/user/repository is later deployed to an environment named staging, we would automatically create a new inactive status for the deployment associated with feature-branch.

How can I try it?

Starting today, these API enhancements are available for developers to preview. At the end of the preview period, these enhancements will become official components of the GitHub API.

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

application/vnd.github.ant-man-preview+json

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

Take a look at the documentation for full details. We would love to hear your thoughts on these enhancements. If you have any questions or feedback, please get in touch with us!

Preview support for Git signing

GitHub recently started verifying GPG signed commits and tags. We are adding API support for signature verification and user GPG key management as well. You can enable these changes during the preview period by providing a custom media type in the Accept header:

application/vnd.github.cryptographer-preview

For example:

curl "https://api.github.com/user/gpg_keys" \
  -H 'Authorization: token TOKEN' \
  -H "Accept: application/vnd.github.cryptographer-preview" \

You can learn more about the new signature verification response objects in the updated repository commit, Git commit, and Git tag documentation. There is also new GPG key management documentation.

During the preview period, we may change aspects of these APIs based on developer feedback. We will announce the changes here on the developer blog, but we will not provide advance notice.

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

Preview Squash Support for the Pull Request Merge API

UPDATE (2016-09-26): As announced, there is an extended version of the preview support of merge methods in the Pull Request Merge API available. This older version will be removed once the new one becomes official.

With the recent addition of squashing Pull Requests via the merge button, we're adding support to squash Pull Requests in the API as well. You can squash a pull request in the Pull Request Merge API during the preview period by providing a custom media type in the Accept header:

application/vnd.github.polaris-preview

For example:

curl "https://api.github.com/repos/github/hubot/pulls/123/merge" \
  -XPUT \
  -H 'Authorization: token TOKEN' \
  -H "Accept: application/vnd.github.polaris-preview" \
  -d '{
    "squash": true,
    "commit_title": "Never tell me the odds"
  }'

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

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

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

UPDATE (2016-06-27): As announced, there is an extended version of the protected branches API available. This older version will be removed once the new one becomes official.

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.