jprdonnelly/docs
1
0
Fork 0
mirror of synced 2025-12-21 19:06:49 -05:00
Code Issues Projects Releases Wiki Activity

GHEC version (#20947)

Browse Source 
Co-authored-by: Matt Pollard <mattpollard@users.noreply.github.com>
Co-authored-by: Grace Park <gracepark@github.com>
Co-authored-by: Steve Guntrip <12534592+stevecat@users.noreply.github.com>
Co-authored-by: Robert Sese <sese@github.com>
Co-authored-by: Peter Bengtsson <peterbe@github.com>
Co-authored-by: Rachael Sewell <rachmari@github.com>
This commit is contained in:
Laura Coursen
2021-10-15 15:41:33 -05:00
committed by GitHub
parent be8cb7cb8c
commit 8f964ea2cb
1592 changed files with 4984 additions and 3494 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
content/developers/apps/getting-started-with-apps/about-apps.md
View File

@@ -1,6 +1,6 @@
---
title: About apps
intro: 'You can build integrations with the {% data variables.product.prodname_dotcom %} APIs to add flexibility and reduce friction in your own workflow.{% ifversion fpt %} You can also share integrations with others on [{% data variables.product.prodname_marketplace %}](https://github.com/marketplace).{% endif %}'
intro: 'You can build integrations with the {% ifversion fpt or ghec %}{% data variables.product.prodname_dotcom %}{% else %}{% data variables.product.product_name %}{% endif %} APIs to add flexibility and reduce friction in your own workflow.{% ifversion fpt or ghec %} You can also share integrations with others on [{% data variables.product.prodname_marketplace %}](https://github.com/marketplace).{% endif %}'
redirect_from:
- /apps/building-integrations/setting-up-a-new-integration/
- /apps/building-integrations/
@@ -11,10 +11,11 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- GitHub Apps
---
Apps on {% data variables.product.prodname_dotcom %} allow you to automate and improve your workflow. You can build apps to improve your workflow.{% ifversion fpt %} You can also share or sell apps in [{% data variables.product.prodname_marketplace %}](https://github.com/marketplace). To learn how to list an app on {% data variables.product.prodname_marketplace %}, see "[Getting started with GitHub Marketplace](/marketplace/getting-started/)."{% endif %}
Apps on {% data variables.product.prodname_dotcom %} allow you to automate and improve your workflow. You can build apps to improve your workflow.{% ifversion fpt or ghec %} You can also share or sell apps in [{% data variables.product.prodname_marketplace %}](https://github.com/marketplace). To learn how to list an app on {% data variables.product.prodname_marketplace %}, see "[Getting started with GitHub Marketplace](/marketplace/getting-started/)."{% endif %}
{% data reusables.marketplace.github_apps_preferred %}, but GitHub supports both {% data variables.product.prodname_oauth_apps %} and {% data variables.product.prodname_github_apps %}. For information on choosing a type of app, see "[Differences between GitHub Apps and OAuth Apps](/developers/apps/differences-between-github-apps-and-oauth-apps)."
@@ -36,7 +37,7 @@ To improve your workflow, you can create a {% data variables.product.prodname_gi
Keep these ideas in mind when creating {% data variables.product.prodname_github_apps %}:
{% ifversion fpt %}
{% ifversion fpt or ghec %}
* {% data reusables.apps.maximum-github-apps-allowed %} {% endif %}
* A {% data variables.product.prodname_github_app %} should take actions independent of a user (unless the app is using a [user-to-server](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps#user-to-server-requests) token). {% data reusables.apps.expiring_user_authorization_tokens %}
@@ -44,10 +45,10 @@ Keep these ideas in mind when creating {% data variables.product.prodname_github
* The {% data variables.product.prodname_github_app %} should connect to a personal account or an organization.
* Don't expect the {% data variables.product.prodname_github_app %} to know and do everything a user can.
* Don't use a {% data variables.product.prodname_github_app %} if you just need a "Login with GitHub" service. But a {% data variables.product.prodname_github_app %} can use a [user identification flow](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/) to log users in _and_ do other things.
* Don't build a {% data variables.product.prodname_github_app %} if you _only_ want to act as a GitHub user and do everything that user can do.{% ifversion fpt %}
* Don't build a {% data variables.product.prodname_github_app %} if you _only_ want to act as a GitHub user and do everything that user can do.{% ifversion fpt or ghec %}
* {% data reusables.apps.general-apps-restrictions %}{% endif %}
To begin developing {% data variables.product.prodname_github_apps %}, start with "[Creating a {% data variables.product.prodname_github_app %}](/apps/building-github-apps/creating-a-github-app/)."{% ifversion fpt %} To learn how to use {% data variables.product.prodname_github_app %} Manifests, which allow people to create preconfigured {% data variables.product.prodname_github_apps %}, see "[Creating {% data variables.product.prodname_github_apps %} from a manifest](/apps/building-github-apps/creating-github-apps-from-a-manifest/)."{% endif %}
To begin developing {% data variables.product.prodname_github_apps %}, start with "[Creating a {% data variables.product.prodname_github_app %}](/apps/building-github-apps/creating-a-github-app/)."{% ifversion fpt or ghec %} To learn how to use {% data variables.product.prodname_github_app %} Manifests, which allow people to create preconfigured {% data variables.product.prodname_github_apps %}, see "[Creating {% data variables.product.prodname_github_apps %} from a manifest](/apps/building-github-apps/creating-github-apps-from-a-manifest/)."{% endif %}
## About {% data variables.product.prodname_oauth_apps %}
@@ -61,12 +62,12 @@ Building an {% data variables.product.prodname_oauth_app %} is a good option if
Keep these ideas in mind when creating {% data variables.product.prodname_oauth_apps %}:
{% ifversion fpt %}
{% ifversion fpt or ghec %}
* {% data reusables.apps.maximum-oauth-apps-allowed %} {% endif %}
* An {% data variables.product.prodname_oauth_app %} should always act as the authenticated {% data variables.product.prodname_dotcom %} user across all of {% data variables.product.prodname_dotcom %} (for example, when providing user notifications).
* An {% data variables.product.prodname_oauth_app %} can be used as an identity provider by enabling a "Login with {% data variables.product.prodname_dotcom %}" for the authenticated user.
* Don't build an {% data variables.product.prodname_oauth_app %} if you want your application to act on a single repository. With the `repo` OAuth scope, {% data variables.product.prodname_oauth_apps %} can act on _all_ of the authenticated user's repositories.
* Don't build an {% data variables.product.prodname_oauth_app %} to act as an application for your team or company. {% data variables.product.prodname_oauth_apps %} authenticate as a single user, so if one person creates an {% data variables.product.prodname_oauth_app %} for a company to use, and then they leave the company, no one else will have access to it.{% ifversion fpt %}
* Don't build an {% data variables.product.prodname_oauth_app %} to act as an application for your team or company. {% data variables.product.prodname_oauth_apps %} authenticate as a single user, so if one person creates an {% data variables.product.prodname_oauth_app %} for a company to use, and then they leave the company, no one else will have access to it.{% ifversion fpt or ghec %}
* {% data reusables.apps.oauth-apps-restrictions %}{% endif %}
For more on {% data variables.product.prodname_oauth_apps %}, see "[Creating an {% data variables.product.prodname_oauth_app %}](/apps/building-oauth-apps/creating-an-oauth-app/)" and "[Registering your app](/rest/guides/basics-of-authentication#registering-your-app)."
@@ -83,12 +84,12 @@ Keep these ideas in mind when using personal access tokens:
* You can perform one-off cURL requests.
* You can run personal scripts.
* Don't set up a script for your whole team or company to use.
* Don't set up a shared user account to act as a bot user.{% ifversion fpt or ghes > 3.2 or ghae-issue-4374 %}
* Don't set up a shared user account to act as a bot user.{% ifversion fpt or ghes > 3.2 or ghae-issue-4374 or ghec %}
* Do set an expiration for your personal access tokens, to help keep your information secure.{% endif %}
## Determining which integration to build
Before you get started creating integrations, you need to determine the best way to access, authenticate, and interact with the {% data variables.product.prodname_dotcom %} APIs. The following image offers some questions to ask yourself when deciding whether to use personal access tokens, {% data variables.product.prodname_github_apps %}, or {% data variables.product.prodname_oauth_apps %} for your integration.
Before you get started creating integrations, you need to determine the best way to access, authenticate, and interact with the {% ifversion fpt or ghec %}{% data variables.product.prodname_dotcom %}{% else %}{% data variables.product.product_name %}{% endif %} APIs. The following image offers some questions to ask yourself when deciding whether to use personal access tokens, {% data variables.product.prodname_github_apps %}, or {% data variables.product.prodname_oauth_apps %} for your integration.
![Intro to apps question flow](/assets/images/intro-to-apps-flow.png)

1
content/developers/apps/getting-started-with-apps/activating-optional-features-for-apps.md
View File

@@ -8,6 +8,7 @@ versions:
fpt: '*'
ghae: '*'
ghes: '*'
ghec: '*'
topics:
- GitHub Apps
shortTitle: Activate optional features

3
content/developers/apps/getting-started-with-apps/differences-between-github-apps-and-oauth-apps.md
View File

@@ -10,6 +10,7 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- GitHub Apps
- OAuth Apps
@@ -60,7 +61,7 @@ An _authorized_ OAuth App has access to all of the user's or organization owner'
| A GitHub App can request an installation access token by using a private key with a JSON web token format out-of-band. | An OAuth app can exchange a request token for an access token after a redirect via a web request. |
| An installation token identifies the app as the GitHub Apps bot, such as @jenkins-bot. | An access token identifies the app as the user who granted the token to the app, such as @octocat. |
| Installation tokens expire after a predefined amount of time (currently 1 hour). | OAuth tokens remain active until they're revoked by the customer. |
| {% data reusables.apps.api-rate-limits-non-ghec %}{% ifversion fpt %} Higher rate limits apply for {% data variables.product.prodname_ghe_cloud %}. For more information, see "[Rate limits for GitHub Apps](/developers/apps/rate-limits-for-github-apps)."{% endif %} | OAuth tokens use the user's rate limit of 5,000 requests per hour. |
| {% data reusables.apps.api-rate-limits-non-ghec %}{% ifversion fpt or ghec %} Higher rate limits apply for {% data variables.product.prodname_ghe_cloud %}. For more information, see "[Rate limits for GitHub Apps](/developers/apps/rate-limits-for-github-apps)."{% endif %} | OAuth tokens use the user's rate limit of 5,000 requests per hour. |
| Rate limit increases can be granted both at the GitHub Apps level (affecting all installations) and at the individual installation level. | Rate limit increases are granted per OAuth App. Every token granted to that OAuth App gets the increased limit. |
| {% data variables.product.prodname_github_apps %} can authenticate on behalf of the user, which is called user-to-server requests. The flow to authorize is the same as the OAuth App authorization flow. User-to-server tokens can expire and be renewed with a refresh token. For more information, see "[Refreshing user-to-server access tokens](/apps/building-github-apps/refreshing-user-to-server-access-tokens/)" and "[Identifying and authorizing users for GitHub Apps](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/)." | The OAuth flow used by {% data variables.product.prodname_oauth_apps %} authorizes an {% data variables.product.prodname_oauth_app %} on behalf of the user. This is the same flow used in {% data variables.product.prodname_github_app %} user-to-server authorization. |

1
content/developers/apps/getting-started-with-apps/index.md
View File

@@ -5,6 +5,7 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- GitHub Apps
children:

7
content/developers/apps/getting-started-with-apps/migrating-oauth-apps-to-github-apps.md
View File

@@ -8,6 +8,7 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- GitHub Apps
shortTitle: Migrate from OAuth Apps
@@ -30,7 +31,7 @@ This article provides guidelines for existing integrators who are considering mi
## Converting an OAuth App to a GitHub App
These guidelines assume that you have a registered OAuth App{% ifversion fpt %} that may or may not be listed in GitHub Marketplace{% endif %}. At a high level, you'll need to follow these steps:
These guidelines assume that you have a registered OAuth App{% ifversion fpt or ghec %} that may or may not be listed in GitHub Marketplace{% endif %}. At a high level, you'll need to follow these steps:
1. [Review the available API endpoints for GitHub Apps](#review-the-available-api-endpoints-for-github-apps)
1. [Design to stay within API rate limits](#design-to-stay-within-api-rate-limits)
@@ -45,13 +46,13 @@ These guidelines assume that you have a registered OAuth App{% ifversion fpt %}
### Review the available API endpoints for GitHub Apps
While the majority of [REST API](/rest) endpoints and [GraphQL](/graphql) queries are available to GitHub Apps today, we are still in the process of enabling some endpoints. Review the [available REST endpoints](/rest/overview/endpoints-available-for-github-apps) to ensure that the endpoints you need are compatible with GitHub Apps. Note that some of the API endpoints enabled for GitHub Apps allow the app to act on behalf of the user. See "[User-to-server requests](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/#user-to-server-requests)" for a list of endpoints that allow a GitHub App to authenticate as a user.
While the majority of [REST API](/rest) endpoints and [GraphQL]({% ifversion ghec %}/free-pro-team@latest{% endif %}/graphql) queries are available to GitHub Apps today, we are still in the process of enabling some endpoints. Review the [available REST endpoints](/rest/overview/endpoints-available-for-github-apps) to ensure that the endpoints you need are compatible with GitHub Apps. Note that some of the API endpoints enabled for GitHub Apps allow the app to act on behalf of the user. See "[User-to-server requests](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/#user-to-server-requests)" for a list of endpoints that allow a GitHub App to authenticate as a user.
We recommend reviewing the list of API endpoints you need as early as possible. Please let Support know if there is an endpoint you require that is not yet enabled for {% data variables.product.prodname_github_apps %}.
### Design to stay within API rate limits
GitHub Apps use [sliding rules for rate limits](/apps/building-github-apps/understanding-rate-limits-for-github-apps/), which can increase based on the number of repositories and users in the organization. A GitHub App can also make use of [conditional requests](/rest/overview/resources-in-the-rest-api#conditional-requests) or consolidate requests by using the [GraphQL API V4](/graphql).
GitHub Apps use [sliding rules for rate limits](/apps/building-github-apps/understanding-rate-limits-for-github-apps/), which can increase based on the number of repositories and users in the organization. A GitHub App can also make use of [conditional requests](/rest/overview/resources-in-the-rest-api#conditional-requests) or consolidate requests by using the [GraphQL API V4]({% ifversion ghec %}/free-pro-team@latest{% endif %}/graphql).
### Register a new GitHub App

3
content/developers/apps/getting-started-with-apps/setting-up-your-development-environment-to-create-a-github-app.md
View File

@@ -8,6 +8,7 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- GitHub Apps
shortTitle: Development environment
@@ -16,7 +17,7 @@ shortTitle: Development environment
This guide will walk through the steps needed to configure a GitHub App and run it on a server. GitHub Apps require some setup steps to manage webhook events and connect the app registration on GitHub to your code. The app in this guide serves as a foundation that you can use to extend and build new GitHub Apps.
By the end of this guide you'll have registered a GitHub App and set up a web server to receive webhook events. You'll learn how to use a tool called Smee to capture webhook payloads and forward them to your local development environment. The template app you'll configure in this section won't do anything special yet, but it will serve as a framework you can use to start writing app code using the API or complete other [quickstart guides](/apps/quickstart-guides/). {% ifversion fpt %}You can check out successful examples of apps on [GitHub Marketplace](https://github.com/marketplace) and [Works with GitHub](https://github.com/works-with).{% endif %}
By the end of this guide you'll have registered a GitHub App and set up a web server to receive webhook events. You'll learn how to use a tool called Smee to capture webhook payloads and forward them to your local development environment. The template app you'll configure in this section won't do anything special yet, but it will serve as a framework you can use to start writing app code using the API or complete other [quickstart guides](/apps/quickstart-guides/). {% ifversion fpt or ghec %}You can check out successful examples of apps on [GitHub Marketplace](https://github.com/marketplace) and [Works with GitHub](https://github.com/works-with).{% endif %}
After completing this project you will understand how to authenticate as a GitHub App and an installation, and how those authentication methods are different.