About choosing an integration type

Installation processes for integrations

GitHub Apps are installed at the account level, which means that a GitHub App can be used in one account without granting access to another. For instance, you can 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. GitHub Apps also don't break or go away when the individual who set them up leaves the organization.

Note: GitHub Apps are only compatible with the REST API v3 at this time.

GitHub Apps OAuth Apps
Installation grants you access to a specific user's or organization's chosen repositories Authorization grants you access to the user's accessible resources
Installation token's access to resources will change if an admin removes repositories from the installation The OAuth access token will lose access to resources that the user loses access to, for instance when a user is removed from a repository or organization)
An organization or personal repository owner can uninstall the GitHub App to remove its access A user can delete an OAuth access token to remove access
Only an organization owner can install a GitHub App on their organization Any user can grant an authorization for resources they have access to
A user can always install a GitHub App on their personal repository A user can always grant an authorization for their personal resources
Installation token is limited to specified repositories and the integrator's chosen permissions Access token is limited via scopes
GitHub Apps can request separate access to issues and pull requests without getting access to the repository's code/contents OAuth Apps needs to request repo scope to get access to issues, pull requests, or anything owned by the repository
GitHub Apps are not subject to organization application policies. A GitHub App only has access to the repositories the organization owner granted. If an organization application policy is active, only an organization owner can authorize installation of an OAuth App. If installed, the OAuth App gains access to anything visible to the token they have within the approved organization.
Organization members can't request a GitHub App installation. If an organization application policy is active, any user can request that an GitHub App be installed to a particular organization but an organization owner can approve or deny the request.
GitHub Apps receive a webhook event whenever an installation is changed or removed so the integrator can always know when they've received more or less access to an organization's resources. OAuth Apps can lose access to an organization or repository at any time based on the granting user's changing access. There is no indication that an OAuth App loses access to a resource.

Token-based identification for integrations

Note: GitHub Apps can also use a user-based token. For more information, see "Identifying users for GitHub Apps."

GitHub Apps OAuth Apps
Installation token requested by using private key with JSON web token format out-of-band Exchange request token for access token after redirect via web request
Installation token identifies you as the GitHub Apps bot, such as @jenkins-bot Access token identifies you as the user who granted you the token, such as @octocat
Installation tokens automatically expire after a predefined amount of time (currently 1 hour) OAuth tokens last forever (or until they are manually revoked by the customer)
GitHub Apps use the installation's minimum rate limit of 5,000 requests per hour. Organization installations with more than 20 users receive another 50 requests per hour for each user. Installations that have more than 20 repositories receive another 50 requests per hour for each repository. OAuth tokens use the user's rate limit (5,000 requests per hour)
Rate limit increases could be granted both at the GitHub Apps level (affecting all installations) and at the individual installation level Rate limit increases are granted per OAuth application and every token granted to that OAuth application gets the increased limit

Requesting permission levels for resources of integrations

GitHub App have targeted permissions that allow third-party applications to request access only to what they need. For example, a 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 GitHub App could have no access to read or write code, but have the ability to manage issues, labels, and milestones. With OAuth Apps, it's not possible to set granular permissions.

Note: GitHub Apps can either have read or write permissions.

Access GitHub Apps OAuth Apps
Access to public repositories Public repository would need to be specifically chosen during installation public_repo
Access to repository code/contents Repository contents repo
Access to issues, labels, and milestones Issues repo
Access to pull requests, labels, and milestones Pull requests repo
Access to commit statuses (for CI builds) Commit statuses repo:status
Access to deployments and deployment statuses Deployments repo_deployment
Receiving events via a webhook Webhook is automatically included as part of the GitHub App write:repo_hook or write:org_hook

Repository discovery for integrations

GitHub Apps OAuth Apps
GitHub Apps can look at /installation/repositories to see repositories the installation can access OAuth Apps can look at /user/repos for a user view or /orgs/:org/repos for an organization view of accessible repositories
GitHub Apps receive webhooks when repositories are added or removed from the installation OAuth Apps create organization webhooks for notifications when a new repository is created within an organization

Webhooks for integrations

GitHub Apps OAuth Apps
GitHub Apps automatically has a single webhook that receives the events it's configured to receive for every repository it has access to OAuth Apps request the webhook scope to create a repository webhook for each repository it needs to receive events from
GitHub Apps receive certain organization-level events with the Organization members permission OAuth Apps request the organization webhook scope to create an organization webhook for each organization it needs to receive organization-level events from

Git access for integrations

GitHub Apps OAuth Apps
Ask for Repository contents permission and use your installation token to authenticate via HTTP-based Git. Ask for write:public_key scope and create a deploy key via the API. You can then use that key to perform Git commands.
The token is used as the HTTP password. The token is used as the HTTP username.

Machine and Bot accounts for integrations

Machine user accounts are user accounts that segregate automated systems using GitHub's user system.

Bot accounts are specific to GitHub Apps and are built into every GitHub App.

GitHub Apps OAuth Apps
GitHub Apps bots do not consume a GitHub Enterprise seat A machine user account consumes a GitHub Enterprise seat
A bot is never granted a password and thus cannot be logged into directly A machine user is granted a username and password to be managed and secured by the customer