jprdonnelly/docs
1
0
Fork 0
mirror of synced 2025-12-23 11:54:18 -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

1
content/developers/apps/building-github-apps/authenticating-with-github-apps.md
View File

@@ -10,6 +10,7 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- GitHub Apps
shortTitle: Authentication

9
content/developers/apps/building-github-apps/creating-a-custom-badge-for-your-github-app.md
View File

@@ -8,6 +8,7 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- GitHub Apps
shortTitle: Custom badges
@@ -19,9 +20,9 @@ An identicon badge looks something like this:
After you create a GitHub App, you can customize your app's badge by uploading a logo and selecting a background color. A badge is a square logo image inside of a circular badge. You can choose a background color for the badge, which can visually distinguish your app.
Your logo should be a PNG, JPG, or GIF file under 1 MB in size. For the best quality rendering, we recommend an image size of at least 200px x 200px. {% ifversion fpt %}See "[Tips for logo and badge images](/marketplace/listing-on-github-marketplace/writing-github-marketplace-listing-descriptions/#guidelines-for-logos)" for more guidance on customizing badges.{% endif %}
Your logo should be a PNG, JPG, or GIF file under 1 MB in size. For the best quality rendering, we recommend an image size of at least 200px x 200px. {% ifversion fpt or ghec %}See "[Tips for logo and badge images](/marketplace/listing-on-github-marketplace/writing-github-marketplace-listing-descriptions/#guidelines-for-logos)" for more guidance on customizing badges.{% endif %}
{% ifversion fpt %}
{% ifversion fpt or ghec %}
You can change a custom badge for a GitHub App that already has an approved Marketplace listing by navigating to https://github.com/marketplace/manage.
@@ -37,10 +38,10 @@ To create a custom badge:
![Upload a logo](/assets/images/github-apps/github_apps_upload_logo.png)
6. Crop your picture. When you're done, click **Set new avatar**.
![Crop and set logo ](/assets/images/github-apps/github_apps_crop_and_set_avatar.png)
7. In "Badge background color", type the [hexadecimal color code](http://www.color-hex.com/) of the background color for your badge. {% ifversion fpt %}**Note:** The "Badge background color" input field will only appear after you upload an application logo.{% endif %}
7. In "Badge background color", type the [hexadecimal color code](http://www.color-hex.com/) of the background color for your badge. {% ifversion fpt or ghec %}**Note:** The "Badge background color" input field will only appear after you upload an application logo.{% endif %}
![Badge background color](/assets/images/github-apps/github_apps_badge_background_color.png)
{% ifversion fpt %}
{% ifversion fpt or ghec %}
## Next steps

7
content/developers/apps/building-github-apps/creating-a-github-app-from-a-manifest.md
View File

@@ -8,6 +8,7 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- GitHub Apps
shortTitle: App creation manifest flow
@@ -59,7 +60,7 @@ The person creating the app will be redirected to a GitHub page with an input fi
`name` | `string` | The name of the GitHub App.
`url` | `string` | **Required.** The homepage of your GitHub App.
`hook_attributes` | `object` | The configuration of the GitHub App's webhook.
`redirect_url` | `string` | The full URL to redirect to after a user initiates the creation of a GitHub App from a manifest.{% ifversion fpt or ghae-next or ghes > 3.0 %}
`redirect_url` | `string` | The full URL to redirect to after a user initiates the creation of a GitHub App from a manifest.{% ifversion fpt or ghae-next or ghes > 3.0 or ghec %}
`callback_urls` | `array of strings` | A full URL to redirect to after someone authorizes an installation. You can provide up to 10 callback URLs.{% else %}
`callback_url` | `string` | A full URL to redirect to after someone authorizes an installation.{% endif %}
`description` | `string` | A description of the GitHub App.
@@ -99,7 +100,7 @@ This example uses a form on a web page with a button that triggers the `POST` re
"url": "https://example.com/github/events",
},
"redirect_url": "https://example.com/redirect",
{% ifversion fpt or ghae-next or ghes > 3.0 %}"callback_urls": [
{% ifversion fpt or ghae-next or ghes > 3.0 or ghec %}"callback_urls": [
"https://example.com/callback"
],{% else %}"callback_url": "https://example.com/callback",{% endif %}
"public": true,
@@ -134,7 +135,7 @@ This example uses a form on a web page with a button that triggers the `POST` re
"url": "https://example.com/github/events",
},
"redirect_url": "https://example.com/redirect",
{% ifversion fpt or ghae-next or ghes > 3.0 %}"callback_urls": [
{% ifversion fpt or ghae-next or ghes > 3.0 or ghec %}"callback_urls": [
"https://example.com/callback"
],{% else %}"callback_url": "https://example.com/callback",{% endif %}
"public": true,

27
content/developers/apps/building-github-apps/creating-a-github-app-using-url-parameters.md
View File

@@ -8,6 +8,7 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- GitHub Apps
shortTitle: App creation query parameters
@@ -21,13 +22,13 @@ You can add query parameters to these URLs to preselect the configuration of a {
The person creating the app can edit the preselected values from the {% data variables.product.prodname_github_app %} registration page, before submitting the app. If you do not include required parameters in the URL query string, like `name`, the person creating the app will need to input a value before submitting the app.
{% ifversion ghes > 3.1 or fpt or ghae-next %}
{% ifversion ghes > 3.1 or fpt or ghae-next or ghec %}
For apps that require a secret to secure their webhook, the secret's value must be set in the form by the person creating the app, not by using query parameters. For more information, see "[Securing your webhooks](/developers/webhooks-and-events/webhooks/securing-your-webhooks)."
{% endif %}
The following URL creates a new public app called `octocat-github-app` with a preconfigured description and callback URL. This URL also selects read and write permissions for `checks`, subscribes to the `check_run` and `check_suite` webhook events, and selects the option to request user authorization (OAuth) during installation:
{% ifversion fpt or ghae-next or ghes > 3.0 %}
{% ifversion fpt or ghae-next or ghes > 3.0 or ghec %}
```text
{% data variables.product.oauth_host_code %}/settings/apps/new?name=octocat-github-app&description=An%20Octocat%20App&callback_urls[]=https://example.com&request_oauth_on_install=true&public=true&checks=write&events[]=check_run&events[]=check_suite
@@ -49,7 +50,7 @@ The complete list of available query parameters, permissions, and events is list
-----|------|-------------
`name` | `string` | The name of the {% data variables.product.prodname_github_app %}. Give your app a clear and succinct name. Your app cannot have the same name as an existing GitHub user, unless it is your own user or organization name. A slugged version of your app's name will be shown in the user interface when your integration takes an action.
`description` | `string` | A description of the {% data variables.product.prodname_github_app %}.
`url` | `string` | The full URL of your {% data variables.product.prodname_github_app %}'s website homepage.{% ifversion fpt or ghae-next or ghes > 3.0 %}
`url` | `string` | The full URL of your {% data variables.product.prodname_github_app %}'s website homepage.{% ifversion fpt or ghae-next or ghes > 3.0 or ghec %}
`callback_urls` | `array of strings` | A full URL to redirect to after someone authorizes an installation. You can provide up to 10 callback URLs. These URLs are used if your app needs to identify and authorize user-to-server requests. For example, `callback_urls[]=https://example.com&callback_urls[]=https://example-2.com`.{% else %}
`callback_url` | `string` | The full URL to redirect to after someone authorizes an installation. This URL is used if your app needs to identify and authorize user-to-server requests.{% endif %}
`request_oauth_on_install` | `boolean` | If your app authorizes users using the OAuth flow, you can set this option to `true` to allow people to authorize the app when they install it, saving a step. If you select this option, the `setup_url` becomes unavailable and users will be redirected to your `callback_url` after installing the app.
@@ -60,7 +61,7 @@ The complete list of available query parameters, permissions, and events is list
{% ifversion ghes < 3.2 or ghae %}`webhook_secret` | `string` | You can specify a secret to secure your webhooks. See "[Securing your webhooks](/webhooks/securing/)" for more details.
{% endif %}`events` | `array of strings` | Webhook events. Some webhook events require `read` or `write` permissions for a resource before you can select the event when registering a new {% data variables.product.prodname_github_app %}. See the "[{% data variables.product.prodname_github_app %} webhook events](#github-app-webhook-events)" section for available events and their required permissions. You can select multiple events in a query string. For example, `events[]=public&events[]=label`.
`domain` | `string` | The URL of a content reference.
`single_file_name` | `string` | This is a narrowly-scoped permission that allows the app to access a single file in any repository. When you set the `single_file` permission to `read` or `write`, this field provides the path to the single file your {% data variables.product.prodname_github_app %} will manage. {% ifversion fpt or ghes > 2.22 %} If you need to manage multiple files, see `single_file_paths` below. {% endif %}{% ifversion fpt or ghes > 2.22 %}
`single_file_name` | `string` | This is a narrowly-scoped permission that allows the app to access a single file in any repository. When you set the `single_file` permission to `read` or `write`, this field provides the path to the single file your {% data variables.product.prodname_github_app %} will manage. {% ifversion fpt or ghes > 2.22 or ghec %} If you need to manage multiple files, see `single_file_paths` below. {% endif %}{% ifversion fpt or ghes > 2.22 or ghec %}
`single_file_paths` | `array of strings` | This allows the app to access up ten specified files in a repository. When you set the `single_file` permission to `read` or `write`, this array can store the paths for up to ten files that your {% data variables.product.prodname_github_app %} will manage. These files all receive the same permission set by `single_file`, and do not have separate individual permissions. When two or more files are configured, the API returns `multiple_single_files=true`, otherwise it returns `multiple_single_files=false`.{% endif %}
## {% data variables.product.prodname_github_app %} permissions
@@ -69,35 +70,35 @@ You can select permissions in a query string using the permission name in the fo
Permission | Description
---------- | -----------
[`administration`](/rest/reference/permissions-required-for-github-apps/#permission-on-administration) | Grants access to various endpoints for organization and repository administration. Can be one of: `none`, `read`, or `write`.{% ifversion fpt %}
[`administration`](/rest/reference/permissions-required-for-github-apps/#permission-on-administration) | Grants access to various endpoints for organization and repository administration. Can be one of: `none`, `read`, or `write`.{% ifversion fpt or ghec %}
[`blocking`](/rest/reference/permissions-required-for-github-apps/#permission-on-blocking) | Grants access to the [Blocking Users API](/rest/reference/users#blocking). Can be one of: `none`, `read`, or `write`.{% endif %}
[`checks`](/rest/reference/permissions-required-for-github-apps/#permission-on-checks) | Grants access to the [Checks API](/rest/reference/checks). Can be one of: `none`, `read`, or `write`.
`content_references` | Grants access to the "[Create a content attachment](/rest/reference/apps#create-a-content-attachment)" endpoint. Can be one of: `none`, `read`, or `write`.
[`contents`](/rest/reference/permissions-required-for-github-apps/#permission-on-contents) | Grants access to various endpoints that allow you to modify repository contents. Can be one of: `none`, `read`, or `write`.
[`deployments`](/rest/reference/permissions-required-for-github-apps/#permission-on-deployments) | Grants access to the [Deployments API](/rest/reference/repos#deployments). Can be one of: `none`, `read`, or `write`.{% ifversion fpt or ghes %}
[`deployments`](/rest/reference/permissions-required-for-github-apps/#permission-on-deployments) | Grants access to the [Deployments API](/rest/reference/repos#deployments). Can be one of: `none`, `read`, or `write`.{% ifversion fpt or ghes or ghec %}
[`emails`](/rest/reference/permissions-required-for-github-apps/#permission-on-emails) | Grants access to the [Emails API](/rest/reference/users#emails). Can be one of: `none`, `read`, or `write`.{% endif %}
[`followers`](/rest/reference/permissions-required-for-github-apps/#permission-on-followers) | Grants access to the [Followers API](/rest/reference/users#followers). Can be one of: `none`, `read`, or `write`.
[`gpg_keys`](/rest/reference/permissions-required-for-github-apps/#permission-on-gpg-keys) | Grants access to the [GPG Keys API](/rest/reference/users#gpg-keys). Can be one of: `none`, `read`, or `write`.
[`issues`](/rest/reference/permissions-required-for-github-apps/#permission-on-issues) | Grants access to the [Issues API](/rest/reference/issues). Can be one of: `none`, `read`, or `write`.
[`keys`](/rest/reference/permissions-required-for-github-apps/#permission-on-keys) | Grants access to the [Public Keys API](/rest/reference/users#keys). Can be one of: `none`, `read`, or `write`.
[`members`](/rest/reference/permissions-required-for-github-apps/#permission-on-members) | Grants access to manage an organization's members. Can be one of: `none`, `read`, or `write`.{% ifversion fpt %}
[`members`](/rest/reference/permissions-required-for-github-apps/#permission-on-members) | Grants access to manage an organization's members. Can be one of: `none`, `read`, or `write`.{% ifversion fpt or ghec %}
[`metadata`](/rest/reference/permissions-required-for-github-apps/#metadata-permissions) | Grants access to read-only endpoints that do not leak sensitive data. Can be `read` or `none`. Defaults to `read` when you set any permission, or defaults to `none` when you don't specify any permissions for the {% data variables.product.prodname_github_app %}.
[`organization_administration`](/rest/reference/permissions-required-for-github-apps/#permission-on-organization-administration) | Grants access to "[Update an organization](/rest/reference/orgs#update-an-organization)" endpoint and the [Organization Interaction Restrictions API](/rest/reference/interactions#set-interaction-restrictions-for-an-organization). Can be one of: `none`, `read`, or `write`.{% endif %}
[`organization_hooks`](/rest/reference/permissions-required-for-github-apps/#permission-on-organization-hooks) | Grants access to the [Organization Webhooks API](/rest/reference/orgs#webhooks/). Can be one of: `none`, `read`, or `write`.
`organization_plan` | Grants access to get information about an organization's plan using the "[Get an organization](/rest/reference/orgs#get-an-organization)" endpoint. Can be one of: `none` or `read`.
[`organization_projects`](/rest/reference/permissions-required-for-github-apps/#permission-on-organization-projects) | Grants access to the [Projects API](/rest/reference/projects). Can be one of: `none`, `read`, `write`, or `admin`.{% ifversion fpt %}
[`organization_projects`](/rest/reference/permissions-required-for-github-apps/#permission-on-organization-projects) | Grants access to the [Projects API](/rest/reference/projects). Can be one of: `none`, `read`, `write`, or `admin`.{% ifversion fpt or ghec %}
[`organization_user_blocking`](/rest/reference/permissions-required-for-github-apps/#permission-on-organization-projects) | Grants access to the [Blocking Organization Users API](/rest/reference/orgs#blocking). Can be one of: `none`, `read`, or `write`.{% endif %}
[`pages`](/rest/reference/permissions-required-for-github-apps/#permission-on-pages) | Grants access to the [Pages API](/rest/reference/repos#pages). Can be one of: `none`, `read`, or `write`.
`plan` | Grants access to get information about a user's GitHub plan using the "[Get a user](/rest/reference/users#get-a-user)" endpoint. Can be one of: `none` or `read`.
[`pull_requests`](/rest/reference/permissions-required-for-github-apps/#permission-on-pull-requests) | Grants access to various pull request endpoints. Can be one of: `none`, `read`, or `write`.
[`repository_hooks`](/rest/reference/permissions-required-for-github-apps/#permission-on-repository-hooks) | Grants access to the [Repository Webhooks API](/rest/reference/repos#hooks). Can be one of: `none`, `read`, or `write`.
[`repository_projects`](/rest/reference/permissions-required-for-github-apps/#permission-on-repository-projects) | Grants access to the [Projects API](/rest/reference/projects). Can be one of: `none`, `read`, `write`, or `admin`.{% ifversion fpt or ghes > 3.0 %}
[`secret_scanning_alerts`](/rest/reference/permissions-required-for-github-apps/#permission-on-secret-scanning-alerts) | Grants access to the [Secret scanning API](/rest/reference/secret-scanning). Can be one of: `none`, `read`, or `write`.{% endif %}{% ifversion fpt or ghes %}
[`repository_projects`](/rest/reference/permissions-required-for-github-apps/#permission-on-repository-projects) | Grants access to the [Projects API](/rest/reference/projects). Can be one of: `none`, `read`, `write`, or `admin`.{% ifversion fpt or ghes > 3.0 or ghec %}
[`secret_scanning_alerts`](/rest/reference/permissions-required-for-github-apps/#permission-on-secret-scanning-alerts) | Grants access to the [Secret scanning API](/rest/reference/secret-scanning). Can be one of: `none`, `read`, or `write`.{% endif %}{% ifversion fpt or ghes or ghec %}
[`security_events`](/rest/reference/permissions-required-for-github-apps/#permission-on-security-events) | Grants access to the [Code scanning API](/rest/reference/code-scanning/). Can be one of: `none`, `read`, or `write`.{% endif %}
[`single_file`](/rest/reference/permissions-required-for-github-apps/#permission-on-single-file) | Grants access to the [Contents API](/rest/reference/repos#contents). Can be one of: `none`, `read`, or `write`.
[`starring`](/rest/reference/permissions-required-for-github-apps/#permission-on-starring) | Grants access to the [Starring API](/rest/reference/activity#starring). Can be one of: `none`, `read`, or `write`.
[`statuses`](/rest/reference/permissions-required-for-github-apps/#permission-on-statuses) | Grants access to the [Statuses API](/rest/reference/repos#statuses). Can be one of: `none`, `read`, or `write`.
[`team_discussions`](/rest/reference/permissions-required-for-github-apps/#permission-on-team-discussions) | Grants access to the [Team Discussions API](/rest/reference/teams#discussions) and the [Team Discussion Comments API](/rest/reference/teams#discussion-comments). Can be one of: `none`, `read`, or `write`.{% ifversion fpt or ghes or ghae-issue-4864 %}
[`team_discussions`](/rest/reference/permissions-required-for-github-apps/#permission-on-team-discussions) | Grants access to the [Team Discussions API](/rest/reference/teams#discussions) and the [Team Discussion Comments API](/rest/reference/teams#discussion-comments). Can be one of: `none`, `read`, or `write`.{% ifversion fpt or ghes or ghae-issue-4864 or ghec %}
`vulnerability_alerts`| Grants access to receive security alerts for vulnerable dependencies in a repository. See "[About alerts for vulnerable dependencies](/github/managing-security-vulnerabilities/about-alerts-for-vulnerable-dependencies/)" to learn more. Can be one of: `none` or `read`.{% endif %}
`watching` | Grants access to list and change repositories a user is subscribed to. Can be one of: `none`, `read`, or `write`.
@@ -120,7 +121,7 @@ Webhook event name | Required permission | Description
[`label`](/webhooks/event-payloads/#label) | `metadata` | {% data reusables.webhooks.label_short_desc %}
[`member`](/webhooks/event-payloads/#member) | `members` | {% data reusables.webhooks.member_short_desc %}
[`membership`](/webhooks/event-payloads/#membership) | `members` | {% data reusables.webhooks.membership_short_desc %}
[`milestone`](/webhooks/event-payloads/#milestone) | `pull_request` | {% data reusables.webhooks.milestone_short_desc %}{% ifversion fpt %}
[`milestone`](/webhooks/event-payloads/#milestone) | `pull_request` | {% data reusables.webhooks.milestone_short_desc %}{% ifversion fpt or ghec %}
[`org_block`](/webhooks/event-payloads/#org_block) | `organization_administration` | {% data reusables.webhooks.org_block_short_desc %}{% endif %}
[`organization`](/webhooks/event-payloads/#organization) | `members` | {% data reusables.webhooks.organization_short_desc %}
[`page_build`](/webhooks/event-payloads/#page_build) | `pages` | {% data reusables.webhooks.page_build_short_desc %}
@@ -133,7 +134,7 @@ Webhook event name | Required permission | Description
[`pull_request_review_comment`](/webhooks/event-payloads/#pull_request_review_comment) | `pull_request` | {% data reusables.webhooks.pull_request_review_comment_short_desc %}
[`push`](/webhooks/event-payloads/#push) | `contents` | {% data reusables.webhooks.push_short_desc %}
[`release`](/webhooks/event-payloads/#release) | `contents` | {% data reusables.webhooks.release_short_desc %}
[`repository`](/webhooks/event-payloads/#repository) |`metadata` | {% data reusables.webhooks.repository_short_desc %}{% ifversion fpt %}
[`repository`](/webhooks/event-payloads/#repository) |`metadata` | {% data reusables.webhooks.repository_short_desc %}{% ifversion fpt or ghec %}
[`repository_dispatch`](/webhooks/event-payloads/#repository_dispatch) | `contents` | Allows integrators using GitHub Actions to trigger custom events.{% endif %}
[`status`](/webhooks/event-payloads/#status) | `statuses` | {% data reusables.webhooks.status_short_desc %}
[`team`](/webhooks/event-payloads/#team) | `members` | {% data reusables.webhooks.team_short_desc %}

7
content/developers/apps/building-github-apps/creating-a-github-app.md
View File

@@ -10,12 +10,13 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- GitHub Apps
---
{% ifversion fpt %}To learn how to use GitHub App Manifests, which allow people to create preconfigured GitHub Apps, see "[Creating GitHub Apps from a manifest](/apps/building-github-apps/creating-github-apps-from-a-manifest/)."{% endif %}
{% ifversion fpt or ghec %}To learn how to use GitHub App Manifests, which allow people to create preconfigured GitHub Apps, see "[Creating GitHub Apps from a manifest](/apps/building-github-apps/creating-github-apps-from-a-manifest/)."{% endif %}
{% ifversion fpt %}
{% ifversion fpt or ghec %}
{% note %}
**Note:** {% data reusables.apps.maximum-github-apps-allowed %}
@@ -37,7 +38,7 @@ topics:
![Field for a description of your GitHub App](/assets/images/github-apps/github_apps_description.png)
1. In "Homepage URL", type the full URL to your app's website.
![Field for the homepage URL of your GitHub App](/assets/images/github-apps/github_apps_homepage_url.png)
{% ifversion fpt or ghes > 3.0 %}
{% ifversion fpt or ghes > 3.0 or ghec %}
1. In "Callback URL", type the full URL to redirect to after a user authorizes the installation. This URL is used if your app needs to identify and authorize user-to-server requests.
You can use **Add callback URL** to provide additional callback URLs, up to a maximum of 10.

67
content/developers/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps.md
View File

@@ -10,6 +10,7 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- GitHub Apps
shortTitle: Identify & authorize users
@@ -24,7 +25,7 @@ When your GitHub App acts on behalf of a user, it performs user-to-server reques
To authorize users for standard apps that run in the browser, use the [web application flow](#web-application-flow).
{% ifversion fpt or ghae or ghes > 3.0 %}
{% ifversion fpt or ghae or ghes > 3.0 or ghec %}
To authorize users for headless apps without direct access to the browser, such as CLI tools or Git credential managers, use the [device flow](#device-flow). The device flow uses the OAuth 2.0 [Device Authorization Grant](https://tools.ietf.org/html/rfc8628).
@@ -52,7 +53,7 @@ When your GitHub App specifies a `login` parameter, it prompts users with a spec
Name | Type | Description
-----|------|------------
`client_id` | `string` | **Required.** The client ID for your GitHub App. You can find this in your [GitHub App settings](https://github.com/settings/apps) when you select your app. **Note:** The app ID and client ID are not the same, and are not interchangeable.
`redirect_uri` | `string` | The URL in your application where users will be sent after authorization. This must be an exact match to {% ifversion fpt or ghes > 3.0 %} one of the URLs you provided as a **Callback URL** {% else %} the URL you provided in the **User authorization callback URL** field{% endif %} when setting up your GitHub App and can't contain any additional parameters.
`redirect_uri` | `string` | The URL in your application where users will be sent after authorization. This must be an exact match to {% ifversion fpt or ghes > 3.0 or ghec %} one of the URLs you provided as a **Callback URL** {% else %} the URL you provided in the **User authorization callback URL** field{% endif %} when setting up your GitHub App and can't contain any additional parameters.
`state` | `string` | This should contain a random string to protect against forgery attacks and could contain any other arbitrary data.
`login` | `string` | Suggests a specific account to use for signing in and authorizing the app.
`allow_signup` | `string` | Whether or not unauthenticated users will be offered an option to sign up for {% data variables.product.prodname_dotcom %} during the OAuth flow. The default is `true`. Use `false` when a policy prohibits signups.
@@ -88,7 +89,7 @@ Name | Type | Description
`client_id` | `string` | **Required.** The client ID for your GitHub App.
`client_secret` | `string` | **Required.** The client secret for your GitHub App.
`code` | `string` | **Required.** The code you received as a response to Step 1.
`redirect_uri` | `string` | The URL in your application where users will be sent after authorization. This must be an exact match to {% ifversion fpt or ghes > 3.0 %} one of the URLs you provided as a **Callback URL** {% else %} the URL you provided in the **User authorization callback URL** field{% endif %} when setting up your GitHub App and can't contain any additional parameters.
`redirect_uri` | `string` | The URL in your application where users will be sent after authorization. This must be an exact match to {% ifversion fpt or ghes > 3.0 or ghec %} one of the URLs you provided as a **Callback URL** {% else %} the URL you provided in the **User authorization callback URL** field{% endif %} when setting up your GitHub App and can't contain any additional parameters.
`state` | `string` | The unguessable random string you provided in Step 1.
#### Response
@@ -97,9 +98,9 @@ By default, the response takes the following form. The response parameters `expi
```json
{
"access_token": "{% ifversion fpt or ghes > 3.1 or ghae-next %}ghu_16C7e42F292c6912E7710c838347Ae178B4a{% else %}e72e16c7e42f292c6912e7710c838347ae178b4a{% endif %}",
"access_token": "{% ifversion fpt or ghes > 3.1 or ghae-next or ghec %}ghu_16C7e42F292c6912E7710c838347Ae178B4a{% else %}e72e16c7e42f292c6912e7710c838347ae178b4a{% endif %}",
"expires_in": 28800,
"refresh_token": "{% ifversion fpt or ghes > 3.1 or ghae-next %}ghr_1B4a2e77838347a7E420ce178F2E7c6912E169246c34E1ccbF66C46812d16D5B1A9Dc86A1498{% else %}r1.c1b4a2e77838347a7e420ce178f2e7c6912e1692{% endif %}",
"refresh_token": "{% ifversion fpt or ghes > 3.1 or ghae-next or ghec %}ghr_1B4a2e77838347a7E420ce178F2E7c6912E169246c34E1ccbF66C46812d16D5B1A9Dc86A1498{% else %}r1.c1b4a2e77838347a7e420ce178f2e7c6912e1692{% endif %}",
"refresh_token_expires_in": 15811200,
"scope": "",
"token_type": "bearer"
@@ -119,7 +120,7 @@ For example, in curl you can set the Authorization header like this:
curl -H "Authorization: token OAUTH-TOKEN" {% data variables.product.api_url_pre %}/user
```
{% ifversion fpt or ghae or ghes > 3.0 %}
{% ifversion fpt or ghae or ghes > 3.0 or ghec %}
## Device flow
@@ -166,11 +167,11 @@ Because user-level permissions are granted on an individual user basis, you can
## User-to-server requests
While most of your API interaction should occur using your server-to-server installation access tokens, certain endpoints allow you to perform actions via the API using a user access token. Your app can make the following requests using [GraphQL v4](/graphql) or [REST v3](/rest) endpoints.
While most of your API interaction should occur using your server-to-server installation access tokens, certain endpoints allow you to perform actions via the API using a user access token. Your app can make the following requests using [GraphQL v4]({% ifversion ghec %}/free-pro-team@latest{% endif %}/graphql) or [REST v3](/rest) endpoints.
### Supported endpoints
{% ifversion fpt %}
{% ifversion fpt or ghec %}
#### Actions Runners
* [List runner applications for a repository](/rest/reference/actions#list-runner-applications-for-a-repository)
@@ -204,7 +205,7 @@ While most of your API interaction should occur using your server-to-server inst
* [Delete an organization secret](/rest/reference/actions#delete-an-organization-secret)
{% endif %}
{% ifversion fpt %}
{% ifversion fpt or ghec %}
#### Artifacts
* [List artifacts for a repository](/rest/reference/actions#list-artifacts-for-a-repository)
@@ -246,7 +247,7 @@ While most of your API interaction should occur using your server-to-server inst
* [List deployments](/rest/reference/repos#list-deployments)
* [Create a deployment](/rest/reference/repos#create-a-deployment)
* [Get a deployment](/rest/reference/repos#get-a-deployment){% ifversion fpt or ghes or ghae %}
* [Get a deployment](/rest/reference/repos#get-a-deployment){% ifversion fpt or ghes or ghae or ghec %}
* [Delete a deployment](/rest/reference/repos#delete-a-deployment){% endif %}
#### Events
@@ -294,7 +295,7 @@ While most of your API interaction should occur using your server-to-server inst
* [List repositories accessible to the user access token](/rest/reference/apps#list-repositories-accessible-to-the-user-access-token)
{% ifversion fpt %}
{% ifversion fpt or ghec %}
#### Interaction Limits
* [Get interaction restrictions for an organization](/rest/reference/interactions#get-interaction-restrictions-for-an-organization)
@@ -339,7 +340,7 @@ While most of your API interaction should occur using your server-to-server inst
* [Lock an issue](/rest/reference/issues#lock-an-issue)
* [Unlock an issue](/rest/reference/issues#unlock-an-issue)
{% ifversion fpt %}
{% ifversion fpt or ghec %}
#### Jobs
* [Get a job for a workflow run](/rest/reference/actions#get-a-job-for-a-workflow-run)
@@ -392,7 +393,7 @@ While most of your API interaction should occur using your server-to-server inst
* [Delete an organization webhook](/rest/reference/orgs#webhooks/#delete-an-organization-webhook)
* [Ping an organization webhook](/rest/reference/orgs#webhooks/#ping-an-organization-webhook)
{% ifversion fpt %}
{% ifversion fpt or ghec %}
#### Organization Invitations
* [List pending organization invitations](/rest/reference/orgs#list-pending-organization-invitations)
@@ -428,7 +429,7 @@ While most of your API interaction should occur using your server-to-server inst
* [Remove pre-receive hook enforcement for an organization](/enterprise/user/rest/reference/enterprise-admin#remove-pre-receive-hook-enforcement-for-an-organization)
{% endif %}
{% ifversion fpt or ghes or ghae %}
{% ifversion fpt or ghes or ghae or ghec %}
#### Organization Team Projects
* [List team projects](/rest/reference/teams#list-team-projects)
@@ -444,7 +445,7 @@ While most of your API interaction should occur using your server-to-server inst
* [Add or update team repository permissions](/rest/reference/teams#add-or-update-team-repository-permissions)
* [Remove a repository from a team](/rest/reference/teams#remove-a-repository-from-a-team)
{% ifversion fpt %}
{% ifversion fpt or ghec %}
#### Organization Team Sync
* [List idp groups for a team](/rest/reference/teams#list-idp-groups-for-a-team)
@@ -459,7 +460,7 @@ While most of your API interaction should occur using your server-to-server inst
* [Get a team by name](/rest/reference/teams#get-a-team-by-name)
* [Update a team](/rest/reference/teams#update-a-team)
* [Delete a team](/rest/reference/teams#delete-a-team)
{% ifversion fpt %}
{% ifversion fpt or ghec %}
* [List pending team invitations](/rest/reference/teams#list-pending-team-invitations)
{% endif %}
* [List team members](/rest/reference/teams#list-team-members)
@@ -480,14 +481,14 @@ While most of your API interaction should occur using your server-to-server inst
* [List organizations for the authenticated user](/rest/reference/orgs#list-organizations-for-the-authenticated-user)
* [List organizations for a user](/rest/reference/orgs#list-organizations-for-a-user)
{% ifversion fpt %}
{% ifversion fpt or ghec %}
#### Organizations Credential Authorizations
* [List SAML SSO authorizations for an organization](/rest/reference/orgs#list-saml-sso-authorizations-for-an-organization)
* [Remove a SAML SSO authorization for an organization](/rest/reference/orgs#remove-a-saml-sso-authorization-for-an-organization)
{% endif %}
{% ifversion fpt %}
{% ifversion fpt or ghec %}
#### Organizations Scim
* [List SCIM provisioned identities](/rest/reference/scim#list-scim-provisioned-identities)
@@ -498,7 +499,7 @@ While most of your API interaction should occur using your server-to-server inst
* [Delete a SCIM user from an organization](/rest/reference/scim#delete-a-scim-user-from-an-organization)
{% endif %}
{% ifversion fpt %}
{% ifversion fpt or ghec %}
#### Source Imports
* [Get an import status](/rest/reference/migrations#get-an-import-status)
@@ -581,7 +582,7 @@ While most of your API interaction should occur using your server-to-server inst
#### Reactions
{% ifversion fpt or ghes or ghae %}* [Delete a reaction](/rest/reference/reactions#delete-a-reaction-legacy){% else %}* [Delete a reaction](/rest/reference/reactions#delete-a-reaction){% endif %}
{% ifversion fpt or ghes or ghae or ghec %}* [Delete a reaction](/rest/reference/reactions#delete-a-reaction-legacy){% else %}* [Delete a reaction](/rest/reference/reactions#delete-a-reaction){% endif %}
* [List reactions for a commit comment](/rest/reference/reactions#list-reactions-for-a-commit-comment)
* [Create reaction for a commit comment](/rest/reference/reactions#create-reaction-for-a-commit-comment)
* [List reactions for an issue](/rest/reference/reactions#list-reactions-for-an-issue)
@@ -593,7 +594,7 @@ While most of your API interaction should occur using your server-to-server inst
* [List reactions for a team discussion comment](/rest/reference/reactions#list-reactions-for-a-team-discussion-comment)
* [Create reaction for a team discussion comment](/rest/reference/reactions#create-reaction-for-a-team-discussion-comment)
* [List reactions for a team discussion](/rest/reference/reactions#list-reactions-for-a-team-discussion)
* [Create reaction for a team discussion](/rest/reference/reactions#create-reaction-for-a-team-discussion){% ifversion fpt or ghes or ghae %}
* [Create reaction for a team discussion](/rest/reference/reactions#create-reaction-for-a-team-discussion){% ifversion fpt or ghes or ghae or ghec %}
* [Delete a commit comment reaction](/rest/reference/reactions#delete-a-commit-comment-reaction)
* [Delete an issue reaction](/rest/reference/reactions#delete-an-issue-reaction)
* [Delete a reaction to a commit comment](/rest/reference/reactions#delete-an-issue-comment-reaction)
@@ -631,7 +632,7 @@ While most of your API interaction should occur using your server-to-server inst
* [Unstar a repository for the authenticated user](/rest/reference/activity#unstar-a-repository-for-the-authenticated-user)
* [List repositories watched by a user](/rest/reference/activity#list-repositories-watched-by-a-user)
{% ifversion fpt %}
{% ifversion fpt or ghec %}
#### Repository Automated Security Fixes
* [Enable automated security fixes](/rest/reference/repos#enable-automated-security-fixes)
@@ -700,7 +701,7 @@ While most of your API interaction should occur using your server-to-server inst
#### Repository Community
* [Get the code of conduct for a repository](/rest/reference/codes-of-conduct#get-the-code-of-conduct-for-a-repository)
{% ifversion fpt %}
{% ifversion fpt or ghec %}
* [Get community profile metrics](/rest/reference/repos#get-community-profile-metrics)
{% endif %}
@@ -713,7 +714,7 @@ While most of your API interaction should occur using your server-to-server inst
* [Get a repository README](/rest/reference/repos#get-a-repository-readme)
* [Get the license for a repository](/rest/reference/licenses#get-the-license-for-a-repository)
{% ifversion fpt or ghes or ghae %}
{% ifversion fpt or ghes or ghae or ghec %}
#### Repository Event Dispatches
* [Create a repository dispatch event](/rest/reference/repos#create-a-repository-dispatch-event)
@@ -787,7 +788,7 @@ While most of your API interaction should occur using your server-to-server inst
* [Get the weekly commit count](/rest/reference/repos#get-the-weekly-commit-count)
* [Get the hourly commit count for each day](/rest/reference/repos#get-the-hourly-commit-count-for-each-day)
{% ifversion fpt %}
{% ifversion fpt or ghec %}
#### Repository Vulnerability Alerts
* [Enable vulnerability alerts](/rest/reference/repos#enable-vulnerability-alerts)
@@ -833,7 +834,7 @@ While most of your API interaction should occur using your server-to-server inst
* [Get all repository topics](/rest/reference/repos#get-all-repository-topics)
* [Replace all repository topics](/rest/reference/repos#replace-all-repository-topics)
{% ifversion fpt %}
{% ifversion fpt or ghec %}
#### Traffic
* [Get repository clones](/rest/reference/repos#get-repository-clones)
@@ -842,7 +843,7 @@ While most of your API interaction should occur using your server-to-server inst
* [Get page views](/rest/reference/repos#get-page-views)
{% endif %}
{% ifversion fpt %}
{% ifversion fpt or ghec %}
#### User Blocking
* [List users blocked by the authenticated user](/rest/reference/users#list-users-blocked-by-the-authenticated-user)
@@ -855,10 +856,10 @@ While most of your API interaction should occur using your server-to-server inst
* [Unblock a user](/rest/reference/users#unblock-a-user)
{% endif %}
{% ifversion fpt or ghes %}
{% ifversion fpt or ghes or ghec %}
#### User Emails
{% ifversion fpt %}
{% ifversion fpt or ghec %}
* [Set primary email visibility for the authenticated user](/rest/reference/users#set-primary-email-visibility-for-the-authenticated-user)
{% endif %}
* [List email addresses for the authenticated user](/rest/reference/users#list-email-addresses-for-the-authenticated-user)
@@ -896,13 +897,13 @@ While most of your API interaction should occur using your server-to-server inst
* [Get the authenticated user](/rest/reference/users#get-the-authenticated-user)
* [List app installations accessible to the user access token](/rest/reference/apps#list-app-installations-accessible-to-the-user-access-token)
{% ifversion fpt %}
{% ifversion fpt or ghec %}
* [List subscriptions for the authenticated user](/rest/reference/apps#list-subscriptions-for-the-authenticated-user)
{% endif %}
* [List users](/rest/reference/users#list-users)
* [Get a user](/rest/reference/users#get-a-user)
{% ifversion fpt %}
{% ifversion fpt or ghec %}
#### Workflow Runs
* [List workflow runs for a repository](/rest/reference/actions#list-workflow-runs-for-a-repository)
@@ -915,7 +916,7 @@ While most of your API interaction should occur using your server-to-server inst
* [Get workflow run usage](/rest/reference/actions#get-workflow-run-usage)
{% endif %}
{% ifversion fpt %}
{% ifversion fpt or ghec %}
#### Workflows
* [List repository workflows](/rest/reference/actions#list-repository-workflows)
@@ -923,7 +924,7 @@ While most of your API interaction should occur using your server-to-server inst
* [Get workflow usage](/rest/reference/actions#get-workflow-usage)
{% endif %}
{% ifversion fpt or ghes > 3.1 or ghae-next %}
{% ifversion fpt or ghes > 3.1 or ghae-next or ghec %}
## Further reading

1
content/developers/apps/building-github-apps/index.md
View File

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

3
content/developers/apps/building-github-apps/managing-allowed-ip-addresses-for-a-github-app.md
View File

@@ -4,6 +4,7 @@ intro: 'You can add an IP allow list to your {% data variables.product.prodname_
versions:
fpt: '*'
ghae: '*'
ghec: '*'
topics:
- GitHub Apps
shortTitle: Manage allowed IP addresses
@@ -11,7 +12,7 @@ shortTitle: Manage allowed IP addresses
## About IP address allow lists for {% data variables.product.prodname_github_apps %}
Enterprise and organization owners can restrict access to assets by configuring an IP address allow list. This list specifies the IP addresses that are allowed to connect. For more information, see "[Managing allowed IP addresses for your organization](/organizations/keeping-your-organization-secure/managing-allowed-ip-addresses-for-your-organization#enabling-allowed-ip-addresses)" and {% ifversion ghae %}"[Restricting network traffic to your enterprise](/admin/configuration/configuring-your-enterprise/restricting-network-traffic-to-your-enterprise)." {% else %}"[Enforcing security settings in your enterprise account](/github/setting-up-and-managing-your-enterprise/setting-policies-for-organizations-in-your-enterprise-account/enforcing-security-settings-in-your-enterprise-account#managing-allowed-ip-addresses-for-organizations-in-your-enterprise-account)." {% endif %}
Enterprise and organization owners can restrict access to assets by configuring an IP address allow list. This list specifies the IP addresses that are allowed to connect. For more information, see "[Enforcing policies for security settings in your enterprise](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-security-settings-in-your-enterprise#managing-allowed-ip-addresses-for-organizations-in-your-enterprise)."
When an organization has an allow list, third-party applications that connect via a {% data variables.product.prodname_github_app %} will be denied access unless both of the following are true:

11
content/developers/apps/building-github-apps/rate-limits-for-github-apps.md
View File

@@ -11,13 +11,14 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- GitHub Apps
shortTitle: Rate limits
---
## Server-to-server requests
{% ifversion fpt %}
{% ifversion fpt or ghec %}
Different server-to-server request rate limits apply to {% data variables.product.prodname_github_apps %} if the app is installed on organizations or repositories owned by a {% data variables.product.prodname_ghe_cloud %} account.
@@ -27,7 +28,7 @@ Different server-to-server request rate limits apply to {% data variables.produc
{% data reusables.apps.api-rate-limits-non-ghec %}
{% ifversion fpt %}
{% ifversion fpt or ghec %}
### {% data variables.product.prodname_ghe_cloud %} server-to-server rate limits
@@ -39,7 +40,7 @@ Different server-to-server request rate limits apply to {% data variables.produc
{% data variables.product.prodname_github_apps %} can also act [on behalf of a user](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/#identifying-and-authorizing-users-for-github-apps), making user-to-server requests.
{% ifversion fpt %}
{% ifversion fpt or ghec %}
Different user-to-server request rate limits apply to {% data variables.product.prodname_github_apps %} if the app is installed on organizations or repositories owned by a {% data variables.product.prodname_ghe_cloud %} account and the authenticated user also belongs to the same {% data variables.product.prodname_ghe_cloud %} account.
@@ -49,7 +50,7 @@ Different user-to-server request rate limits apply to {% data variables.product.
User-to-server requests are rate limited at 5,000 requests per hour and per authenticated user. All OAuth applications authorized by that user, personal access tokens owned by that user, and requests authenticated with that user's{% ifversion ghae %} token{% else %} username and password{% endif %} share the same quota of 5,000 requests per hour for that user.
{% ifversion fpt %}
{% ifversion fpt or ghec %}
### {% data variables.product.prodname_ghe_cloud %} user-to-server rate limits
@@ -57,4 +58,4 @@ When a user belongs to a {% data variables.product.prodname_ghe_cloud %} account
{% endif %}
For more detailed information about rate limits, see "[Rate limiting](/rest/overview/resources-in-the-rest-api#rate-limiting)" for REST API and "[Resource limitations](/graphql/overview/resource-limitations)" for GraphQL API.
For more detailed information about rate limits, see "[Rate limiting](/rest/overview/resources-in-the-rest-api#rate-limiting)" for REST API and "[Resource limitations]({% ifversion ghec %}/free-pro-team@latest{% endif %}/graphql/overview/resource-limitations)" for GraphQL API.

7
content/developers/apps/building-github-apps/refreshing-user-to-server-access-tokens.md
View File

@@ -8,6 +8,7 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- GitHub Apps
shortTitle: Refresh user-to-server access
@@ -42,9 +43,9 @@ Name | Type | Description
```json
{
"access_token": "{% ifversion fpt or ghes > 3.1 or ghae-next %}ghu_16C7e42F292c6912E7710c838347Ae178B4a{% else %}e72e16c7e42f292c6912e7710c838347ae178b4a{% endif %}",
"access_token": "{% ifversion fpt or ghes > 3.1 or ghae-next or ghec %}ghu_16C7e42F292c6912E7710c838347Ae178B4a{% else %}e72e16c7e42f292c6912e7710c838347ae178b4a{% endif %}",
"expires_in": "28800",
"refresh_token": "{% ifversion fpt or ghes > 3.1 or ghae-next %}ghr_1B4a2e77838347a7E420ce178F2E7c6912E169246c34E1ccbF66C46812d16D5B1A9Dc86A1498{% else %}r1.c1b4a2e77838347a7e420ce178f2e7c6912e169246c34e1ccbf66c46812d16d5b1a9dc86a149873c{% endif %}",
"refresh_token": "{% ifversion fpt or ghes > 3.1 or ghae-next or ghec %}ghr_1B4a2e77838347a7E420ce178F2E7c6912E169246c34E1ccbF66C46812d16D5B1A9Dc86A1498{% else %}r1.c1b4a2e77838347a7e420ce178f2e7c6912e169246c34e1ccbf66c46812d16d5b1a9dc86a149873c{% endif %}",
"refresh_token_expires_in": "15811200",
"scope": "",
"token_type": "bearer"
@@ -75,7 +76,7 @@ Existing {% data variables.product.prodname_github_apps %} using user-to-server
Enabling expiring user tokens for existing {% data variables.product.prodname_github_apps %} requires sending users through the OAuth flow to re-issue new user tokens that will expire in 8 hours and making a request with the refresh token to get a new access token and refresh token. For more information, see "[Identifying and authorizing users for GitHub Apps](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/)."
{% ifversion fpt or ghes > 3.1 or ghae-next %}
{% ifversion fpt or ghes > 3.1 or ghae-next or ghec %}
## Further reading

1
content/developers/apps/building-github-apps/setting-permissions-for-github-apps.md
View File

@@ -10,6 +10,7 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- GitHub Apps
shortTitle: Set permissions

23
content/developers/apps/building-oauth-apps/authorizing-oauth-apps.md
View File

@@ -13,6 +13,7 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- OAuth Apps
---
@@ -22,7 +23,7 @@ If you want to skip authorizing your app in the standard way, such as when testi
To authorize your OAuth app, consider which authorization flow best fits your app.
- [web application flow](#web-application-flow): Used to authorize users for standard OAuth apps that run in the browser. (The [implicit grant type](https://tools.ietf.org/html/rfc6749#section-4.2) is not supported.){% ifversion fpt or ghae or ghes > 3.0 %}
- [web application flow](#web-application-flow): Used to authorize users for standard OAuth apps that run in the browser. (The [implicit grant type](https://tools.ietf.org/html/rfc6749#section-4.2) is not supported.){% ifversion fpt or ghae or ghes > 3.0 or ghec %}
- [device flow](#device-flow): Used for headless apps, such as CLI tools.{% endif %}
## Web application flow
@@ -49,7 +50,7 @@ When your GitHub App specifies a `login` parameter, it prompts users with a spec
Name | Type | Description
-----|------|--------------
`client_id`|`string` | **Required**. The client ID you received from GitHub when you {% ifversion fpt %}[registered](https://github.com/settings/applications/new){% else %}registered{% endif %}.
`client_id`|`string` | **Required**. The client ID you received from GitHub when you {% ifversion fpt or ghec %}[registered](https://github.com/settings/applications/new){% else %}registered{% endif %}.
`redirect_uri`|`string` | The URL in your application where users will be sent after authorization. See details below about [redirect urls](#redirect-urls).
`login` | `string` | Suggests a specific account to use for signing in and authorizing the app.
`scope`|`string` | A space-delimited list of [scopes](/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/). If not provided, `scope` defaults to an empty list for users that have not authorized any scopes for the application. For users who have authorized scopes for the application, the user won't be shown the OAuth authorization page with the list of scopes. Instead, this step of the flow will automatically complete with the set of scopes the user has authorized for the application. For example, if a user has already performed the web flow twice and has authorized one token with `user` scope and another token with `repo` scope, a third web flow that does not provide a `scope` will receive a token with `user` and `repo` scope.
@@ -78,7 +79,7 @@ Name | Type | Description
By default, the response takes the following form:
```
access_token={% ifversion fpt or ghes > 3.1 or ghae-next %}gho_16C7e42F292c6912E7710c838347Ae178B4a{% else %}e72e16c7e42f292c6912e7710c838347ae178b4a{% endif %}&scope=repo%2Cgist&token_type=bearer
access_token={% ifversion fpt or ghes > 3.1 or ghae-next or ghec %}gho_16C7e42F292c6912E7710c838347Ae178B4a{% else %}e72e16c7e42f292c6912e7710c838347ae178b4a{% endif %}&scope=repo%2Cgist&token_type=bearer
```
{% data reusables.apps.oauth-auth-vary-response %}
@@ -86,7 +87,7 @@ access_token={% ifversion fpt or ghes > 3.1 or ghae-next %}gho_16C7e42F292c6912E
```json
Accept: application/json
{
"access_token":"{% ifversion fpt or ghes > 3.1 or ghae-next %}gho_16C7e42F292c6912E7710c838347Ae178B4a{% else %}e72e16c7e42f292c6912e7710c838347ae178b4a{% endif %}",
"access_token":"{% ifversion fpt or ghes > 3.1 or ghae-next or ghec %}gho_16C7e42F292c6912E7710c838347Ae178B4a{% else %}e72e16c7e42f292c6912e7710c838347ae178b4a{% endif %}",
"scope":"repo,gist",
"token_type":"bearer"
}
@@ -97,7 +98,7 @@ Accept: application/xml
<OAuth>
<token_type>bearer</token_type>
<scope>repo,gist</scope>
<access_token>{% ifversion fpt or ghes > 3.1 or ghae-next %}gho_16C7e42F292c6912E7710c838347Ae178B4a{% else %}e72e16c7e42f292c6912e7710c838347ae178b4a{% endif %}</access_token>
<access_token>{% ifversion fpt or ghes > 3.1 or ghae-next or ghec %}gho_16C7e42F292c6912E7710c838347Ae178B4a{% else %}e72e16c7e42f292c6912e7710c838347ae178b4a{% endif %}</access_token>
</OAuth>
```
@@ -114,7 +115,7 @@ For example, in curl you can set the Authorization header like this:
curl -H "Authorization: token OAUTH-TOKEN" {% data variables.product.api_url_pre %}/user
```
{% ifversion fpt or ghae or ghes > 3.0 %}
{% ifversion fpt or ghae or ghes > 3.0 or ghec %}
## Device flow
@@ -216,7 +217,7 @@ Name | Type | Description
By default, the response takes the following form:
```
access_token={% ifversion fpt or ghes > 3.1 or ghae-next %}gho_16C7e42F292c6912E7710c838347Ae178B4a{% else %}e72e16c7e42f292c6912e7710c838347ae178b4a{% endif %}&token_type=bearer&scope=repo%2Cgist
access_token={% ifversion fpt or ghes > 3.1 or ghae-next or ghec %}gho_16C7e42F292c6912E7710c838347Ae178B4a{% else %}e72e16c7e42f292c6912e7710c838347ae178b4a{% endif %}&token_type=bearer&scope=repo%2Cgist
```
{% data reusables.apps.oauth-auth-vary-response %}
@@ -224,7 +225,7 @@ access_token={% ifversion fpt or ghes > 3.1 or ghae-next %}gho_16C7e42F292c6912E
```json
Accept: application/json
{
"access_token": "{% ifversion fpt or ghes > 3.1 or ghae-next %}gho_16C7e42F292c6912E7710c838347Ae178B4a{% else %}e72e16c7e42f292c6912e7710c838347ae178b4a{% endif %}",
"access_token": "{% ifversion fpt or ghes > 3.1 or ghae-next or ghec %}gho_16C7e42F292c6912E7710c838347Ae178B4a{% else %}e72e16c7e42f292c6912e7710c838347ae178b4a{% endif %}",
"token_type": "bearer",
"scope": "repo,gist"
}
@@ -233,7 +234,7 @@ Accept: application/json
```xml
Accept: application/xml
<OAuth>
<access_token>{% ifversion fpt or ghes > 3.1 or ghae-next %}gho_16C7e42F292c6912E7710c838347Ae178B4a{% else %}e72e16c7e42f292c6912e7710c838347ae178b4a{% endif %}</access_token>
<access_token>{% ifversion fpt or ghes > 3.1 or ghae-next or ghec %}gho_16C7e42F292c6912E7710c838347Ae178B4a{% else %}e72e16c7e42f292c6912e7710c838347ae178b4a{% endif %}</access_token>
<token_type>bearer</token_type>
<scope>gist,repo</scope>
</OAuth>
@@ -265,7 +266,7 @@ For more information, see the "[OAuth 2.0 Device Authorization Grant](https://to
Non-web authentication is available for limited situations like testing. If you need to, you can use [Basic Authentication](/rest/overview/other-authentication-methods#basic-authentication) to create a personal access token using your [Personal access tokens settings page](/articles/creating-an-access-token-for-command-line-use). This technique enables the user to revoke access at any time.
{% ifversion fpt or ghes %}
{% ifversion fpt or ghes or ghec %}
{% note %}
**Note:** When using the non-web application flow to create an OAuth2 token, make sure to understand how to [work with
@@ -333,7 +334,7 @@ To build this link, you'll need your OAuth Apps `client_id` that you received fr
* "[Troubleshooting authorization request errors](/apps/managing-oauth-apps/troubleshooting-authorization-request-errors)"
* "[Troubleshooting OAuth App access token request errors](/apps/managing-oauth-apps/troubleshooting-oauth-app-access-token-request-errors)"
{% ifversion fpt or ghae or ghes > 3.0 %}* "[Device flow errors](#error-codes-for-the-device-flow)"{% endif %}{% ifversion fpt or ghae-issue-4374 or ghes > 3.2 %}
{% ifversion fpt or ghae or ghes > 3.0 or ghec %}* "[Device flow errors](#error-codes-for-the-device-flow)"{% endif %}{% ifversion fpt or ghae-issue-4374 or ghes > 3.2 or ghec %}
* "[Token expiration and revocation](/github/authenticating-to-github/keeping-your-account-and-data-secure/token-expiration-and-revocation)"{% endif %}
## Further reading

9
content/developers/apps/building-oauth-apps/creating-a-custom-badge-for-your-oauth-app.md
View File

@@ -8,6 +8,7 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- OAuth Apps
shortTitle: Create custom badges
@@ -19,9 +20,9 @@ An identicon badge looks something like this:
After you create an OAuth App, you can customize the app's badge by uploading a logo and selecting a background color. A badge is a square logo image inside of a circular badge. You can choose a background color for the badge, which can be used to visually distinguish your app.
Your logo should be a PNG, JPG, or GIF file under 1 MB in size. For the best quality rendering, we recommend an image size of at least 200px x 200px. {% ifversion fpt %}See "[Tips for logo and badge images](/marketplace/listing-on-github-marketplace/writing-github-marketplace-listing-descriptions/#guidelines-for-logos)" for more guidance on customizing badges.{% endif %}
Your logo should be a PNG, JPG, or GIF file under 1 MB in size. For the best quality rendering, we recommend an image size of at least 200px x 200px. {% ifversion fpt or ghec %}See "[Tips for logo and badge images](/marketplace/listing-on-github-marketplace/writing-github-marketplace-listing-descriptions/#guidelines-for-logos)" for more guidance on customizing badges.{% endif %}
{% ifversion fpt %}
{% ifversion fpt or ghec %}
You can change a custom badge for a GitHub App that already has an approved Marketplace listing by navigating to https://github.com/marketplace/manage.
@@ -37,11 +38,11 @@ To create a custom badge:
![Upload a logo](/assets/images/oauth-apps/oauth_apps_upload_logo.png)
6. Crop your picture. When you're done, click **Set new application logo**.
![Crop and set logo](/assets/images/oauth-apps/oauth_apps_crop_and_set_logo.png)
7. In "Badge background color", type the [hexadecimal color code](http://www.color-hex.com/) of the background color for your badge. {% ifversion fpt %}**Note:** The "Badge background color" input field will be visible after an application logo has been uploaded.{% endif %}
7. In "Badge background color", type the [hexadecimal color code](http://www.color-hex.com/) of the background color for your badge. {% ifversion fpt or ghec %}**Note:** The "Badge background color" input field will be visible after an application logo has been uploaded.{% endif %}
![Badge background color](/assets/images/oauth-apps/oauth_apps_badge_background_color.png)
{% data reusables.user-settings.update_oauth_app %}
{% ifversion fpt %}
{% ifversion fpt or ghec %}
## Next steps

5
content/developers/apps/building-oauth-apps/creating-an-oauth-app.md
View File

@@ -9,10 +9,11 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- OAuth Apps
---
{% ifversion fpt %}
{% ifversion fpt or ghec %}
{% note %}
**Note:** {% data reusables.apps.maximum-oauth-apps-allowed %}
@@ -46,7 +47,7 @@ topics:
![Field for a description of your app](/assets/images/oauth-apps/oauth_apps_application_description.png)
9. In "Authorization callback URL", type the callback URL of your app.
![Field for the authorization callback URL of your app](/assets/images/oauth-apps/oauth_apps_authorization_callback_url.png)
{% ifversion fpt or ghes > 3.0 %}
{% ifversion fpt or ghes > 3.0 or ghec %}
{% note %}
**Note:** OAuth Apps cannot have multiple callback URLs, unlike {% data variables.product.prodname_github_apps %}.

1
content/developers/apps/building-oauth-apps/index.md
View File

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

9
content/developers/apps/building-oauth-apps/scopes-for-oauth-apps.md
View File

@@ -10,6 +10,7 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- OAuth Apps
---
@@ -45,7 +46,7 @@ Name | Description
&emsp;`repo:status`| Grants read/write access to {% ifversion not ghae %}public{% else %}internal{% endif %} and private repository commit statuses. This scope is only necessary to grant other users or services access to private repository commit statuses *without* granting access to the code.
&emsp;`repo_deployment`| Grants access to [deployment statuses](/rest/reference/repos#deployments) for {% ifversion not ghae %}public{% else %}internal{% endif %} and private repositories. This scope is only necessary to grant other users or services access to deployment statuses, *without* granting access to the code.{% ifversion not ghae %}
&emsp;`public_repo`| Limits access to public repositories. That includes read/write access to code, commit statuses, repository projects, collaborators, and deployment statuses for public repositories and organizations. Also required for starring public repositories.{% endif %}
&emsp;`repo:invite` | Grants accept/decline abilities for invitations to collaborate on a repository. This scope is only necessary to grant other users or services access to invites *without* granting access to the code.{% ifversion fpt or ghes > 3.0 %}
&emsp;`repo:invite` | Grants accept/decline abilities for invitations to collaborate on a repository. This scope is only necessary to grant other users or services access to invites *without* granting access to the code.{% ifversion fpt or ghes > 3.0 or ghec %}
&emsp;`security_events` | Grants: <br/> read and write access to security events in the [{% data variables.product.prodname_code_scanning %} API](/rest/reference/code-scanning) <br/> read and write access to security events in the [{% data variables.product.prodname_secret_scanning %} API](/rest/reference/secret-scanning) <br/> This scope is only necessary to grant other users or services access to security events *without* granting access to the code.{% endif %}{% ifversion ghes < 3.1 %}
&emsp;`security_events` | Grants read and write access to security events in the [{% data variables.product.prodname_code_scanning %} API](/rest/reference/code-scanning). This scope is only necessary to grant other users or services access to security events *without* granting access to the code.{% endif %}
**`admin:repo_hook`** | Grants read, write, ping, and delete access to repository hooks in {% ifversion not ghae %}public{% else %}internal{% endif %} and private repositories. The `repo` {% ifversion not ghae %}and `public_repo` scopes grant{% else %}scope grants{% endif %} full access to repositories, including repository hooks. Use the `admin:repo_hook` scope to limit access to only repository hooks.
@@ -66,13 +67,13 @@ Name | Description
&emsp;`user:follow`| Grants access to follow or unfollow other users.
**`delete_repo`** | Grants access to delete adminable repositories.
**`write:discussion`** | Allows read and write access for team discussions.
&emsp;`read:discussion` | Allows read access for team discussions.{% ifversion fpt or ghae %}
&emsp;`read:discussion` | Allows read access for team discussions.{% ifversion fpt or ghae or ghec %}
**`write:packages`** | Grants access to upload or publish a package in {% data variables.product.prodname_registry %}. For more information, see "[Publishing a package](/github/managing-packages-with-github-packages/publishing-a-package)".
**`read:packages`** | Grants access to download or install packages from {% data variables.product.prodname_registry %}. For more information, see "[Installing a package](/github/managing-packages-with-github-packages/installing-a-package)".
**`delete:packages`** | Grants access to delete packages from {% data variables.product.prodname_registry %}. For more information, see "{% ifversion fpt or ghes > 3.0 %}[Deleting and restoring a package](/packages/learn-github-packages/deleting-and-restoring-a-package){% elsif ghes < 3.1 or ghae %}[Deleting a package](/packages/learn-github-packages/deleting-a-package){% endif %}."{% endif %}
**`delete:packages`** | Grants access to delete packages from {% data variables.product.prodname_registry %}. For more information, see "{% ifversion fpt or ghes > 3.0 or ghec %}[Deleting and restoring a package](/packages/learn-github-packages/deleting-and-restoring-a-package){% elsif ghes < 3.1 or ghae %}[Deleting a package](/packages/learn-github-packages/deleting-a-package){% endif %}."{% endif %}
**`admin:gpg_key`** | Fully manage GPG keys.
&emsp;`write:gpg_key`| Create, list, and view details for GPG keys.
&emsp;`read:gpg_key`| List and view details for GPG keys.{% ifversion fpt %}
&emsp;`read:gpg_key`| List and view details for GPG keys.{% ifversion fpt or ghec %}
**`workflow`** | Grants the ability to add and update {% data variables.product.prodname_actions %} workflow files. Workflow files can be committed without this scope if the same file (with both the same path and contents) exists on another branch in the same repository. Workflow files can expose `GITHUB_TOKEN` which may have a different set of scopes. For more information, see "[Authentication in a workflow](/actions/reference/authentication-in-a-workflow#permissions-for-the-github_token)."{% endif %}
{% note %}

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.

13
content/developers/apps/guides/creating-ci-tests-with-the-checks-api.md
View File

@@ -8,6 +8,7 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- GitHub Apps
shortTitle: CI tests using Checks API
@@ -51,7 +52,7 @@ To get an idea of what your Checks API CI server will do when you've completed t
## Prerequisites
Before you get started, you may want to familiarize yourself with [GitHub Apps](/apps/), [Webhooks](/webhooks), and the [Checks API](/rest/reference/checks), if you're not already. You'll find more APIs in the [REST API docs](/rest). The Checks API is also available to use in [GraphQL](/graphql), but this quickstart focuses on REST. See the GraphQL [Checks Suite](/graphql/reference/objects#checksuite) and [Check Run](/graphql/reference/objects#checkrun) objects for more details.
Before you get started, you may want to familiarize yourself with [GitHub Apps](/apps/), [Webhooks](/webhooks), and the [Checks API](/rest/reference/checks), if you're not already. You'll find more APIs in the [REST API docs](/rest). The Checks API is also available to use in [GraphQL]({% ifversion ghec %}/free-pro-team@latest{% endif %}/graphql), but this quickstart focuses on REST. See the GraphQL [Checks Suite]({% ifversion ghec %}/free-pro-team@latest{% endif %}/graphql/reference/objects#checksuite) and [Check Run]({% ifversion ghec %}/free-pro-team@latest{% endif %}/graphql/reference/objects#checkrun) objects for more details.
You'll use the [Ruby programming language](https://www.ruby-lang.org/en/), the [Smee](https://smee.io/) webhook payload delivery service, the [Octokit.rb Ruby library](http://octokit.github.io/octokit.rb/) for the GitHub REST API, and the [Sinatra web framework](http://sinatrarb.com/) to create your Checks API CI server app.
@@ -136,7 +137,7 @@ The `requested` action requests a check run each time code is pushed to the repo
You'll add this new method as a [Sinatra helper](https://github.com/sinatra/sinatra#helpers) in case you want other routes to use it too. Under `helpers do`, add this `create_check_run` method:
{% ifversion fpt or ghes > 2.22 or ghae %}
{% ifversion fpt or ghes > 2.22 or ghae or ghec %}
``` ruby
# Create a new check run with the status queued
def create_check_run
@@ -227,7 +228,7 @@ In this section, you're not going to kick off the CI test yet, but you'll walk t
Let's create the `initiate_check_run` method and update the status of the check run. Add the following code to the helpers section:
{% ifversion fpt or ghes > 2.22 or ghae %}
{% ifversion fpt or ghes > 2.22 or ghae or ghec %}
``` ruby
# Start the CI process
def initiate_check_run
@@ -586,7 +587,7 @@ text = "Octo RuboCop version: #{@output['metadata']['rubocop_version']}"
Now you've got all the information you need to update your check run. In the [first half of this quickstart](#step-14-updating-a-check-run), you added this code to set the status of the check run to `success`:
{% ifversion fpt or ghes > 2.22 or ghae %}
{% ifversion fpt or ghes > 2.22 or ghae or ghec %}
``` ruby
# Mark the check run as complete!
@installation_client.update_check_run(
@@ -612,7 +613,7 @@ Now you've got all the information you need to update your check run. In the [fi
You'll need to update that code to use the `conclusion` variable you set based on the RuboCop results (to `success` or `neutral`). You can update the code with the following:
{% ifversion fpt or ghes > 2.22 or ghae %}
{% ifversion fpt or ghes > 2.22 or ghae or ghec %}
``` ruby
# Mark the check run as complete! And if there are warnings, share them.
@installation_client.update_check_run(
@@ -660,7 +661,7 @@ You'll need to update that code to use the `conclusion` variable you set based o
Now that you're setting a conclusion based on the status of the CI test and you've added the output from the RuboCop results, you've created a CI test! Congratulations. 🙌
The code above also adds a feature to your CI server called [requested actions](https://developer.github.com/changes/2018-05-23-request-actions-on-checks/) via the `actions` object. {% ifversion fpt %}(Note this is not related to [GitHub Actions](/actions).) {% endif %}Requested actions add a button in the **Checks** tab on GitHub that allows someone to request the check run to take additional action. The additional action is completely configurable by your app. For example, because RuboCop has a feature to automatically fix the errors it finds in Ruby code, your CI server can use a requested actions button to allow people to request automatic error fixes. When someone clicks the button, the app receives the `check_run` event with a `requested_action` action. Each requested action has an `identifier` that the app uses to determine which button was clicked.
The code above also adds a feature to your CI server called [requested actions](https://developer.github.com/changes/2018-05-23-request-actions-on-checks/) via the `actions` object. {% ifversion fpt or ghec %}(Note this is not related to [GitHub Actions](/actions).) {% endif %}Requested actions add a button in the **Checks** tab on GitHub that allows someone to request the check run to take additional action. The additional action is completely configurable by your app. For example, because RuboCop has a feature to automatically fix the errors it finds in Ruby code, your CI server can use a requested actions button to allow people to request automatic error fixes. When someone clicks the button, the app receives the `check_run` event with a `requested_action` action. Each requested action has an `identifier` that the app uses to determine which button was clicked.
The code above doesn't have RuboCop automatically fix errors yet. You'll add that in the next section. But first, take a look at the CI test that you just created by starting up the `template_server.rb` server again and creating a new pull request:

3
content/developers/apps/guides/index.md
View File

@@ -1,12 +1,13 @@
---
title: Guides
intro: 'Learn about using the {% data variables.product.prodname_dotcom %} API with your app, continuous integration, and how to build with apps.'
intro: 'Learn about using the {% ifversion fpt or ghec %}{% data variables.product.prodname_dotcom %}{% else %}{% data variables.product.product_name %}{% endif %} API with your app, continuous integration, and how to build with apps.'
redirect_from:
- /apps/quickstart-guides
versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- GitHub Apps
children:

3
content/developers/apps/guides/using-content-attachments.md
View File

@@ -8,6 +8,7 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- GitHub Apps
---
@@ -120,7 +121,7 @@ curl -X "POST" "{% data variables.product.api_url_code %}/graphql" \
}'
```
For more information on `node_id`, see "[Using Global Node IDs](/graphql/guides/using-global-node-ids)."
For more information on `node_id`, see "[Using Global Node IDs]({% ifversion ghec %}/free-pro-team@latest{% endif %}/graphql/guides/using-global-node-ids)."
## Example using Probot and GitHub App Manifests

5
content/developers/apps/guides/using-the-github-api-in-your-app.md
View File

@@ -9,6 +9,7 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- GitHub Apps
shortTitle: Build an app with the REST API
@@ -24,7 +25,7 @@ This project will walk you through the following:
{% data reusables.apps.app-ruby-guides %}
Once you've worked through the steps, you'll be ready to develop other kinds of integrations using the full suite of GitHub APIs. {% 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 %}
Once you've worked through the steps, you'll be ready to develop other kinds of integrations using the full suite of GitHub APIs. {% 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 %}
## Prerequisites
@@ -233,5 +234,5 @@ Here are some ideas for what you can do next:
* When the bot successfully adds the label, show a message in the Terminal. (Hint: compare the `needs-response` label ID with the ID of the label in the payload as a condition for your message, so that the message only displays when the relevant label is added and not some other label.)
* Add a landing page to your app and hook up a [Sinatra route](https://github.com/sinatra/sinatra#routes) for it.
* Move your code to a hosted server (like Heroku). Don't forget to update your app settings with the new domain.
* Share your project or get advice in the {% data variables.product.prodname_support_forum_with_url %}{% ifversion fpt %}
* Share your project or get advice in the {% data variables.product.prodname_support_forum_with_url %}{% ifversion fpt or ghec %}
* Have you built a shiny new app you think others might find useful? [Add it to GitHub Marketplace](/apps/marketplace/creating-and-submitting-your-app-for-approval/)!{% endif %}

1
content/developers/apps/index.md
View File

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

1
content/developers/apps/managing-github-apps/deleting-a-github-app.md
View File

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

1
content/developers/apps/managing-github-apps/editing-a-github-apps-permissions.md
View File

@@ -9,6 +9,7 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- GitHub Apps
shortTitle: Edit permissions

1
content/developers/apps/managing-github-apps/index.md
View File

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

5
content/developers/apps/managing-github-apps/installing-github-apps.md
View File

@@ -1,6 +1,6 @@
---
title: Installing GitHub Apps
intro: 'When your app is public, anyone can use {% ifversion fpt %} the {% data variables.product.prodname_marketplace %} or {% endif %}an installation URL to install the app on their repository. When your app is private, only you can install the app on repositories that you own.'
intro: 'When your app is public, anyone can use {% ifversion fpt or ghec %} the {% data variables.product.prodname_marketplace %} or {% endif %}an installation URL to install the app on their repository. When your app is private, only you can install the app on repositories that you own.'
redirect_from:
- /apps/installing-github-apps
- /developers/apps/installing-github-apps
@@ -8,6 +8,7 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- GitHub Apps
---
@@ -28,7 +29,7 @@ Once you create a private GitHub App, you can install it on one of your org or u
![App installation permissions](/assets/images/install_permissions.png)
5. Once installed, you will see configuration options for the app on your selected account. You can make changes here, or repeat the previous steps to install the app on another account.
{% ifversion fpt %}
{% ifversion fpt or ghec %}
## Offering your app in the GitHub Marketplace
You can offer a paid or free version of your app in [{% data variables.product.prodname_marketplace %}](https://github.com/marketplace), where people can search for and view details about your app. {% data variables.product.prodname_marketplace %} automatically installs a GitHub App when an order is complete.

7
content/developers/apps/managing-github-apps/making-a-github-app-public-or-private.md
View File

@@ -12,6 +12,7 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- GitHub Apps
shortTitle: Manage app visibility
@@ -24,7 +25,7 @@ Public installation flows have a landing page to enable other people besides the
## Private installation flow
Private installation flows allow only the owner of a GitHub App to install it. Limited information about the GitHub App will still exist on a public page, but the **Install** button will only be available to organization administrators or the user account if the GitHub App is owned by an individual account. {% ifversion fpt or ghes > 3.1 or ghae-next %}Private {% else %}Private (also known as internal){% endif %} GitHub Apps can only be installed on the user or organization account of the owner.
Private installation flows allow only the owner of a GitHub App to install it. Limited information about the GitHub App will still exist on a public page, but the **Install** button will only be available to organization administrators or the user account if the GitHub App is owned by an individual account. {% ifversion fpt or ghes > 3.1 or ghae-next or ghec %}Private {% else %}Private (also known as internal){% endif %} GitHub Apps can only be installed on the user or organization account of the owner.
## Changing who can install your GitHub App
@@ -36,7 +37,7 @@ To change who can install the GitHub App:
3. Select the GitHub App whose installation option you want to change.
![App selection](/assets/images/github-apps/github_apps_select-app.png)
{% data reusables.user-settings.github_apps_advanced %}
5. Depending on the installation option of your GitHub App, click either **Make public** or **Make {% ifversion fpt or ghes > 3.1 or ghae-next %}private{% else %}internal{% endif %}**.
5. Depending on the installation option of your GitHub App, click either **Make public** or **Make {% ifversion fpt or ghes > 3.1 or ghae-next or ghec %}private{% else %}internal{% endif %}**.
![Button to change the installation option of your GitHub App](/assets/images/github-apps/github_apps_make_public.png)
6. Depending on the installation option of your GitHub App, click either **Yes, make this GitHub App public** or **Yes, make this GitHub App {% ifversion fpt or ghes < 3.2 %}internal{% else %}private{% endif %}**.
6. Depending on the installation option of your GitHub App, click either **Yes, make this GitHub App public** or **Yes, make this GitHub App {% ifversion fpt or ghes < 3.2 or ghec %}internal{% else %}private{% endif %}**.
![Button to confirm the change of your installation option](/assets/images/github-apps/github_apps_confirm_installation_option.png)

1
content/developers/apps/managing-github-apps/modifying-a-github-app.md
View File

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

1
content/developers/apps/managing-github-apps/suspending-a-github-app-installation.md
View File

@@ -8,6 +8,7 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- GitHub Apps
shortTitle: Suspend app installation

1
content/developers/apps/managing-github-apps/transferring-ownership-of-a-github-app.md
View File

@@ -9,6 +9,7 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- GitHub Apps
shortTitle: Transfer ownership

1
content/developers/apps/managing-oauth-apps/deleting-an-oauth-app.md
View File

@@ -9,6 +9,7 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- OAuth Apps
---

1
content/developers/apps/managing-oauth-apps/index.md
View File

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

1
content/developers/apps/managing-oauth-apps/modifying-an-oauth-app.md
View File

@@ -9,6 +9,7 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- OAuth Apps
---

1
content/developers/apps/managing-oauth-apps/transferring-ownership-of-an-oauth-app.md
View File

@@ -9,6 +9,7 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- OAuth Apps
shortTitle: Transfer ownership

1
content/developers/apps/managing-oauth-apps/troubleshooting-authorization-request-errors.md
View File

@@ -9,6 +9,7 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- GitHub Apps
shortTitle: Troubleshoot authorization

1
content/developers/apps/managing-oauth-apps/troubleshooting-oauth-app-access-token-request-errors.md
View File

@@ -9,6 +9,7 @@ versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- OAuth Apps
shortTitle: Troubleshoot token request