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.