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.