Changes to the upcoming Projects API

To support the release of organization-wide projects, we're making a change to the upcoming Projects API.

New Projects API endpoints

We've added new "List organization projects" and "Create organization project" API endpoints, allowing your app to get all of the projects belonging to a particular organization, or to create new ones.

Changes to existing Projects API endpoints

Previously, the "Get a project" endpoint was scoped to the project's owner. It looked like this:

GET /repos/:owner/:repo/projects/:number

We're changing the "Get a project" endpoint to look like this:

GET /projects/:id

This allows integrators to keep the same URL structure in their API requests whether they're working with a repository project or an organization-wide project.

We're making this same change to every single Projects API endpoint except for the "List repository projects" and "Create repository project" endpoints.

The owner-scoped endpoints (besides those for "List repository projects" and "Create repository project") are now deprecated, so please update your apps to use the new endpoints before November 10, 2016. On this day, we'll be removing these endpoints. Further requests to them after this day will receive 404 responses.

New scope requirements

We've added the public_repo scope as a requirement for accessing projects that belong to a public repository. This is in addition to the existing repo scope requirement for accessing projects that belong to a private repository or an organization.

Here's how this new public_repo scope requirement will affect the Project API endpoints:

• The new ID-based project API endpoints will require the public_repo scope for projects belonging to public repositories effective immediately.
• The "List repository projects" and "Create repository project" endpoints will begin requiring the public_repo scope for public repositories on November 10, 2016.
• The deprecated owner-scoped Project API endpoints won't require the public_repo scope for public repositories, but these endpoints will be removed on November 10, 2016.

To access the Projects API during the preview 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!

New Webhooks for Labels and Milestones

We're releasing new webhook events for labels and milestones. You'll automatically begin receiving these events if you have a webhook that is subscribed to wildcard events. As before, we continue to recommend listening for the actions in order to future-proof your code.

Several new events and actions were added, which are detailed below.

LabelEvent

• created: sent when a label is created.
• edited: sent when a label is edited, such as when it's renamed or the color is changed.
• deleted: sent when a label is deleted.

MilestoneEvent

• created: sent when a milestone is created.
• closed: sent when a milestone is closed.
• opened: sent when a milestone is opened.
• edited: sent when a milestone is edited, such as when its description, due date, or title is changed.
• deleted: sent when a milestone is deleted.

IssuesEvent

• milestoned: sent when an issue is added to a milestone.
• demilestoned: sent when an issue is removed from a milestone.

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

Traffic API Preview now has ISO 8601 compliant timestamps

We've updated the Traffic API preview to make the timestamps ISO 8601 compliant. For example, the millisecond timestamp 1475625600000 will be changed to 2016-10-05T00:00:00Z.

This is a breaking change for the views and clones endpoints. If you're trying out this new API during its preview period, you'll need to update your code to continue working with it.

As always, if you have any questions or feedback, please get in touch.

OAuth authorizations grants API is now official

We're making OAuth grants API part of the official GitHub API. The grants API simplifies management of OAuth applications by letting you view and revoke access in a similar manner to how users manage OAuth applications on GitHub.com. Rather than managing individual OAuth application tokens, the grants API allows you to view and revoke all access for an OAuth application you had previously authorized.

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

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!