Update "Modifying a GitHub App" (#36043)

Co-authored-by: Sarah Edwards <skedwards88@github.com>
Co-authored-by: Hirsch Singhal <1666363+hpsin@users.noreply.github.com>

content/apps/creating-github-apps/creating-github-apps/creating-a-github-app.md

@@ -42,7 +42,7 @@ You can create a {% data variables.product.prodname_github_app %} owned by your
 
    For more information about the callback URL, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/about-the-user-authorization-callback-url)." For more information about generating a user access token to act 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)" and "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)."
 1. Optionally, to prevent user access tokens from expiring, deselect **Expire user authorization tokens**. {% data variables.product.company_short %} strongly recommends that you leave this option selected. For more information about refreshing expired tokens and the benefits of user access tokens that expire, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens)." If your app does not need to generate a user access token, this field will be ignored.
-1. Optionally, to prompt users to authorize your app when they install it, select **Request user authorization (OAuth) during installation**. If a user authorizes your app, your app can generate a user access token in order make API requests on the user's behalf and attribute app activity to the 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)" and "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)."
+1. Optionally, to prompt users to authorize your app when they install it, select **Request user authorization (OAuth) during installation**. If a user authorizes your app, your app can generate a user access token to make API requests on the user's behalf and attribute app activity to the 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)" and "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)."
 1. Optionally, if you want to use device flow to generate a user access token, select **Enable Device Flow**. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)."
 1. Optionally, under "Setup URL", enter the URL to redirect users to after they install your app. If additional setup is required after installation, you can use this URL to tell users what steps to take after installation.
 
@@ -56,3 +56,7 @@ You can create a {% data variables.product.prodname_github_app %} owned by your
 1. If you selected **Active** in the earlier step to indicate that your app should receive webhook events, under "Subscribe to events", select the webhook events that you want your app to receive. The permissions that you selected in the previous step determine what webhook events are available. For more information about each webhook event, see "[AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads)."
 1. Under "Where can this GitHub App be installed?", select  **Only on this account** or **Any account**. For more information on installation options, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/making-a-github-app-public-or-private)."
 1. Click **Create GitHub App**.
+
+## Further reading
+
+- "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app)"

content/apps/creating-github-apps/creating-github-apps/index.md

@@ -15,12 +15,11 @@ children:
   - /differences-between-github-apps-and-oauth-apps
   - /rate-limits-for-github-apps
   - /creating-a-github-app
-  - /using-webhooks-with-github-apps
   - /choosing-permissions-for-a-github-app
+  - /using-webhooks-with-github-apps
   - /making-a-github-app-public-or-private
   - /creating-a-github-app-from-a-manifest
   - /creating-a-github-app-using-url-parameters
   - /creating-a-custom-badge-for-your-github-app
   - /about-the-user-authorization-callback-url
 ---
-

content/apps/creating-github-apps/creating-github-apps/making-a-github-app-public-or-private.md

@@ -33,13 +33,11 @@ If you want to make your app available to {% ifversion ghes %}other {% endif %}{
 
 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 an existing {% 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 %}, see "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app)."
 
 ### Public installation flow
 
-Public {% data variables.product.prodname_github_apps %} have a landing page with an **Install** button, so that other people can install the app in their repositories. If you don't want to use the default landing page, you can modify the "Public link" field on the settings page for your {% data variables.product.prodname_github_app %}. For more information, see "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app)."
-
-{% ifversion fpt or ghec %}If your {% data variables.product.prodname_github_app %} is public to all users on {% data variables.product.prodname_dotcom_the_website %}, you can also choose to publish it to {% data variables.product.prodname_marketplace %}. For more information, see "[AUTOTITLE](/apps/publishing-apps-to-github-marketplace/github-marketplace-overview/about-github-marketplace)."{% endif %}
+Public {% data variables.product.prodname_github_apps %} have a landing page with an **Install** button, so that other people can install the app in their repositories. {% ifversion fpt or ghec %}If your {% data variables.product.prodname_github_app %} is public to all users on {% data variables.product.prodname_dotcom_the_website %}, you can also choose to publish it to {% data variables.product.prodname_marketplace %}. For more information, see "[AUTOTITLE](/apps/publishing-apps-to-github-marketplace/github-marketplace-overview/about-github-marketplace)."{% endif %}
 
 ### Private installation flow
 

content/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps.md

@@ -21,6 +21,8 @@ To receive webhook events in your {% data variables.product.prodname_github_app
 
 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/creating-github-apps/creating-a-github-app)."
 
+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)."
+
 ## 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.
@@ -53,7 +55,7 @@ After creating a webhook secret for your app, you will need to configure your se
 
 ## Subscribing to webhook events
 
-You can subscribe your {% data variables.product.prodname_github_app %} to receive webhook payloads for specific events. 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. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app)."
+You can subscribe your {% data variables.product.prodname_github_app %} to receive webhook payloads for specific events. {% data reusables.apps.webhooks-and-apps %} For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app)."
 
 For example, if you would like your app to receive a webhook event payload whenever a new issue is opened in your repository, you would first need to give your app permission to access "Issues" under "Repository permissions." Then under "Subscribe to events" you can select "Issues."
 

content/apps/maintaining-github-apps/editing-a-github-apps-permissions.md

@@ -1,32 +0,0 @@
----
-title: Editing a GitHub App's permissions
-intro: '{% data reusables.shortdesc.editing_permissions_for_github_apps %}'
-redirect_from:
-  - /apps/building-integrations/managing-github-apps/editing-a-github-app-s-permissions
-  - /apps/managing-github-apps/editing-a-github-app-s-permissions
-  - /developers/apps/editing-a-github-apps-permissions
-  - /developers/apps/managing-github-apps/editing-a-github-apps-permissions
-versions:
-  fpt: '*'
-  ghes: '*'
-  ghae: '*'
-  ghec: '*'
-topics:
-  - GitHub Apps
-shortTitle: Edit permissions
----
-{% note %}
-
-**Note:** Updated permissions won't take effect on an installation until the owner of the account or organization approves the changes. You can use the [InstallationEvent webhook](/webhooks-and-events/webhooks/webhook-events-and-payloads#installation) to find out when people accept new permissions for your app. One exception is user-level permissions, which don't require the account owner to approve permission changes.
-
-{% endnote %}
-
-{% data reusables.user-settings.access_settings %}
-{% data reusables.user-settings.developer_settings %}
-{% data reusables.user-settings.github_apps %}
-{% data reusables.user-settings.modify_github_app %}
-5. In the {% data variables.product.prodname_github_apps %} settings sidebar, click **Permissions & events**.
-6. Under "Repository permissions", "Organization permissions", and "Account permissions" sections, modify the permissions you'd like to change. For each type of permission, select either "Read-only", "Read and write", or "No access" from the dropdown. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app)."
-7. Under "Subscribe to events", select any events to which you'd like to subscribe your app.
-8. Optionally, under "Add a note to users", add a note telling your users why you are changing the permissions that your GitHub App requests.
-9. Click **Save changes**.

content/apps/maintaining-github-apps/index.md

@@ -15,7 +15,6 @@ topics:
 children:
   - /about-github-app-managers
   - /modifying-a-github-app
-  - /editing-a-github-apps-permissions
   - /managing-allowed-ip-addresses-for-a-github-app
   - /installing-github-apps
   - /activating-optional-features-for-apps

content/apps/maintaining-github-apps/modifying-a-github-app.md

@@ -6,6 +6,11 @@ redirect_from:
   - /apps/managing-github-apps/modifying-a-github-app
   - /developers/apps/modifying-a-github-app
   - /developers/apps/managing-github-apps/modifying-a-github-app
+  - /apps/building-integrations/managing-github-apps/editing-a-github-app-s-permissions
+  - /apps/managing-github-apps/editing-a-github-app-s-permissions
+  - /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
 versions:
   fpt: '*'
   ghes: '*'
@@ -14,10 +19,95 @@ versions:
 topics:
   - GitHub Apps
 ---
-{% data reusables.user-settings.access_settings %}
+
+## 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)."
+
+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.
+
+## Navigating to your {% data variables.product.prodname_github_app %} settings
+
+To modify a {% data variables.product.prodname_github_app %}, first navigate to the app settings page.
+
+{% data reusables.apps.settings-step %}
 {% data reusables.user-settings.developer_settings %}
 {% data reusables.user-settings.github_apps %}
 {% data reusables.user-settings.modify_github_app %}
-1. In "Basic information", modify the GitHub App information that you'd like to change.{% ifversion device-flow-is-opt-in %}
-1. If your GitHub App will use the device flow to generate a user access token, click **Enable device flow**. For more information about device flow, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)."{% endif %}
+
+## Changing the basic information of a {% data variables.product.prodname_github_app %}
+
+You can change the basic information of your {% data variables.product.prodname_github_app %}, like the name of the app, the description of the app, and the homepage URL of the app.
+
+{% data reusables.apps.navigate-to-app-settings-this-article %}
+1. Under "Basic information," modify the {% data variables.product.prodname_github_app %} information that you'd like to change.
 1. Click **Save changes**.
+
+## Requesting user authorization (OAuth) during installation
+
+You can prompt users to authorize your {% data variables.product.prodname_github_app %} when they install it and generate a user access token. When you request user authorization (OAuth) during installation, you must also provide a callback URL where the user will be redirected after they authorize the installation. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)."
+
+{% data reusables.apps.navigate-to-app-settings-this-article %}
+1. Under "Identifying and authorizing users," select or deselect **Request user authorization (OAuth) during installation**.
+1. Under "Callback URL," enter the full URL to redirect to after a user authorizes the installation.
+
+## Enabling or disabling the device flow
+
+You can use the device flow to authorize users for a headless app like a CLI tool or Git credential manager. For more information about using the device flow with {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_oauth_apps %}, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app#using-the-device-flow-to-generate-a-user-access-token)" and "[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#device-flow)."
+
+{% data reusables.apps.navigate-to-app-settings-this-article %}
+1. Under "Identifying and authorizing users," select or deselect **Enable Device Flow**.
+
+## Adding or updating a setup URL
+
+You can redirect people to a specific URL after they install your app. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app)."
+
+If you select **Request user authorization (OAuth) during installation**, you will not be able to enter a setup URL. Users will instead be redirected to the Callback URL as part of the authorization flow, where you can describe additional setup. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/about-the-user-authorization-callback-url)."
+
+{% data reusables.apps.navigate-to-app-settings-this-article %}
+1. Under "Post installation," in the "Setup URL" field, enter the URL where you'd like to redirect users after they install your app.
+1. Optionally, if you want to redirect users to the setup URL after they update an installation, select **Redirect on update**. An update includes adding or removing a repository for an installation. If "Setup URL" is blank, this will be ignored.
+
+## Changing the permissions of a {% data variables.product.prodname_github_app %}
+
+You can change the access permissions that are granted to your {% data variables.product.prodname_github_app %} using the following steps.
+
+When you change the **repository** or **organization** permissions of an app, each account where the app is installed will need to approve the new permissions. When you change the **account** permissions of an app, each user that has authorized the app will need to approve the permission changes. Updated permissions won't take effect on an installation or user authorization until the new permissions are approved. You can use the [installation webhook](/webhooks-and-events/webhooks/webhook-events-and-payloads?actionType=new_permissions_accepted#installation) to find out when people accept new permissions for your app.
+
+Changing the permissions of an app may also change the webhooks that your app can subscribe to and the actions that your app can take with the API. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app)."
+
+{% data reusables.apps.navigate-to-app-settings-this-article %}
+1. In the {% data variables.product.prodname_github_apps %} settings sidebar, click **Permissions & events**.
+1. Under the sections "Repository permissions," "Organization permissions," and "Account permissions," modify the permissions you'd like to change. For each type of permission, select either "Read-only," "Read and write," or "No access" from the dropdown. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app)."
+1. Optionally, under "Add a note to users," add a note telling your users why you are changing the permissions that your {% data variables.product.prodname_github_app %} requests.
+1. Click **Save changes**.
+
+## Activating or deactivating the {% data variables.product.prodname_github_app %} webhook
+
+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, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps)."
+
+{% data reusables.apps.navigate-to-app-settings-this-article %}
+1. Under "Webhook," to enable or disable the webhook, select or deselect **Active**.
+1. If you selected **Active** in the previous step, under "Webhook URL," enter the URL that {% data variables.product.prodname_dotcom %} should send webhook events to.
+1. Optionally, if you selected **Active** in the previous step, under "Webhook secret," enter a secret token to secure your webhooks. {% data variables.product.prodname_dotcom %} highly recommends that you set a webhook secret.
+
+## Changing the webhook event subscriptions of a {% data variables.product.prodname_github_app %}
+
+You can change the webhook events that a {% data variables.product.prodname_github_app %} subscribes to using the following steps.
+
+{% data reusables.apps.webhooks-and-apps %} For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps)."
+
+{% data reusables.apps.navigate-to-app-settings-this-article %}
+1. Activate the {% data variables.product.prodname_github_app %} webhook. For more information, see "[Activating or deactivating the {% data variables.product.prodname_github_app %} webhook](/apps/maintaining-github-apps/modifying-a-github-app#activating-or-deactivating-the-github-app-webhook)" in this article.
+1. In the {% data variables.product.prodname_github_apps %} settings sidebar, click **Permissions & events**.
+1. Under the sections "Repository permissions," "Organization permissions," and "Account permissions," select the permissions that are required for the events your app will subscribe to. For more information, see "[Changing the permissions of a {% data variables.product.prodname_github_app %}](#changing-the-permissions-of-a-github-app)."
+1. Under "Subscribe to Events," select the webhook events you would like your {% data variables.product.prodname_github_app %} to receive.
+1. Click **Save changes**.
+
+## Changing the visibility of a {% data variables.product.prodname_github_app %}
+
+You can change the visibility settings of your {% data variables.product.prodname_github_app %} to control who can install it. Public apps cannot be made private if they're installed on other accounts. For more information, see "[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/making-a-github-app-public-or-private)."
+
+{% data reusables.apps.navigate-to-app-settings-this-article %}
+{% data reusables.user-settings.github_apps_advanced %}
+1. Under "Danger zone," depending on the current visibility of your {% data variables.product.prodname_github_app %}, click either **Make public** or **Make private**.

content/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps.md

@@ -124,7 +124,7 @@ The device flow allows you to authorize users for a headless app, such as a CLI
 
 {% ifversion device-flow-is-opt-in %}
 
-Before you can use the device flow to authorize and identify users, you must first enable it in your app's settings. For more information about enabling the device flow in your app, see "[AUTOTITLE](/apps/oauth-apps/maintaining-oauth-apps/modifying-an-oauth-app)" for OAuth Apps and "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app)" for GitHub Apps.
+Before you can use the device flow to authorize and identify users, you must first enable it in your app's settings. For more information about enabling the device flow in your app, see "[AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app)" for {% data variables.product.prodname_github_apps %} and "[AUTOTITLE](/apps/oauth-apps/maintaining-oauth-apps/modifying-an-oauth-app)" for {% data variables.product.prodname_oauth_apps %}.
 
 {% endif %}
 

content/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app.md

@@ -52,3 +52,7 @@ topics:
 {% endif %}{% ifversion device-flow-is-opt-in %}
 1. If your OAuth App will use the device flow to identify and authorize users, click **Enable Device Flow**. For more information about the device flow, see "[AUTOTITLE](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#device-flow)."{% endif %}
 1. Click **Register application**.
+
+## Further reading
+
+- "[AUTOTITLE](/apps/oauth-apps/maintaining-oauth-apps/modifying-an-oauth-app)"

data/reusables/apps/navigate-to-app-settings-this-article.md

@@ -0,0 +1 @@
+1. Navigate to the settings page for the app you'd like to modify. For more information, see "[Navigating to your {% data variables.product.prodname_github_app %} settings](#navigating-to-your-github-app-settings)" in this article.

data/reusables/apps/webhooks-and-apps.md

@@ -0,0 +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.

data/reusables/shortdesc/modifying_github_apps.md

@@ -1 +1 @@
-After creating a GitHub App, you can make changes to it.
+After creating a {% data variables.product.prodname_github_app %}, you can make changes to it.