Pull Request Review Webhooks

With the recent launch of Pull Request Reviews at GitHub Universe, we've added a webhook event for Pull Request Reviews. You can learn more about the event in the documentation.

A REST API for this feature is on our near-term roadmap and we'll post on this blog when it's available.

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

Preview Rebase Support for the Pull Request Merge API

With the recent addition of rebasing Pull Requests via the merge button, we're adding support to rebasing Pull Requests in the API as well. We're extending the preview squash support to include the rebase merge method. You can rebase 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 '{
    "merge_method": "rebase",
    "commit_title": "Never tell me the odds"
  }'

In addition, we're extending the Squash API Preview to support fetching and updating repository settings for merging pull requests. You can now determine whether merging with squashing, rebasing and merge commits are allowed for a repository, and also change those settings, by providing the same custom media type in the Accept header.

For example:

curl "https://api.github.com/repos/github/hubot" \
  -H 'Authorization: token TOKEN' \
  -H "Accept: application/vnd.github.polaris-preview"

{
  "id": 2278524,
  "name": "hubot",
  "full_name": "github/hubot",
  ...
  "allow_rebase_merge": true,
  "allow_squash_merge": true,
  "allow_merge_commit": true,
  ...
}

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.

Integrations Early Access

We've designed a new option for extending GitHub: Integrations.

Integrations are first-class actors that connect your service to GitHub. They're especially suited when:

• Your service needs to take actions independently of a specific user
• You want granular permissions
• You want to allow users to install on an organization
• You want to allow users to install on a per repository basis

For example, you may wish for your service to write commit statuses, open issues, or deploy code.

Register an Integration

Anyone can register an Integration on GitHub via Settings > Developer settings > Integrations.

Permissions

An Integration can have granular permissions, for example the ability to read issues or create deployments. Notably, access to the contents of a repository, the code itself, is a separate permission.

Each permissions category gives you access to certain endpoints. For example, if your Integration has write permission on Deployments, it can make these API requests:

GET /repositories/:repository_id/deployments/:id
GET /repositories/:repository_id/deployments/:deployment_id/statuses
GET /repositories/:repository_id/deployments
POST /repositories/:repository_id/deployments/:deployment_id/statuses
POST /repositories/:repository_id/deployments

For a full breakdown of permissions, see the permissions documentation.

Installing an Integration

Users and organization admins can install Integrations from within GitHub, from a dedicated page for each Integration. As a user, you can choose whether to install on your personal account, or on any organization you have admin access to. You can choose to install only on specific repositories, or on all of your repositories.

Webhooks

Integrations automatically get one webhook. There is no need to install any further hooks on the accounts and repositories your integration is installed on.

That single webhook provides a simple means for the Integration to listen for new installations, and any other event types it has subscribed to.

Authentication

An Integration authenticates as itself, with its own credentials, not those belonging to a user.

More details can be found in:

• Authenticating as an Integration
• Authenticating as an Installation

What about OAuth applications and Personal Access Tokens?

OAuth applications and Personal Access Tokens will continue to work as is, and be the right solution for many use cases. Integrations use a new permissions model and new flows, and provide an additional option for developers to build the best tools on top of the GitHub platform.

How can I try it?

To access Integrations, you must first sign the pre-release agreement.

If you'd like to get started, check out our developer documentation.

To access the Integrations API functionality during the Early Access, you’ll need to provide the following custom media type in the Accept header:

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

Give us your feedback

Come talk to us, in the new Platform forum.

Preview the new Projects API

We've added Early Access to an API for our new Projects feature!

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

application/vnd.github.inertia-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.

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

API changes for changing the base branch on Pull Requests

GitHub recently added the ability to change the base branch on a Pull Request after it's created. Now we're updating the Pull Request API to enable the new functionality.

For example:

curl "https://api.github.com/repos/github/hubot/pulls/123" \
  -H 'Authorization: token TOKEN' \
  -d '{ "base": "master" }'

The Pull Request base will be updated to point to the master branch.

You can learn more about the new responses and endpoints in the updated Pull Request documentation.

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

Preview the Repository Traffic API

We've added an API for repository traffic, which will let you fetch details about traffic for repositories you have push access to. This data is already available in graphical form in the Graphs section on GitHub.com.

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

application/vnd.github.spiderman-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!

Breaking change: Removed sensitive fields from Organization API responses for non-owners

We're removing some values from Organization API responses to help protect our users' privacy. Previously, these fields were returned to all members of the organization. As of today, you must be an Organization owner to receive values for the following fields in Organization responses:

• private_gists
• disk_usage
• collaborators
• billing_email

If you're not an organization owner, the above keys will now return null. We will continue to send these fields without their values to minimize the impact of this change.

If you have any questions or feedback, please drop us a line.

Multiple Assignees API is now official

We're making Multiple Assignees part of the official GitHub API.

During the preview period you needed to provide the application/vnd.github.cerberus-preview preview 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!

Introducing the GitHub Pages preview API

We're introducing additional preview functionality to the GitHub Pages API to give developers better control over their GitHub Pages site.

Requesting a page build

You can now manually request a build of your GitHub Pages site without needing to push a new commit by making a POST request to the endpoint already available to see past builds. For example:

curl "https://api.github.com/repos/github/developer.github.com/pages/builds" \
  -X POST
  -H 'Authorization: token TOKEN' \
  -H "Accept: application/vnd.github.mister-fantastic-preview" \

Retrieving a site's URL

With the introduction of HTTPS support for GitHub Pages sites, it's important to know not just a site's custom domain, if it has one, but also if it has HTTPS enforcement enabled. The GitHub Pages API will now return an additional html_url field, which will include the computed absolute URL to the site.

The resulting URL can be https://username.github.io (or http://username.github.io) for user sites without a custom domain, https://username.gituhb.io/project for project sites, or http://example.com for sites with custom domains, saving third-party applications the trouble of having to construct complicated URL logic based on the username, owner, and CNAME, as was previously necessary.

For example, to request the HTML URL:

curl "https://api.github.com/repos/github/developer.github.com/pages" \
  -H 'Authorization: token TOKEN' \
  -H "Accept: application/vnd.github.mister-fantastic-preview" \

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.mister-fantastic-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.

For more information, take a look at the docs here, and if you have any questions, please get in touch.

Update to Protected Branches API Preview

Over the past few months, we've made a few improvements to the way protected branches work in our web interface. Today, we're modifying the protected branches API preview period to include these improvements.

Included in these API changes is the ability to allow organizations to specify which members and teams should be able to push to a protected branch, as well as providing a new setting for required status checks which will remove the requirement of a pull request to be up to date before merging.

You'll notice a new endpoint structure. One set of endpoints for modifying the branch settings as a whole (PATCH /repos/:owner/:repo/branches/:branch has been updated to be PUT /repos/:owner/:repo/branches/:branch/protection), and a series of more granular endpoints to modify a subset of the branch protection settings.

This will be a breaking change for the protected branch API. The deprecated API endpoint will be removed when the protected branches API will leave the preview period. If you're trying out the old protected branches API, you'll need to update your code.

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.