Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: About creating GitHub Apps
shortTitle: About creating apps
intro: '{% data variables.product.prodname_github_app %}s let you build integrations to automate processes and extend {% data variables.product.company_short %}''s functionality.'
intro: '{% data variables.product.prodname_github_apps %} let you build integrations to automate processes and extend {% data variables.product.company_short %}''s functionality.'
versions:
fpt: '*'
ghes: '*'
Expand Down Expand Up @@ -30,7 +30,7 @@ Common use cases for {% data variables.product.prodname_github_apps %} include:
- As a developer tool, allowing users to work with {% data variables.product.prodname_dotcom %} by signing into your {% data variables.product.prodname_github_app %}, which can then act on their behalf
- Integrating your tool or external service with {% data variables.product.company_short %}

Like {% data variables.product.prodname_oauth_apps %}, {% data variables.product.prodname_github_app %}s use OAuth 2.0 and can act on behalf of a user. Unlike {% data variables.product.prodname_oauth_apps %}, {% data variables.product.prodname_github_app %}s can also act independently of a user.
Like {% data variables.product.prodname_oauth_apps %}, {% data variables.product.prodname_github_apps %} use OAuth 2.0 and can act on behalf of a user. Unlike {% data variables.product.prodname_oauth_apps %}, {% data variables.product.prodname_github_apps %} can also act independently of a user.

{% data variables.product.prodname_github_apps %} can be installed directly on organizations and personal accounts and granted access to specific repositories. They come with built-in webhooks and narrow, specific permissions.

Expand Down Expand Up @@ -67,10 +67,10 @@ Some examples of automations you could create with a {% data variables.product.p
- A {% data variables.product.prodname_github_app %} that helps repository contributors. For example, the app could post helpful resources after a contributor creates a pull request or makes a comment.
- A {% data variables.product.prodname_github_app %} that generates short-lived tokens to give to other CI/CD tools, or to pull information from a repository.

### {% data variables.product.prodname_github_app %}s that respond to webhooks
### {% data variables.product.prodname_github_apps %} that respond to webhooks

If you want your app to respond to events on {% data variables.product.prodname_dotcom %}, your app should subscribe to webhooks. For example, you may want your app to leave a comment when a pull request is opened. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/using-webhooks-with-github-apps)."

### {% data variables.product.prodname_github_app %}s that can take certain actions
### {% data variables.product.prodname_github_apps %} that can take certain actions

When you set up your {% data variables.product.prodname_github_app %}, you can select specific permissions for the app. These permissions determine what the app can do via the {% data variables.product.prodname_dotcom %} API, what they can do on behalf of a signed in user, and what webhooks the app can receive. For more information, see "[AUTOTITLE](/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app)."
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ If your app is a native client, client-side app, or runs on a user device (as op

## Use the appropriate token type

{% data variables.product.prodname_github_app %}s can generate installation access tokens or user access tokens in order to make authenticated API requests.
{% data variables.product.prodname_github_apps %} can generate installation access tokens or user access tokens in order to make authenticated API requests.

Installation access tokens will attribute activity to your app. These are useful for automations that act independently of users.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,51 +13,51 @@ topics:

## Using a {% data variables.product.prodname_github_app %} instead of an {% data variables.product.prodname_oauth_app %}

In general, {% data variables.product.prodname_github_app %}s are preferred over {% data variables.product.prodname_oauth_app %}s.
In general, {% data variables.product.prodname_github_apps %} are preferred over {% data variables.product.prodname_oauth_apps %}.

Both {% data variables.product.prodname_oauth_app %}s and {% data variables.product.prodname_github_app %}s use OAuth 2.0.
Both {% data variables.product.prodname_oauth_apps %} and {% data variables.product.prodname_github_apps %} use OAuth 2.0.

{% data variables.product.prodname_oauth_app %}s can only act on behalf of a user while {% data variables.product.prodname_github_app %}s can either act on behalf of a user or independently of a user.
{% data variables.product.prodname_oauth_apps %} can only act on behalf of a user while {% data variables.product.prodname_github_apps %} can either act on behalf of a user or independently of a user.

For more information, see "[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps)."

For information on how to migrate an existing {% data variables.product.prodname_oauth_app %} to a {% data variables.product.prodname_github_app %}, see "[AUTOTITLE](/apps/creating-github-apps/guides/migrating-oauth-apps-to-github-apps)."

### {% data variables.product.prodname_github_app %}s offer enhanced security
### {% data variables.product.prodname_github_apps %} offer enhanced security

{% data variables.product.prodname_github_app %}s provide more control over what the app can do. Instead of the broad scopes that {% data variables.product.prodname_oauth_app %}s use, {% data variables.product.prodname_github_app %}s use fine-grained permissions. For example, if your app needs to read the contents of a repository, an {% data variables.product.prodname_oauth_app %} would require the `repo` scope, which would also let the app edit the repository contents and settings. A {% data variables.product.prodname_github_app %} can request read-only access to repository contents, which will not let the app take more privileged actions like editing the repository contents or settings.
{% data variables.product.prodname_github_apps %} provide more control over what the app can do. Instead of the broad scopes that {% data variables.product.prodname_oauth_apps %} use, {% data variables.product.prodname_github_apps %} use fine-grained permissions. For example, if your app needs to read the contents of a repository, an {% data variables.product.prodname_oauth_app %} would require the `repo` scope, which would also let the app edit the repository contents and settings. A {% data variables.product.prodname_github_app %} can request read-only access to repository contents, which will not let the app take more privileged actions like editing the repository contents or settings.

{% data variables.product.prodname_github_app %}s also offer more control over repository access. With a {% data variables.product.prodname_github_app %}, the user or organization owner who installed the app can decide what repositories the app can access. Conversely, an {% data variables.product.prodname_oauth_app %} can access every repository that the user who authorized the app can access.
{% data variables.product.prodname_github_apps %} also offer more control over repository access. With a {% data variables.product.prodname_github_app %}, the user or organization owner who installed the app can decide what repositories the app can access. Conversely, an {% data variables.product.prodname_oauth_app %} can access every repository that the user who authorized the app can access.

{% data variables.product.prodname_github_app %}s use short lived tokens. If the token is leaked, the token will be valid for a shorter amount of time, which reduces the damage that can be done. Conversely, {% data variables.product.prodname_oauth_app %} tokens do not expire until the person who authorized the {% data variables.product.prodname_oauth_app %} revokes the token.
{% data variables.product.prodname_github_apps %} use short lived tokens. If the token is leaked, the token will be valid for a shorter amount of time, which reduces the damage that can be done. Conversely, {% data variables.product.prodname_oauth_app %} tokens do not expire until the person who authorized the {% data variables.product.prodname_oauth_app %} revokes the token.

These security features help harden your {% data variables.product.prodname_github_app %}'s security by limiting the damage that could be done if your app's credentials were leaked. Additionally, this lets organizations with stricter security policies use your app.

### {% data variables.product.prodname_github_app %}s can act independently of or on behalf of a user
### {% data variables.product.prodname_github_apps %} can act independently of or on behalf of a user

{% data variables.product.prodname_github_app %}s can act independently of a user. This is beneficial for automations that do not require user input.
{% data variables.product.prodname_github_apps %} can act independently of a user. This is beneficial for automations that do not require user input.

Similar to {% data variables.product.prodname_oauth_app %}s, {% data variables.product.prodname_github_app %}s can still take actions on behalf of a user. Unlike {% data variables.product.prodname_oauth_app %}s, which don't indicate that the action was performed by the app, {% data variables.product.prodname_github_app %}s indicate that the action was performed by the app on behalf of the user.
Similar to {% data variables.product.prodname_oauth_apps %}, {% data variables.product.prodname_github_apps %} can still take actions on behalf of a user. Unlike {% data variables.product.prodname_oauth_apps %}, which don't indicate that the action was performed by the app, {% data variables.product.prodname_github_apps %} indicate that the action was performed by the app on behalf of the user.

{% data variables.product.prodname_github_app %}s are not tied to a user account and do not consume a seat on {% data variables.product.product_name %}. {% data variables.product.prodname_github_app %}s remain installed even when the person who initially installed the app leaves the organization. This lets your integrations continue to work even if people leave your team.
{% data variables.product.prodname_github_apps %} are not tied to a user account and do not consume a seat on {% data variables.product.product_name %}. {% data variables.product.prodname_github_apps %} remain installed even when the person who initially installed the app leaves the organization. This lets your integrations continue to work even if people leave your team.

### {% data variables.product.prodname_github_app %}s have scalable rate limits
### {% data variables.product.prodname_github_apps %} have scalable rate limits

The rate limit for {% data variables.product.prodname_github_app %}s using an installation access token scales with the number of repositories and number of organization users. Conversely, {% data variables.product.prodname_oauth_apps %} have lower rate limits and do not scale. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/rate-limits-for-github-apps)."
The rate limit for {% data variables.product.prodname_github_apps %} using an installation access token scales with the number of repositories and number of organization users. Conversely, {% data variables.product.prodname_oauth_apps %} have lower rate limits and do not scale. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/rate-limits-for-github-apps)."

### {% data variables.product.prodname_github_app %}s have built in webhooks
### {% data variables.product.prodname_github_apps %} have built in webhooks

{% data variables.product.prodname_github_app %}s have built-in, centralized webhooks. {% data variables.product.prodname_github_app %}s can receive webhook events for all repositories and organizations the app can access. Conversely, {% data variables.product.prodname_oauth_app %}s must configure webhooks individually for each repository and organization.
{% data variables.product.prodname_github_apps %} have built-in, centralized webhooks. {% data variables.product.prodname_github_apps %} can receive webhook events for all repositories and organizations the app can access. Conversely, {% data variables.product.prodname_oauth_apps %} must configure webhooks individually for each repository and organization.

### API access differs slightly

In general, {% data variables.product.prodname_github_app %}s and {% data variables.product.prodname_oauth_app %}s can make the same API requests. However, there are some differences:
In general, {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_oauth_apps %} can make the same API requests. However, there are some differences:

- The REST API to manage check runs and check suites is only available to {% data variables.product.prodname_github_app %}s.
- Enterprise-level resources such as the enterprise object itself are not available to {% data variables.product.prodname_github_app %}s. This means that {% data variables.product.prodname_github_app %}s cannot call endpoints like `GET /enterprise/settings/license`. However, enterprise-owned organization and repository resources are available.
- The REST API to manage check runs and check suites is only available to {% data variables.product.prodname_github_apps %}.
- Enterprise-level resources such as the enterprise object itself are not available to {% data variables.product.prodname_github_apps %}. This means that {% data variables.product.prodname_github_apps %} cannot call endpoints like `GET /enterprise/settings/license`. However, enterprise-owned organization and repository resources are available.
- Some requests may return incomplete data depending on the permissions and repository access that was granted to an {% data variables.product.prodname_github_app %}. For example, if your app makes a request to get all repositories that a user can access, the response will only include the repositories that the app was also granted access to.

For more information about the REST API endpoints that are available to {% data variables.product.prodname_github_app %}s, see "[AUTOTITLE](/rest/overview/endpoints-available-for-github-apps)."
For more information about the REST API endpoints that are available to {% data variables.product.prodname_github_apps %}, see "[AUTOTITLE](/rest/overview/endpoints-available-for-github-apps)."

## Choosing between a {% data variables.product.prodname_github_app %} or a {% data variables.product.pat_generic %}

Expand Down
Loading