Integrations

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.

Granular permissions

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.

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.