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.
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.
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.
An Integration authenticates as itself, with its own credentials, not those belonging to a user.
More details can be found in:
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
Give us your feedback
Come talk to us, in the new Platform forum.