- What are Integrations?
- How is an Integration different from an OAuth Application?
- Getting started and web application flow
- Current limitations
- Feedback and collaboration
What are Integrations?
Integrations are a new way to extend GitHub. They can be installed directly on organizations and user accounts and granted access to specific repositories. They come with granular permissions and built-in webhooks. Integrations are first class actors within GitHub.
Installed on organizations
Integrations can be installed directly on an organization (you must be an owner to install). Since they are installed at the account level, users can safely use an Integration in one context without necessarily granting access to another (e.g., use a third party build service at work in your employer's organization, but not grant that build service access to repositories in your personal account). Integrations also don't break or go away when the individual who set them up leaves the organization.
Grant access only to specific repositories
Even more important than selecting an install target is the ability to grant Integrations access only to specific repositories. As part of the install process (and at anytime afterward) organization owners can grant or deny access on an individual repository level — something that just isn't possible with an OAuth application.
Beyond just access to a specific repository, Integrations can have very targeted permissions allowing third party applications to request access only to what they need and nothing more. For example, an CI Integration could request read access to repository content and write access to the status API (something that is not possible in the old OAuth system). Another Integration could be granted no access to read or write code, but given the ability to manage issues, labels, and milestones.
Webhooks are built in
Part of registering an Integration involves (optionally) selecting webhook events to be delivered to an endpoint of your choosing.
First class actors
Finally, an Integration can act on its own behalf — taking actions via the API directly instead of impersonating a user. This allows for usage patterns that previously required maintaining a bot or service account as a separate user. Integrations are first class actors on GitHub opening up whole new workflows for bots, machines, and intelligent programs to augment the development experience.
How is an Integration different from an OAuth Application?
There are many differences between OAuth applications and Integrations. At a high level, an Integration is best used to provide a service to an entire organization. While an Integration can perform certain actions on behalf of users, it should primarily use its own identity when performing its function.
If you're looking to use GitHub as an identity provider and perform all actions as the user who granted access, an OAuth application likely suits the situation better.
For a full comparison, check out Integrations vs. OAuth Applications.
Getting started and web application flow
All developers need to register their integration before getting started. A registered integration has a private key which should not be shared. It can be regenerated if the key is compromised.
The API actions listed in "List of Integrations Enabled Endpoints" are available for integrations to access. The flow for performing API actions is:
- Authenticate as the integration
- Create an installation access token
- Authenticate with the installation access token
- Perform the API action as the integration or on behalf of a user
The sidebar to the right provides documentation for Integrations.
During the Early Access for Integrations, you should limit the information that you expose to users on your site, so that information isn't accidentally shown to a user that doesn't have the same access your Integration does.
We have built flows that enable you to identify a user and determine what information you can show them. Currently this is limited to specific situations where a user clicks a link within GitHub and is directed to your site. Beyond this, you shouldn't allow users to explore additional information that your Integration has.
You can read about the currently supported flows here. In the future, we'll enable you to more holistically identify users and determine what information to show them.
Feedback and collaboration
We run the GitHub Platform Forum at platform.github.community. You'll be able to collaborate with other integrators, as well as engineers and product managers from GitHub. To foster transparency and collaboration, the GitHub Platform Forum should be used for all discussions, bug reports, and requests. If you need to discuss a private concern, you can contact our support team for assistance.