зеркало из https://github.com/github/docs.git
Update GitHub App terminology (#37381)
Co-authored-by: Jess Hosman <1183847+jhosman@users.noreply.github.com> Co-authored-by: Hirsch Singhal <1666363+hpsin@users.noreply.github.com>
This commit is contained in:
Sarah Edwards
GitHub
Родитель
6a7d23e030
Коммит
892a21a899
|
|
@ -33,7 +33,7 @@ There are two ways to generate a user access token for a {% data variables.produ
|
|||
|
||||
## Prerequisites
|
||||
|
||||
This tutorial assumes that you have already created a {% data variables.product.prodname_github_app %}. For more information about creating an app, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)."
|
||||
This tutorial assumes that you have already registered a {% data variables.product.prodname_github_app %}. For more information about registering a {% data variables.product.prodname_github_app %}, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)."
|
||||
|
||||
Before following this tutorial, you must enable device flow for your app. For more information about enabling device flow for your app, see "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app)."
|
||||
|
||||
|
|
|
|||
|
|
@ -20,9 +20,9 @@ This tutorial uses JavaScript, but you can use any programming language that you
|
|||
|
||||
### About webhooks
|
||||
|
||||
When you create a {% data variables.product.prodname_github_app %}, you can specify a webhook URL and subscribe to webhook events. When activity on {% data variables.product.company_short %} triggers an event that your app is subscribed to, {% data variables.product.company_short %} will send a webhook event to your app's webhook URL.
|
||||
When you register a {% data variables.product.prodname_github_app %}, you can specify a webhook URL and subscribe to webhook events. When activity on {% data variables.product.company_short %} triggers an event that your app is subscribed to, {% data variables.product.company_short %} will send a webhook event to your app's webhook URL.
|
||||
|
||||
For example, you can subscribe your app to the pull request webhook event. When a pull request is opened in a repository that the app was granted access to, {% data variables.product.company_short %} will send a pull request webhook event to your app's webhook URL. If multiple actions can trigger the event, the event payload will include an `action` field to indicate what type of action triggered the event. In this example, the value of `action` would be `opened` since the event was triggered because a pull request was opened.
|
||||
For example, you can subscribe your {% data variables.product.prodname_github_app %} to the pull request webhook event. When a pull request is opened in a repository that the app was granted access to, {% data variables.product.company_short %} will send a pull request webhook event to your app's webhook URL. If multiple actions can trigger the event, the event payload will include an `action` field to indicate what type of action triggered the event. In this example, the value of `action` would be `opened` since the event was triggered because a pull request was opened.
|
||||
|
||||
If your app is running on a server that is listening for these webhook events, then your app can take an action when it receives a webhook event. For example, your app can use the {% data variables.product.company_short %} API to post a comment to the pull request when it receives a pull request webhook event.
|
||||
|
||||
|
|
@ -40,7 +40,7 @@ The following sections will lead you through setting up the following components
|
|||
|
||||
- a repository to store the code for your app
|
||||
- a way to receive webhooks locally
|
||||
- a {% data variables.product.prodname_github_app %} that is subscribed to "pull request" webhook events, has permission to add comments to pull requests, and uses a webhook URL that you can receive locally
|
||||
- a {% data variables.product.prodname_github_app %} registration that is subscribed to "pull request" webhook events, has permission to add comments to pull requests, and uses a webhook URL that you can receive locally
|
||||
|
||||
### Create a repository to store code for your app
|
||||
|
||||
|
|
@ -59,16 +59,16 @@ In order to develop your app locally, you can use a webhook proxy URL to forward
|
|||
1. Click **Start a new channel**.
|
||||
1. Copy the full URL under "Webhook Proxy URL". You will use this URL in a later step.
|
||||
|
||||
### Create a {% data variables.product.prodname_github_app %}
|
||||
### Register a {% data variables.product.prodname_github_app %}
|
||||
|
||||
For this tutorial, you must have a {% data variables.product.prodname_github_app %} that:
|
||||
For this tutorial, you must have a {% data variables.product.prodname_github_app %} registration that:
|
||||
|
||||
- Has webhooks active
|
||||
- Uses a webhook URL that you can receive locally
|
||||
- Has the "Pull request" repository permission
|
||||
- Subscribes to the "Pull request" webhook event
|
||||
|
||||
The following steps will guide you through configuring a {% data variables.product.prodname_github_app %} with these settings. For more information about {% data variables.product.prodname_github_app %} settings, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)."
|
||||
The following steps will guide you through registering a {% data variables.product.prodname_github_app %} with these settings. For more information about {% data variables.product.prodname_github_app %} settings, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)."
|
||||
|
||||
{% data reusables.apps.settings-step %}
|
||||
{% data reusables.user-settings.developer_settings %}
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ There are two ways to generate a user access token for a {% data variables.produ
|
|||
|
||||
## Prerequisites
|
||||
|
||||
This tutorial assumes that you have already created a {% data variables.product.prodname_github_app %}. For more information about creating an app, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)."
|
||||
This tutorial assumes that you have already registered a {% data variables.product.prodname_github_app %}. For more information about registering a {% data variables.product.prodname_github_app %}, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)."
|
||||
|
||||
Before following this tutorial, you must set a callback URL for your app. This tutorial uses a local Sinatra server with the default URL of `http://localhost:4567`. For example, to work with the default URL for a local Sinatra application, your callback URL can be `http://localhost:4567/github/callback`. Once you are ready to deploy your app, you can change the callback URL to use your live server address. For more information about updating the callback URL for your app, see "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app)" and "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-the-user-authorization-callback-url)."
|
||||
|
||||
|
|
|
|||
|
|
@ -18,9 +18,9 @@ If you need to make authenticated API requests in a {% data variables.product.pr
|
|||
|
||||
## Authenticating with a {% data variables.product.prodname_github_app %}
|
||||
|
||||
In order to use a {% data variables.product.prodname_github_app %} to make authenticated API requests, you must create a {% data variables.product.prodname_github_app %}, store your app's credentials, and install your app. Once this is done, you can use your app to create an installation access token, which can be used to make authenticated API requests in a {% data variables.product.prodname_actions %} workflow. You can also pass the installation access token to a custom action that requires a token.
|
||||
In order to use a {% data variables.product.prodname_github_app %} to make authenticated API requests, you must register a {% data variables.product.prodname_github_app %}, store your app's credentials, and install your app. Once this is done, you can use your app to create an installation access token, which can be used to make authenticated API requests in a {% data variables.product.prodname_actions %} workflow. You can also pass the installation access token to a custom action that requires a token.
|
||||
|
||||
1. Create a {% data variables.product.prodname_github_app %}. Give your {% data variables.product.prodname_github_app %} the necessary permissions to access the desired resources. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)" and "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app)."
|
||||
1. Register a {% data variables.product.prodname_github_app %}. Give your {% data variables.product.prodname_github_app %} registration the necessary permissions to access the desired resources. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)" and "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app)."
|
||||
1. Store the app ID of your {% data variables.product.prodname_github_app %} as a {% data variables.product.prodname_actions %} secret. You can find the app ID on the settings page for your app. The app ID is different from the client ID. For more information about storing secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)."
|
||||
1. Generate a private key for your app. Store the contents of the resulting file as a secret. (Store the entire contents of the file, including `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----`.) For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)."
|
||||
1. Install the {% data variables.product.prodname_github_app %} on your user account or organization and grant it access to any repositories that you want your workflow to access. For more information, see "[AUTOTITLE](/apps/maintaining-github-apps/installing-github-apps#installing-your-private-github-app-on-your-repository)."
|
||||
|
|
|
|||
|
|
@ -40,7 +40,7 @@ In order to develop your app locally, you can use a webhook proxy URL to forward
|
|||
1. Click **Start a new channel**.
|
||||
1. Copy the full URL under "Webhook Proxy URL". You will use this URL in a later step.
|
||||
|
||||
## Step 3: Create a {% data variables.product.prodname_github_app %}
|
||||
## Step 3: Register a {% data variables.product.prodname_github_app %}
|
||||
|
||||
The following steps will guide you through configuring the app settings that are required for this quickstart. For more information about the settings, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)."
|
||||
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ topics:
|
|||
shortTitle: Setup URL
|
||||
---
|
||||
|
||||
When you create a {% data variables.product.prodname_github_app %}, you can specify a setup URL. When users install your {% data variables.product.prodname_github_app %}, they are redirected to the setup URL. If additional setup is required after installation, you can use this URL to tell users what steps to take next.
|
||||
When you register a {% data variables.product.prodname_github_app %}, you can specify a setup URL. When users install your {% data variables.product.prodname_github_app %}, they are redirected to the setup URL. If additional setup is required after installation, you can use this URL to tell users what steps to take next.
|
||||
|
||||
If you specify a setup URL, you can also select **Redirect on update** to specify that users should be redirected to the setup URL after they update an installation. An update includes adding or removing access to a repository for an installation.
|
||||
|
||||
|
|
@ -22,9 +22,9 @@ If you specify a setup URL, you can also select **Redirect on update** to specif
|
|||
{% endwarning %}
|
||||
|
||||
{% ifversion fpt or ghec %}
|
||||
Although the setup URL is optional in the {% data variables.product.prodname_github_app %} settings, it is required if you want to allow users to purchase your app in {% data variables.product.prodname_marketplace %}. For more information, see "[AUTOTITLE](/apps/publishing-apps-to-github-marketplace/using-the-github-marketplace-api-in-your-app/handling-new-purchases-and-free-trials)."
|
||||
Although the setup URL is optional during {% data variables.product.prodname_github_app %} registration, it is required if you want to allow users to purchase your app in {% data variables.product.prodname_marketplace %}. For more information, see "[AUTOTITLE](/apps/publishing-apps-to-github-marketplace/using-the-github-marketplace-api-in-your-app/handling-new-purchases-and-free-trials)."
|
||||
{% endif %}
|
||||
|
||||
The setup URL is different from the callback URL. Users are redirected to the setup URL after they install a {% data variables.product.prodname_github_app %}. Users are redirected to the callback URL when they authorize a {% data variables.product.company_short %} via the web application flow. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-the-user-authorization-callback-url)."
|
||||
|
||||
For more information about creating or modifying a {% data variables.product.prodname_github_app %}, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)" and "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app)."
|
||||
For more information about registering a {% data variables.product.prodname_github_app %}, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)." For more information about modifying a {% data variables.product.prodname_github_app %} registration, see "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app)."
|
||||
|
|
|
|||
|
|
@ -13,10 +13,11 @@ redirect_from:
|
|||
- /apps/creating-github-apps/creating-github-apps/about-the-user-authorization-callback-url
|
||||
---
|
||||
|
||||
When you create a {% data variables.product.prodname_github_app %}, you can specify a callback URL. When you use the web application flow to generate a user access token in order to act on behalf of a user, users will be redirected to the callback URL after they authorize the app.
|
||||
When you register a {% data variables.product.prodname_github_app %}, you can specify a callback URL. When you use the web application flow to generate a user access token in order to act on behalf of a user, users will be redirected to the callback URL after they authorize the {% data variables.product.prodname_github_app %}.
|
||||
|
||||
You can specify up to 10 callback URLs. If you specify multiple callback URLs, you can use the `redirect_uri` parameter when you prompt the user to authorize your app, to indicate which callback URL the user should be redirected to. If you do not specify `redirect_uri`, the first callback URL will be used. For more information about using the `redirect_uri` parameter, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)".
|
||||
You can specify up to 10 callback URLs. If you specify multiple callback URLs, you can use the `redirect_uri` parameter when you prompt the user to authorize your {% data variables.product.prodname_github_app %}, to indicate which callback URL the user should be redirected to. If you do not specify `redirect_uri`, the first callback URL will be used. For more information about using the `redirect_uri` parameter, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)".
|
||||
|
||||
The callback URL is different from the setup URL. Users are redirected to the setup URL after they install an app. Users are redirected to the callback URL when they authorize an app via the web application flow. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-the-setup-url)."
|
||||
The callback URL is different from the setup URL. Users are redirected to the setup URL after they install a {% data variables.product.prodname_github_app %}. Users are redirected to the callback URL when they authorize a {% data variables.product.prodname_github_app %} via the web application flow. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-the-setup-url)."
|
||||
|
||||
For more information about generating user access tokens, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)". For more information about registering a {% data variables.product.prodname_github_app %}, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)." For more information about modifying a {% data variables.product.prodname_github_app %} registration, see "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app)."
|
||||
|
||||
For more information about generating user access tokens, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)". For more information about creating or modifying a {% data variables.product.prodname_github_app %}, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)" and "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app)."
|
||||
|
|
|
|||
|
|
@ -13,9 +13,9 @@ topics:
|
|||
|
||||
## Select the minimum permissions required
|
||||
|
||||
Select the minimum permissions that your {% data variables.product.prodname_github_app %} needs. If any keys or tokens for your app become compromised, this will limit the amount of damage that can occur. For more information about how to choose permissions, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app)."
|
||||
When you register a {% data variables.product.prodname_github_app %}, select the minimum permissions that your {% data variables.product.prodname_github_app %} needs. If any keys or tokens for your app become compromised, this will limit the amount of damage that can occur. For more information about how to choose permissions, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app)."
|
||||
|
||||
When your app creates an installation access token or user access token, you can further limit the repositories that the app can access and the permissions that the token has. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app)" and "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)."
|
||||
When your {% data variables.product.prodname_github_app %} creates an installation access token or user access token, you can further limit the repositories that the app can access and the permissions that the token has. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app)" and "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)."
|
||||
|
||||
## Stay under the rate limit
|
||||
|
||||
|
|
@ -29,7 +29,7 @@ If you do hit a rate limit and need to retry an API request, use the `x-ratelimi
|
|||
|
||||
## Secure your app's credentials
|
||||
|
||||
You can generate a private key and client secret for your app. With these credentials, your app can generate installation access tokens, user access tokens, and refresh tokens. These tokens can be used to make API requests on behalf of an app installation or user.
|
||||
You can generate a private key and client secret for your {% data variables.product.prodname_github_app %}. With these credentials, your app can generate installation access tokens, user access tokens, and refresh tokens. These tokens can be used to make API requests on behalf of an app installation or user.
|
||||
|
||||
You must store these credentials securely. The storage mechanism depends on your integrations architecture and the platform that it runs on. In general, you should use a storage mechanism that is intended to store sensitive data on the platform that you are using.
|
||||
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@ topics:
|
|||
|
||||
## About {% data variables.product.prodname_github_app %} permissions
|
||||
|
||||
{% data variables.product.prodname_github_app %}s don't have any permissions by default. When you create an app, you can select permissions for the app. The permissions that you select determine what the app can do with {% data variables.product.company_short %}'s APIs and what webhooks the app can subscribe to. You should select the minimum permissions required for the app.
|
||||
{% data variables.product.prodname_github_app %}s don't have any permissions by default. When you register a {% data variables.product.prodname_github_app %}, you can select permissions for the app. The permissions that you select determine what the app can do with {% data variables.product.company_short %}'s APIs and what webhooks the app can subscribe to. You should select the minimum permissions required for the app.
|
||||
|
||||
Although {% data variables.product.prodname_github_app %}s don't have any permissions by default, they do have implicit permissions to read public resources when acting on behalf of a user. When a user authorizes the app to act on their behalf, the {% data variables.product.prodname_github_app %} can use the resulting user access token to make requests to the REST API{% ifversion graphQL-for-fgpats-and-apps %} and the GraphQL API{% endif %} to read public resources. To learn more about acting on behalf of a user, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user)."
|
||||
|
||||
|
|
@ -35,7 +35,7 @@ You can modify the permissions for your app at any time. When you modify the per
|
|||
|
||||
Some webhooks and API access requires "Administration" permissions. If your app requires "Administration" permissions, consider explaining this requirement on your app's homepage. This will help users understand why your app needs a high level permission.
|
||||
|
||||
For more information about specifying permissions during app creation, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)." For more information about modifying permissions, see "[AUTOTITLE](/apps/maintaining-github-apps/editing-a-github-apps-permissions)."
|
||||
For more information about specifying permissions during {% data variables.product.prodname_github_app %} registration, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)." For more information about modifying permissions, see "[AUTOTITLE](/apps/maintaining-github-apps/editing-a-github-apps-permissions)."
|
||||
|
||||
## Choosing permissions for webhook access
|
||||
|
||||
|
|
@ -43,7 +43,7 @@ The webhook documentation indicates whether each webhook is available to {% data
|
|||
|
||||
For example, if you want your app to subscribe to `team` events, your app must have the "Members" organization permission.
|
||||
|
||||
On your app settings page, the available webhook events will change as you change your app's permissions. If you did not select sufficient permissions for your app to subscribe to an event, the event will not appear as an option on your app settings page.
|
||||
On your {% data variables.product.prodname_github_app %} registration page, the available webhook events will change as you change your app's permissions. If you did not select sufficient permissions for your {% data variables.product.prodname_github_app %} to subscribe to an event, the event will not appear as an option on your app registration page.
|
||||
|
||||
## Choosing permissions for REST API access
|
||||
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ 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.
|
||||
After you register 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 or ghec %}See "[AUTOTITLE](/apps/publishing-apps-to-github-marketplace/listing-an-app-on-github-marketplace/writing-a-listing-description-for-your-app#guidelines-for-logos)" for more guidance on customizing badges.{% endif %}
|
||||
|
||||
|
|
@ -51,6 +51,6 @@ To create a custom badge:
|
|||
|
||||
## Next steps
|
||||
|
||||
For more information about creating a Marketplace listing for this app, see "[AUTOTITLE](/apps/publishing-apps-to-github-marketplace/listing-an-app-on-github-marketplace)".
|
||||
For more information about listing your {% data variables.product.prodname_github_app %} in {% data variables.product.prodname_marketplace %}, see "[AUTOTITLE](/apps/publishing-apps-to-github-marketplace/listing-an-app-on-github-marketplace)".
|
||||
|
||||
{% endif %}
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ topics:
|
|||
- GitHub Apps
|
||||
children:
|
||||
- /about-creating-github-apps
|
||||
- /creating-a-github-app
|
||||
- /registering-a-github-app
|
||||
- /about-the-user-authorization-callback-url
|
||||
- /about-the-setup-url
|
||||
- /choosing-permissions-for-a-github-app
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: Making a GitHub App public or private
|
||||
intro: 'When setting up a {% data variables.product.prodname_github_app %}, you can make it public so that other GitHub users or organizations can install the app, or private so that you can only install it on the account that owns the app.'
|
||||
intro: 'When registering a {% data variables.product.prodname_github_app %}, you can make it public so that other GitHub users or organizations can install the app, or private so that you can only install it on the account that owns the app.'
|
||||
redirect_from:
|
||||
- /apps/building-integrations/setting-up-and-registering-github-apps/about-installation-options-for-github-apps
|
||||
- /apps/building-github-apps/installation-options-for-github-apps
|
||||
|
|
@ -22,19 +22,19 @@ shortTitle: Visibility
|
|||
|
||||
## About visibility for {% data variables.product.prodname_github_app %}s
|
||||
|
||||
You can make your {% data variables.product.prodname_github_app %} public or private. {% ifversion fpt %}If you set your {% data variables.product.prodname_github_app %} to public, any user on {% data variables.product.prodname_dotcom_the_website %} or {% data variables.product.prodname_ghe_cloud %} can install it. If you set your {% data variables.product.prodname_github_app %} to private, it can only be installed on the account that owns the app.
|
||||
You can make your {% data variables.product.prodname_github_app %} registration public or private. {% ifversion fpt %}If you set your {% data variables.product.prodname_github_app %} registration to public, any user on {% data variables.product.prodname_dotcom_the_website %} or {% data variables.product.prodname_ghe_cloud %} can install it. If you set your {% data variables.product.prodname_github_app %} registration to private, it can only be installed on the account that owns the app.
|
||||
|
||||
{% elsif ghes %}If you set your {% data variables.product.prodname_github_app %} to public, anyone on your {% data variables.product.prodname_ghe_server %} instance can install it, but the app is not available outside of your instance. If you set your {% data variables.product.prodname_github_app %} to private, it can only be installed on the account that owns the app.
|
||||
{% elsif ghes %}If you set your {% data variables.product.prodname_github_app %} registration to public, anyone on your {% data variables.product.prodname_ghe_server %} instance can install it, but the app is not available outside of your instance. If you set your {% data variables.product.prodname_github_app %} registration to private, it can only be installed on the account that owns the app.
|
||||
|
||||
{% elsif ghec %}If you set your {% data variables.product.prodname_github_app %} to public, and the {% data variables.product.prodname_github_app %} is owned by an {% data variables.product.prodname_emu %} account, accounts owned by your enterprise can install it, but the app cannot be installed on accounts outside of your enterprise. If a {% data variables.product.prodname_github_app %} is owned by an account that is not an {% data variables.product.prodname_emu %}, and the app is set to public, any user on {% data variables.product.prodname_dotcom_the_website %} or {% data variables.product.prodname_ghe_cloud %} can install the app. If you set your {% data variables.product.prodname_github_app %} to private, it can only be installed on the account that owns the app.{% endif %}
|
||||
{% elsif ghec %}If you set your {% data variables.product.prodname_github_app %} registration to public, and the {% data variables.product.prodname_github_app %} registration is owned by an {% data variables.product.prodname_emu %} account, accounts owned by your enterprise can install it, but the app cannot be installed on accounts outside of your enterprise. If a {% data variables.product.prodname_github_app %} registration is owned by an account that is not an {% data variables.product.prodname_emu %}, and the app is set to public, any user on {% data variables.product.prodname_dotcom_the_website %} or {% data variables.product.prodname_ghe_cloud %} can install the app. If you set your {% data variables.product.prodname_github_app %} registration to private, it can only be installed on the account that owns the app.{% endif %}
|
||||
|
||||
{% ifversion fpt or ghec %}You can create a {% data variables.product.prodname_github_app %} from your individual user account and make it available for organization accounts to install. You do not need an enterprise plan or an organization account to create a {% data variables.product.prodname_github_app %} for organizations even if the organization is owned by an enterprise on {% data variables.product.prodname_ghe_cloud %}.{% endif %}
|
||||
{% ifversion fpt or ghec %}You can register a {% data variables.product.prodname_github_app %} under your personal account or organization and make it available for other organizations to install. You do not need an enterprise plan or an organization account to make your {% data variables.product.prodname_github_app %} available to an organization even if the organization is owned by an enterprise on {% data variables.product.prodname_ghe_cloud %}.{% endif %}
|
||||
|
||||
If you want to make your app available to {% ifversion ghes %}other {% endif %}{% data variables.product.prodname_ghe_server %} instances, then you need to use an app manifest. The {% data variables.product.prodname_ghe_server %} instance will create the app from the manifest and provide you with the required information. For more information, see "[AUTOTITLE](/developers/apps/building-github-apps/creating-a-github-app-from-a-manifest)."
|
||||
If you want to make your app available to {% ifversion ghes %}other {% endif %}{% data variables.product.prodname_ghe_server %} instances, then you need to take additional steps. For more information, see "[AUTOTITLE](/apps/sharing-github-apps/making-your-github-app-available-for-github-enterprise-server)."
|
||||
|
||||
If it is important for {% ifversion ghes %}other {% endif %}{% data variables.product.prodname_ghe_server %} users to be able to use your tool, consider using {% data variables.product.prodname_actions %} instead of a {% data variables.product.prodname_github_app %}. Public actions are available on {% data variables.product.prodname_ghe_server %} instances with GitHub Connect. For more information, see "[AUTOTITLE](/github-ae@latest/admin/github-actions/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect)" and "[AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/about-github-actions-for-enterprises)."
|
||||
|
||||
For information about changing the visibility of a {% data variables.product.prodname_github_app %}, see "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app)."
|
||||
For information about changing the visibility of a {% data variables.product.prodname_github_app %} registration, see "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app)."
|
||||
|
||||
### Public installation flow
|
||||
|
||||
|
|
|
|||
|
|
@ -57,7 +57,7 @@ Once you have registered a {% data variables.product.prodname_github_app %}, ada
|
|||
|
||||
You will need to update your app's code to handle API authentication for your {% data variables.product.prodname_github_app %}. A {% data variables.product.prodname_github_app %} can authenticate in three ways:
|
||||
|
||||
- As the app itself, in order to get or modify details about the app or to create an installation access token. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app)."
|
||||
- As the app itself, in order to get or modify details about the {% data variables.product.prodname_github_app %} registration or to create an installation access token. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app)."
|
||||
- As an app installation, in order to take actions on behalf of itself. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation)."
|
||||
- On behalf of a user, in order to attribute actions to a user. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user)."
|
||||
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
title: Creating a GitHub App
|
||||
shortTitle: Create a {% data variables.product.prodname_github_app %}
|
||||
intro: 'You can create a {% data variables.product.prodname_github_app %} under your personal account or under any organization you own.'
|
||||
title: Registering a GitHub App
|
||||
shortTitle: 'Register a {% data variables.product.prodname_github_app %}'
|
||||
intro: 'You can register a {% data variables.product.prodname_github_app %} under your personal account or under any organization you own.'
|
||||
redirect_from:
|
||||
- /early-access/integrations/creating-an-integration
|
||||
- /apps/building-integrations/setting-up-and-registering-github-apps/registering-github-apps
|
||||
|
|
@ -9,6 +9,7 @@ redirect_from:
|
|||
- /developers/apps/creating-a-github-app
|
||||
- /developers/apps/building-github-apps/creating-a-github-app
|
||||
- /apps/creating-github-apps/creating-github-apps/creating-a-github-app
|
||||
- /apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghes: '*'
|
||||
|
|
@ -18,13 +19,13 @@ topics:
|
|||
- GitHub Apps
|
||||
---
|
||||
|
||||
## About creating {% data variables.product.prodname_github_apps %}
|
||||
## About registering {% data variables.product.prodname_github_apps %}
|
||||
|
||||
You can create a {% data variables.product.prodname_github_app %} owned by your personal account, by an organization that you own, or by an organization that has granted you permission to manage all apps owned by the organization. For more information, see "[AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/adding-github-app-managers-in-your-organization)."
|
||||
You can register a {% data variables.product.prodname_github_app %} under your personal account, under an organization that you own, or under an organization that has granted you permission to manage all apps owned by the organization. For more information, see "[AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/adding-github-app-managers-in-your-organization)."
|
||||
|
||||
{% data reusables.apps.maximum-github-apps-allowed %}
|
||||
|
||||
## Creating a {% data variables.product.prodname_github_app %}
|
||||
## Registering a {% data variables.product.prodname_github_app %}
|
||||
|
||||
{% data reusables.apps.settings-step %}
|
||||
{% data reusables.user-settings.developer_settings %}
|
||||
|
|
@ -61,10 +62,10 @@ You can create a {% data variables.product.prodname_github_app %} owned by your
|
|||
|
||||
## Next steps
|
||||
|
||||
After creating a {% data variables.product.prodname_github_app %}, you will want to write code to make your {% data variables.product.prodname_github_app %} do something. For examples of how to write code, see:
|
||||
After registering a {% data variables.product.prodname_github_app %}, you will want to write code to make your {% data variables.product.prodname_github_app %} do something. For examples of how to write code, see:
|
||||
|
||||
- "[AUTOTITLE](/apps/creating-github-apps/guides/building-a-github-app-that-responds-to-webhook-events)"
|
||||
- "[AUTOTITLE](/apps/creating-github-apps/guides/building-a-login-with-github-button-with-a-github-app)"
|
||||
- "[AUTOTITLE](/apps/creating-github-apps/guides/building-a-login-with-github-button-with-a-github-app)"
|
||||
- "[AUTOTITLE](/apps/creating-github-apps/guides/building-a-cli-with-a-github-app)"
|
||||
|
||||
You should aim to follow best practices. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app)."
|
||||
|
|
@ -19,15 +19,15 @@ Webhooks enable your {% data variables.product.prodname_github_app %} to receive
|
|||
|
||||
You can configure your {% data variables.product.prodname_github_app %} to receive webhooks for specific events on {% data variables.product.prodname_dotcom %} and automatically take action on them. For more information about the types of webhooks you can receive, see "[AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads)."
|
||||
|
||||
To receive webhook events in your {% data variables.product.prodname_github_app %}, you must activate webhooks in the app settings and specify a webhook URL where {% data variables.product.prodname_dotcom %} will send the webhook payloads. For more information about creating and configuring a {% data variables.product.prodname_github_app %}, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)."
|
||||
To receive webhook events in your {% data variables.product.prodname_github_app %}, you must enable webhooks for your {% data variables.product.prodname_github_app %} registration and specify a webhook URL where {% data variables.product.prodname_dotcom %} will send the webhook payloads.
|
||||
|
||||
If your app does not need to respond to webhooks or will only be used for authentication, you can turn off the webhook function in your app settings. You do not need to specify a webhook URL. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)."
|
||||
If your {% data variables.product.prodname_github_app %} does not need to respond to webhooks or will only be used for authentication, you can turn off the webhook function for your {% data variables.product.prodname_github_app %} registration. You do not need to specify a webhook URL.
|
||||
|
||||
For information about changing the webhooks that a {% data variables.product.prodname_github_app %} subscribes to, see "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app)."
|
||||
For more information about registering a {% data variables.product.prodname_github_app %}, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)." For more information about changing the webhooks that a {% data variables.product.prodname_github_app %} registration subscribes to, see "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app)."
|
||||
|
||||
## Choosing a webhook URL
|
||||
|
||||
When you activate webhooks in the settings for your {% data variables.product.prodname_github_app %}, you will need to specify a webhook URL. The webhook URL is the address of a web server that will receive the webhook event payloads sent to your {% data variables.product.prodname_github_app %}. The server can then take action based on the content of the payload. You should choose a web server that's appropriate for the volume of webhook traffic that your {% data variables.product.prodname_github_app %} will encounter.
|
||||
When you activate webhooks for your {% data variables.product.prodname_github_app %} registration, you will need to specify a webhook URL. The webhook URL is the address of a web server that will receive the webhook event payloads sent to your {% data variables.product.prodname_github_app %}. The server can then take action based on the content of the payload. You should choose a web server that's appropriate for the volume of webhook traffic that your {% data variables.product.prodname_github_app %} will encounter.
|
||||
|
||||
### Choosing a webhook URL for development and testing
|
||||
|
||||
|
|
@ -39,7 +39,7 @@ You can use Smee to create a unique domain where {% data variables.product.prodn
|
|||
|
||||
1. To use Smee to create a unique domain, go to https://smee.io and click **Start a new channel**.
|
||||
1. On the Smee channel page, follow the instructions under "Use the CLI" to install and run the Smee client.
|
||||
1. To connect your Smee webhook URL to your {% data variables.product.prodname_github_app %}, enter your unique Smee domain in the "Webhook URL" field of your app settings. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)."
|
||||
1. To connect your Smee webhook URL to your {% data variables.product.prodname_github_app %}, enter your unique Smee domain in the "Webhook URL" field on your {% data variables.product.prodname_github_app %} registration page. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)" and "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app)."
|
||||
|
||||
### Choosing a webhook URL for production
|
||||
|
||||
|
|
@ -51,7 +51,7 @@ To handle a higher volume of webhook traffic for a large app in production, cons
|
|||
|
||||
Once you've configured your server to receive payloads, it will listen for any payload sent to the server. For security reasons, you should limit incoming requests to only those originating from {% data variables.product.prodname_dotcom %}. You can do that by creating a webhook secret for your app.
|
||||
|
||||
To create a webhook secret for your GitHub App, type a secret token in your app settings under "Webhook secret." You should choose a random string of text with high entropy. For more information about how to create a webhook secret in your app settings, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)."
|
||||
To create a webhook secret for your GitHub App, type a secret token under "Webhook secret" on your {% data variables.product.prodname_github_app %} registration page. You should choose a random string of text with high entropy. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)" and "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app)."
|
||||
|
||||
After creating a webhook secret for your app, you will need to configure your server to securely store and validate the webhook secret token. For more information, see "[AUTOTITLE](/webhooks-and-events/webhooks/securing-your-webhooks)."
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: About GitHub App managers
|
||||
intro: 'Organization owners can grant or revoke access for a user to manage some or all of the {% data variables.product.prodname_github_apps %} owned by the organization.'
|
||||
intro: 'Organization owners can grant or revoke access for a user to manage some or all of the {% data variables.product.prodname_github_app %} registrations owned by the organization.'
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghes: '*'
|
||||
|
|
|
|||
|
|
@ -24,9 +24,9 @@ topics:
|
|||
|
||||
## About deleting {% data variables.product.prodname_github_app %}s
|
||||
|
||||
If you own a {% data variables.product.prodname_github_app %} or are an app manager for a {% data variables.product.prodname_github_app %}, you can delete the {% data variables.product.prodname_github_app %}. For more information about {% data variables.product.prodname_github_app %} managers, see "[AUTOTITLE](/apps/maintaining-github-apps/about-github-app-managers)."
|
||||
If you own a {% data variables.product.prodname_github_app %} or are an app manager for a {% data variables.product.prodname_github_app %}, you can delete the {% data variables.product.prodname_github_app %} registration. For more information about {% data variables.product.prodname_github_app %} managers, see "[AUTOTITLE](/apps/maintaining-github-apps/about-github-app-managers)."
|
||||
|
||||
When you delete a {% data variables.product.prodname_github_app %}, the app will be uninstalled from all accounts that the app is installed on.
|
||||
When you delete a {% data variables.product.prodname_github_app %} registration, the app will be uninstalled from all accounts that the app is installed on.
|
||||
|
||||
{% note %}
|
||||
|
||||
|
|
@ -44,3 +44,5 @@ When you delete a {% data variables.product.prodname_github_app %}, the app will
|
|||
6. Click **Delete GitHub App**.
|
||||
7. In the confirmation box, type the name of the GitHub App to confirm you want to delete it.
|
||||
8. Click **I understand the consequences, delete this GitHub App**.
|
||||
|
||||
These steps only delete your {% data variables.product.prodname_github_app %} registration, and all of the organization and account installations it may have. They do not delete any code that you wrote for your app. However, any code that relies on your {% data variables.product.prodname_github_app %}'s credentials will no longer function.
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ versions:
|
|||
topics:
|
||||
- GitHub Apps
|
||||
children:
|
||||
- /modifying-a-github-app
|
||||
- /modifying-a-github-app-registration
|
||||
- /activating-optional-features-for-github-apps
|
||||
- /about-github-app-managers
|
||||
- /managing-allowed-ip-addresses-for-a-github-app
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: Managing allowed IP addresses for a GitHub App
|
||||
intro: 'You can add an IP allow list to your {% data variables.product.prodname_github_app %} to prevent your app from being blocked by an organization''s own allow list.'
|
||||
intro: 'You can add an IP allow list to your {% data variables.product.prodname_github_app %} registration to prevent your app from being blocked by an organization''s own allow list.'
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghae: '*'
|
||||
|
|
@ -23,7 +23,7 @@ When an organization has an allow list, third-party applications that connect vi
|
|||
|
||||
{% data reusables.apps.ip-allow-list-only-apps %}
|
||||
|
||||
## Adding an IP address allow list to a {% data variables.product.prodname_github_app %}
|
||||
## Adding an IP address allow list to a {% data variables.product.prodname_github_app %} registration
|
||||
|
||||
{% data reusables.identity-and-permissions.ipv6-allow-lists %}
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: Modifying a GitHub App
|
||||
title: Modifying a GitHub App registration
|
||||
shortTitle: Modify app settings
|
||||
intro: '{% data reusables.shortdesc.modifying_github_apps %}'
|
||||
redirect_from:
|
||||
|
|
@ -12,6 +12,7 @@ redirect_from:
|
|||
- /developers/apps/editing-a-github-apps-permissions
|
||||
- /developers/apps/managing-github-apps/editing-a-github-apps-permissions
|
||||
- /apps/maintaining-github-apps/editing-a-github-apps-permissions
|
||||
- /apps/maintaining-github-apps/modifying-a-github-app
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghes: '*'
|
||||
|
|
@ -23,7 +24,7 @@ topics:
|
|||
|
||||
## About {% data variables.product.prodname_github_app %} modifications
|
||||
|
||||
You can modify your {% data variables.product.prodname_github_app %} to change any of the settings that were selected when the app was created. For more information about the settings you can select while creating a {% data variables.product.prodname_github_app %}, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)."
|
||||
You can modify your {% data variables.product.prodname_github_app %} registration to change any of the settings that were selected when the app was initially registered. For more information about the settings you can select while registering a {% data variables.product.prodname_github_app %}, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)."
|
||||
|
||||
For example, you can change the name and description of your app, the permissions granted to your app, the webhooks your app subscribes to, or the visibility of your app.
|
||||
|
||||
|
|
@ -18,11 +18,11 @@ shortTitle: Transfer ownership
|
|||
|
||||
## About transferring {% data variables.product.prodname_github_app %}s
|
||||
|
||||
The owner of a {% data variables.product.prodname_github_app %} can transfer ownership of the {% data variables.product.prodname_github_app %} to another user or organization. If an organization has designated any app managers for an app owned by the organization, the app managers can also transfer ownership of the {% data variables.product.prodname_github_app %}. For more information about app managers, see "[AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/adding-and-removing-github-app-managers-in-your-organization)."
|
||||
The owner of a {% data variables.product.prodname_github_app %} registration can transfer ownership of the {% data variables.product.prodname_github_app %} registration to another user or organization. If an organization has designated any app managers for an app owned by the organization, the app managers can also transfer ownership of the {% data variables.product.prodname_github_app %} registration. For more information about app managers, see "[AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/adding-and-removing-github-app-managers-in-your-organization)."
|
||||
|
||||
You can only transfer ownership to a user or organization. You cannot transfer ownership to a team.
|
||||
|
||||
## Transferring a {% data variables.product.prodname_github_app %}
|
||||
## Transferring a {% data variables.product.prodname_github_app %} registration
|
||||
|
||||
{% data reusables.apps.settings-step %}
|
||||
{% data reusables.user-settings.developer_settings %}
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ topics:
|
|||
children:
|
||||
- /sharing-your-github-app
|
||||
- /making-your-github-app-available-for-github-enterprise-server
|
||||
- /creating-a-github-app-from-a-manifest
|
||||
- /creating-a-github-app-using-url-parameters
|
||||
- /registering-a-github-app-from-a-manifest
|
||||
- /registering-a-github-app-using-url-parameters
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -23,20 +23,20 @@ These steps are not required if your {% data variables.product.prodname_github_a
|
|||
|
||||
If {% data variables.product.prodname_ghe_server %} access is important, consider whether a custom action for {% data variables.product.prodname_actions %} will suit your needs instead. Public actions are available on {% data variables.product.prodname_ghe_server %} instances with {% data variables.product.prodname_github_connect %}. For more information, see {% ifversion ghes %}"[AUTOTITLE](/admin/github-actions/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect)."{% else %}"[AUTOTITLE](/enterprise-server@latest/admin/github-actions/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect)" in the {% data variables.product.prodname_ghe_server %} documentation.{% endif %}
|
||||
|
||||
## Each {% data variables.product.prodname_ghe_server %} instance must create their own {% data variables.product.prodname_github_app %}
|
||||
## Each {% data variables.product.prodname_ghe_server %} instance must register their own {% data variables.product.prodname_github_app %}
|
||||
|
||||
Organizations owned by a {% data variables.product.prodname_ghe_server %} instance cannot install {% data variables.product.prodname_github_app %}s registered on {% data variables.product.prodname_dotcom_the_website %} or on another {% data variables.product.prodname_ghe_server %} instance. Instead, they must create and install their own {% data variables.product.prodname_github_app %} for use on that instance.
|
||||
Organizations owned by a {% data variables.product.prodname_ghe_server %} instance cannot install {% data variables.product.prodname_github_app %}s registered on {% data variables.product.prodname_dotcom_the_website %} or on another {% data variables.product.prodname_ghe_server %} instance. Instead, they must register and install their own {% data variables.product.prodname_github_app %} for use on that instance.
|
||||
|
||||
1. The app developer creates a manifest or URL parameters. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-from-a-manifest)" and "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-using-url-parameters)."
|
||||
1. The app developer shares the manifest or URL parameters with the {% data variables.product.prodname_ghe_server %} instance that wants to use the app. The same manifest or URL parameters can be shared with multiple {% data variables.product.prodname_ghe_server %} instances.
|
||||
1. An organization owned by the instance creates a {% data variables.product.prodname_github_app %} from the manifest or URL parameters.
|
||||
1. The organization installs the {% data variables.product.prodname_github_app %} that they created.
|
||||
1. An organization owned by the instance uses the manifest or URL parameters to register a {% data variables.product.prodname_github_app %}.
|
||||
1. The organization installs the {% data variables.product.prodname_github_app %} that they registered.
|
||||
|
||||
Optionally, if the organization made the {% data variables.product.prodname_github_app %} public, other organizations within the instance can install the {% data variables.product.prodname_github_app %} as well. There is not a way to install a {% data variables.product.prodname_github_app %} on an entire instance, only on organizations within an instance.
|
||||
|
||||
## The app code must be able to access the {% data variables.product.prodname_github_app %} credentials for the instance
|
||||
|
||||
You app's code will need the credentials of the {% data variables.product.prodname_github_app %} that the {% data variables.product.prodname_ghe_server %} instance created. It will also need the hostname of the instance. You have two options: get the credentials and hostname from the instance, or share the app code with the instance.
|
||||
You app's code will need the credentials of the {% data variables.product.prodname_github_app %} that the {% data variables.product.prodname_ghe_server %} instance registered. It will also need the hostname of the instance. You have two options: get the credentials and hostname from the instance, or share the app code with the instance.
|
||||
|
||||
### Get the credentials from the {% data variables.product.prodname_ghe_server %} instance
|
||||
|
||||
|
|
|
|||
|
|
@ -1,12 +1,13 @@
|
|||
---
|
||||
title: Creating a GitHub App from a manifest
|
||||
intro: 'A GitHub App Manifest is a preconfigured GitHub App you can share with anyone who wants to use your app in their personal repositories. The manifest flow allows someone to quickly create, install, and start extending a GitHub App without needing to register the app or connect the registration to the hosted app code.'
|
||||
title: Registering a GitHub App from a manifest
|
||||
intro: 'A {% data variables.product.prodname_github_app %} manifest is a way to share a preconfigured {% data variables.product.prodname_github_app %} registration with other users. The manifest flow allows someone to quickly register a {% data variables.product.prodname_github_app %}.'
|
||||
redirect_from:
|
||||
- /apps/building-github-apps/creating-github-apps-from-a-manifest
|
||||
- /developers/apps/creating-a-github-app-from-a-manifest
|
||||
- /developers/apps/building-github-apps/creating-a-github-app-from-a-manifest
|
||||
- /apps/creating-github-apps/creating-github-apps/creating-a-github-app-from-a-manifest
|
||||
- /apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-from-a-manifest
|
||||
- /apps/sharing-github-apps/creating-a-github-app-from-a-manifest
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghes: '*'
|
||||
|
|
@ -14,15 +15,15 @@ versions:
|
|||
ghec: '*'
|
||||
topics:
|
||||
- GitHub Apps
|
||||
shortTitle: App creation manifest flow
|
||||
shortTitle: App manifest
|
||||
---
|
||||
## About GitHub App Manifests
|
||||
|
||||
When someone creates a GitHub App from a manifest, they only need to follow a URL and name the app. The manifest includes the permissions, events, and webhook URL needed to automatically register the app. The manifest flow creates the GitHub App registration and retrieves the app's webhook secret, private key (PEM file), and GitHub App ID. The person who creates the app from the manifest will own the app and can choose to [edit the app's configuration settings](/apps/maintaining-github-apps/modifying-a-github-app), delete it, or transfer it to another person on GitHub.
|
||||
When someone registers a GitHub App from a manifest, they only need to follow a URL and name the app. The manifest includes the permissions, events, and webhook URL needed to automatically register the app. The manifest flow creates the GitHub App registration and generates the app's webhook secret, private key (PEM file), client secret, and GitHub App ID. The person who creates the {% data variables.product.prodname_github_app %} registration from the manifest will own the {% data variables.product.prodname_github_app %} registration and can choose to edit the registration's settings, delete it, or transfer it to another person on GitHub.
|
||||
|
||||
You can use [Probot](https://probot.github.io/) to get started with GitHub App Manifests or see an example implementation. See "[Using Probot to implement the GitHub App Manifest flow](#using-probot-to-implement-the-github-app-manifest-flow)" to learn more.
|
||||
|
||||
Here are some scenarios where you might use GitHub App Manifests to create preconfigured apps:
|
||||
Here are some scenarios where you might use GitHub App Manifests to register pre-configured apps:
|
||||
|
||||
* Help new team members come up-to-speed quickly when developing GitHub Apps.
|
||||
* Allow others to extend a GitHub App using the GitHub APIs without requiring them to configure an app.
|
||||
|
|
@ -42,17 +43,17 @@ The GitHub App Manifest flow uses a handshaking process similar to the [OAuth fl
|
|||
|
||||
Follow these steps to implement the GitHub App Manifest flow:
|
||||
|
||||
1. You redirect people to GitHub to create a new GitHub App.
|
||||
1. You redirect people to GitHub to register a new GitHub App.
|
||||
1. GitHub redirects people back to your site.
|
||||
1. You exchange the temporary code to retrieve the app configuration.
|
||||
|
||||
### 1. You redirect people to GitHub to create a new GitHub App
|
||||
### 1. You redirect people to GitHub to register a new GitHub App
|
||||
|
||||
To redirect people to create a new GitHub App, [provide a link](#examples) for them to click that sends a `POST` request to `https://github.com/settings/apps/new` for a personal account or `https://github.com/organizations/ORGANIZATION/settings/apps/new` for an organization account, replacing `ORGANIZATION` with the name of the organization account where the app will be created.
|
||||
To redirect people to register a new GitHub App, [provide a link](#examples) for them to click that sends a `POST` request to `https://github.com/settings/apps/new` for a personal account or `https://github.com/organizations/ORGANIZATION/settings/apps/new` for an organization account, replacing `ORGANIZATION` with the name of the organization account where the app will be registered.
|
||||
|
||||
You must include the [GitHub App Manifest parameters](#github-app-manifest-parameters) as a JSON-encoded string in a parameter called `manifest`. You can also include a `state` [parameter](#parameters) for additional security.
|
||||
|
||||
The person creating the app will be redirected to a GitHub page with an input field where they can edit the name of the app you included in the `manifest` parameter. If you do not include a `name` in the `manifest`, they can set their own name for the app in this field.
|
||||
The person registering the app will be redirected to a GitHub page with an input field where they can edit the name of the app you included in the `manifest` parameter. If you do not include a `name` in the `manifest`, they can set their own name for the app in this field.
|
||||
|
||||
#### GitHub App Manifest parameters
|
||||
|
||||
|
|
@ -61,7 +62,7 @@ The person creating the app will be redirected to a GitHub page with an input fi
|
|||
`name` | `string` | The name of the {% data variables.product.prodname_github_app %}.
|
||||
`url` | `string` | **Required.** The homepage of your {% data variables.product.prodname_github_app %}.
|
||||
`hook_attributes` | `object` | The configuration of the {% data variables.product.prodname_github_app %}'s webhook.
|
||||
`redirect_url` | `string` | The full URL to redirect to after a user initiates the creation of a {% data variables.product.prodname_github_app %} from a manifest.
|
||||
`redirect_url` | `string` | The full URL to redirect to after a user initiates the registration of a {% data variables.product.prodname_github_app %} from a manifest.
|
||||
`callback_urls` | `array of strings` | A full URL to redirect to after someone authorizes an installation. You can provide up to 10 callback URLs.
|
||||
`setup_url` | `string` | A full URL to redirect users to after they install your {% data variables.product.prodname_github_app %} if additional setup is required.
|
||||
`description` | `string` | A description of the {% data variables.product.prodname_github_app %}.
|
||||
|
|
@ -90,7 +91,7 @@ This example uses a form on a web page with a button that triggers the `POST` re
|
|||
|
||||
```html
|
||||
<form action="https://github.com/settings/apps/new?state=abc123" method="post">
|
||||
Create a GitHub App Manifest: <input type="text" name="manifest" id="manifest"><br>
|
||||
Register a GitHub App Manifest: <input type="text" name="manifest" id="manifest"><br>
|
||||
<input type="submit" value="Submit">
|
||||
</form>
|
||||
|
||||
|
|
@ -121,11 +122,11 @@ This example uses a form on a web page with a button that triggers the `POST` re
|
|||
</script>
|
||||
```
|
||||
|
||||
This example uses a form on a web page with a button that triggers the `POST` request for an organization account. Replace `ORGANIZATION` with the name of the organization account where you want to create the app.
|
||||
This example uses a form on a web page with a button that triggers the `POST` request for an organization account. Replace `ORGANIZATION` with the name of the organization account where you want to register the app.
|
||||
|
||||
```html
|
||||
<form action="https://github.com/organizations/ORGANIZATION/settings/apps/new?state=abc123" method="post">
|
||||
Create a GitHub App Manifest: <input type="text" name="manifest" id="manifest"><br>
|
||||
register a GitHub App Manifest: <input type="text" name="manifest" id="manifest"><br>
|
||||
<input type="submit" value="Submit">
|
||||
</form>
|
||||
|
||||
|
|
@ -182,7 +183,7 @@ You must complete this step of the GitHub App Manifest flow within one hour.
|
|||
|
||||
For more information about the endpoint's response, see [Create a GitHub App from a manifest](/rest/apps#create-a-github-app-from-a-manifest).
|
||||
|
||||
When the final step in the manifest flow is completed, the person creating the app from the flow will be an owner of a registered GitHub App that they can install on any of their personal repositories. They can choose to extend the app using the GitHub APIs, transfer ownership to someone else, or delete it at any time.
|
||||
When the final step in the manifest flow is completed, the person registering the app from the flow will be an owner of a registered GitHub App that they can install on any of their personal repositories. They can choose to extend the app using the GitHub APIs, transfer ownership to someone else, or delete it at any time.
|
||||
|
||||
## Using Probot to implement the GitHub App Manifest flow
|
||||
|
||||
|
|
@ -193,7 +194,7 @@ To create a Probot App that you can share, follow these steps:
|
|||
1. [Generate a new GitHub App](https://probot.github.io/docs/development/#generating-a-new-app).
|
||||
1. Open the project you created, and customize the settings in the `app.yml` file. Probot uses the settings in `app.yml` as the [GitHub App Manifest parameters](#github-app-manifest-parameters).
|
||||
1. Add your application's custom code.
|
||||
1. [Run the GitHub App locally](https://probot.github.io/docs/development/#running-the-app-locally) or [host it anywhere you'd like](#hosting-your-app-with-glitch). When you navigate to the hosted app's URL, you'll find a web page with a **Register GitHub App** button that people can click to create a preconfigured app.
|
||||
1. [Run the GitHub App locally](https://probot.github.io/docs/development/#running-the-app-locally) or [host it anywhere you'd like](#hosting-your-app-with-glitch). When you navigate to the hosted app's URL, you'll find a web page with a **Register GitHub App** button that people can click to register a preconfigured app.
|
||||
|
||||
Using [dotenv](https://github.com/bkeepers/dotenv), Probot creates a `.env` file and sets the `APP_ID`, `PRIVATE_KEY`, and `WEBHOOK_SECRET` environment variables with the values [retrieved from the app configuration](#3-you-exchange-the-temporary-code-to-retrieve-the-app-configuration).
|
||||
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
title: Creating a GitHub App using URL parameters
|
||||
title: Registering a GitHub App using URL parameters
|
||||
intro: 'You can use URL query parameters to help other people quickly set up a new {% data variables.product.prodname_github_app %} with a specific configuration you have preselected.'
|
||||
redirect_from:
|
||||
- /apps/building-github-apps/creating-github-apps-using-url-parameters
|
||||
|
|
@ -7,6 +7,7 @@ redirect_from:
|
|||
- /developers/apps/building-github-apps/creating-a-github-app-using-url-parameters
|
||||
- /apps/creating-github-apps/creating-github-apps/creating-a-github-app-using-url-parameters
|
||||
- /apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-using-url-parameters
|
||||
- /apps/sharing-github-apps/creating-a-github-app-using-url-parameters
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghes: '*'
|
||||
|
|
@ -14,11 +15,11 @@ versions:
|
|||
ghec: '*'
|
||||
topics:
|
||||
- GitHub Apps
|
||||
shortTitle: App creation query parameters
|
||||
shortTitle: App query parameters
|
||||
---
|
||||
## About URL parameters for creating {% data variables.product.prodname_github_app %}s
|
||||
## About URL parameters for registering {% data variables.product.prodname_github_app %}s
|
||||
|
||||
You can use URL parameters to preselect the configuration settings of a new {% data variables.product.prodname_github_app %} and share a custom link with other people. The link will take people to an app registration page, where the app settings will be pre-filled according to the URL parameters you included in the URL.
|
||||
You can use URL parameters to preselect the configuration settings of a new {% data variables.product.prodname_github_app %} registration and share a custom link with other people. The link will take people to a {% data variables.product.prodname_github_app %} registration page, where the app settings will be pre-filled according to the URL parameters you included in the URL.
|
||||
|
||||
This approach is useful for integrators who want customers to set up an app on their personal account or organization with certain specifications, or for customers using {% data variables.product.prodname_ghe_server %} who aren't able to install apps from the {% data variables.product.prodname_marketplace %}.
|
||||
|
||||
|
|
@ -28,12 +29,12 @@ Alternatively, you can create a {% data variables.product.prodname_github_app %}
|
|||
|
||||
To create a custom configuration URL for a {% data variables.product.prodname_github_app %} on a personal or organization account, add query parameters after the following base URLs.
|
||||
|
||||
* To create an app on a personal account, add URL parameters to: `{% data variables.product.oauth_host_code %}/settings/apps/new`
|
||||
* To create an app on an organization account, add URL parameters to: `{% data variables.product.oauth_host_code %}/organizations/ORGANIZATION/settings/apps/new`. Replace `ORGANIZATION` with the name of the organization where you'd like the customer to create the app.
|
||||
* To register an app on a personal account, add URL parameters to: `{% data variables.product.oauth_host_code %}/settings/apps/new`
|
||||
* To register an app on an organization account, add URL parameters to: `{% data variables.product.oauth_host_code %}/organizations/ORGANIZATION/settings/apps/new`. Replace `ORGANIZATION` with the name of the organization where you'd like the customer to register the app.
|
||||
|
||||
On the app registration page, the person creating the app can edit the preselected values before submitting the app. If you do not include parameters for required values (like `name`) in the URL query string, the person creating the app will need to input a value before they can submit the app.
|
||||
On the app registration page, the person registering the app can edit the preselected values before submitting the app. If you do not include parameters for required values (like `name`) in the URL query string, the person registering the app will need to input a value before they can register the app.
|
||||
|
||||
For example, the following URL creates a new public app named `octocat-github-app` on a personal account. Using query parameters, the URL preconfigures a description and a callback URL. It also selects read and write permissions for `checks`, activates webhooks using the `webhook_active` parameter, subscribes to the `check_run` and `check_suite` webhook events, and selects the option to request user authorization (OAuth) during installation:
|
||||
For example, the following URL registers a new public app named `octocat-github-app` on a personal account. Using query parameters, the URL preconfigures a description and a callback URL. It also selects read and write permissions for `checks`, activates webhooks using the `webhook_active` parameter, subscribes to the `check_run` and `check_suite` webhook events, and selects the option to request user authorization (OAuth) during installation:
|
||||
|
||||
```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&webhook_active=true&events[]=check_run&events[]=check_suite
|
||||
|
|
@ -41,7 +42,7 @@ For example, the following URL creates a new public app named `octocat-github-ap
|
|||
|
||||
## {% data variables.product.prodname_github_app %} configuration parameters
|
||||
|
||||
You can use the following query parameters to select a specific configuration for the {% data variables.product.prodname_github_app %}. For example, to name the app "octocat-github-app", your query string would include `name=octocat-github-app`.
|
||||
You can use the following query parameters to select a specific configuration for the {% data variables.product.prodname_github_app %} registration. For example, to name the app "octocat-github-app", your query string would include `name=octocat-github-app`.
|
||||
|
||||
Parameter name | Type | Description
|
||||
-----|------|-------------
|
||||
|
|
@ -62,7 +63,7 @@ Parameter name | Type | Description
|
|||
|
||||
## {% data variables.product.prodname_github_app %} permissions
|
||||
|
||||
You can use query parameters to select the permissions for the {% data variables.product.prodname_github_app %}. For more information about the possible permissions you can select for the app, and the endpoints that the app can access with each permission, see "[AUTOTITLE](/rest/overview/permissions-required-for-github-apps)." For the URL query parameter, use the permission name as the query parameter name, and set the query value to one of the possible values for that permission set.
|
||||
You can use query parameters to select the permissions for the {% data variables.product.prodname_github_app %} registration. For more information about the possible permissions you can select for the app, and the endpoints that the app can access with each permission, see "[AUTOTITLE](/rest/overview/permissions-required-for-github-apps)." For the URL query parameter, use the permission name as the query parameter name, and set the query value to one of the possible values for that permission set.
|
||||
|
||||
For example, to select "Read & write" permissions in the user interface for `contents`, your query string would include `contents=write`. To select "Read-only" permissions in the user interface for `blocking`, your query string would include `blocking=read`. To select "No access" in the user interface for `checks`, your query string would not include the `checks` permission.
|
||||
|
||||
|
|
@ -76,6 +77,6 @@ To enable the {% data variables.product.prodname_github_app %} webhook, use `web
|
|||
|
||||
For example, to subscribe a {% data variables.product.prodname_github_app %} to receive webhook payloads for activity relating to commit comments, the query string would include `&webhook_active=true&webhook_url=https://example.com&events[]=commit_comment`. Note that the `commit_comment` webhook event requires the {% data variables.product.prodname_github_app %} to have at least read-level access for the "Contents" repository permission. So your query string should also include a parameter to set the `contents` permission to `read` or `write`. For more information, see "[{% data variables.product.prodname_dotcom %} app permissions](#github-app-permissions)."
|
||||
|
||||
You cannot use query parameters to set the value of a webhook secret. If an app requires a secret to secure its webhook, the value of the secret must be set in the {% data variables.product.company_short %} UI by the person creating the app.
|
||||
You cannot use query parameters to set the value of a webhook secret. If an app requires a secret to secure its webhook, the value of the secret must be set in the {% data variables.product.company_short %} UI by the person registering the app.
|
||||
|
||||
For more information about webhooks and {% data variables.product.prodname_github_apps %}, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/using-webhooks-with-github-apps)."
|
||||
|
|
@ -58,9 +58,9 @@ Billing managers are users who can manage the billing settings for your organiza
|
|||
If your organization has a security team, you can use the security manager role to give members of the team the least access they need to the organization. For more information, see "[AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization)."
|
||||
{% endif %}
|
||||
### {% data variables.product.prodname_github_app %} managers
|
||||
By default, only organization owners can manage the settings of {% data variables.product.prodname_github_apps %} owned by an organization. To allow additional users to manage {% data variables.product.prodname_github_apps %} owned by an organization, an owner can grant them {% data variables.product.prodname_github_app %} manager permissions.
|
||||
By default, only organization owners can manage the settings of {% data variables.product.prodname_github_app %} registrations owned by an organization. To allow additional users to manage {% data variables.product.prodname_github_app %} registrations owned by an organization, an owner can grant them {% data variables.product.prodname_github_app %} manager permissions.
|
||||
|
||||
When you designate a user as a {% data variables.product.prodname_github_app %} manager in your organization, you can grant them access to manage the settings of some or all {% data variables.product.prodname_github_apps %} owned by the organization. The {% data variables.product.prodname_github_app %} manager role does not grant users access to install and uninstall {% data variables.product.prodname_github_apps %} on an organization. For more information, see "[AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/adding-and-removing-github-app-managers-in-your-organization)."
|
||||
When you designate a user as a {% data variables.product.prodname_github_app %} manager in your organization, you can grant them access to manage the settings of some or all {% data variables.product.prodname_github_app %} registrations owned by the organization. The {% data variables.product.prodname_github_app %} manager role does not grant users access to install and uninstall {% data variables.product.prodname_github_apps %} on an organization. For more information, see "[AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/adding-and-removing-github-app-managers-in-your-organization)."
|
||||
|
||||
### Outside collaborators
|
||||
To keep your organization's data secure while allowing access to repositories, you can add *outside collaborators*. {% data reusables.organizations.outside_collaborators_description %}
|
||||
|
|
|
|||
|
|
@ -1,3 +1,3 @@
|
|||
Organization owners can designate other users in their organization as {% data variables.product.prodname_github_app %} managers. {% data variables.product.prodname_github_app %} managers can manage the settings of some or all of the {% data variables.product.prodname_github_apps %} that are owned by the organization. The {% data variables.product.prodname_github_app %} manager role does not grant users access to install and uninstall {% data variables.product.prodname_github_apps %} on an organization. For more information about the specific app settings that a {% data variables.product.prodname_github_app %} manager can control, see "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app)."
|
||||
Organization owners can designate other users in their organization as {% data variables.product.prodname_github_app %} managers. {% data variables.product.prodname_github_app %} managers can manage the settings of some or all of the {% data variables.product.prodname_github_app %} registrations that are owned by the organization. The {% data variables.product.prodname_github_app %} manager role does not grant users access to install and uninstall {% data variables.product.prodname_github_apps %} on an organization. For more information about the specific app settings that a {% data variables.product.prodname_github_app %} manager can control, see "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app)."
|
||||
|
||||
For more information about {% data variables.product.prodname_github_app %} manager permissions, see "[AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#github-app-managers)."
|
||||
|
|
@ -1 +1 @@
|
|||
{% ifversion fpt or ghec %}A user or organization can own up to 100 {% data variables.product.prodname_github_apps %}, but there is no limit to how many can be installed on an account.{% endif %}
|
||||
{% ifversion fpt or ghec %}A user or organization can register up to 100 {% data variables.product.prodname_github_apps %}, but there is no limit to how many {% data variables.product.prodname_github_app %}s can be installed on an account.{% endif %}
|
||||
|
|
@ -1 +1 @@
|
|||
The specific webhook events that you can select in your app settings are determined by the type of permissions you selected for your app. You will first need to select the permissions you would like your app to have, and then you can subscribe your app to webhook events that are related to that set of permissions.
|
||||
The specific webhook events that you can select for your {% data variables.product.prodname_github_app %} registration are determined by the type of permissions you selected for your app. You will first need to select the permissions you would like your app to have, and then you can subscribe your app to webhook events that are related to that set of permissions.
|
||||
|
|
@ -1 +1 @@
|
|||
After creating a {% data variables.product.prodname_github_app %}, you can make changes to it.
|
||||
After registering a {% data variables.product.prodname_github_app %}, you can make changes to it.
|
||||
|
|
|
|||
|
|
@ -1 +1 @@
|
|||
You can transfer ownership of a GitHub App to another user or organization.
|
||||
You can transfer ownership of a GitHub App registration to another user or organization.
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче