Document GitHub Apps allow lists (#19564)

content/admin/configuration/configuring-your-enterprise/restricting-network-traffic-to-your-enterprise.md

@@ -15,11 +15,12 @@ redirect_from:
   - /admin/configuration/restricting-network-traffic-to-your-enterprise
 ---
 ### About IP allow lists
+
 By default, authorized users can access your enterprise from any IP address. Enterprise owners can restrict access to assets owned by organizations in an enterprise account by configuring an allow list for specific IP addresses. {% data reusables.identity-and-permissions.ip-allow-lists-example-and-restrictions %}
 
 {% data reusables.identity-and-permissions.ip-allow-lists-cidr-notation %}
 
-{% data reusables.identity-and-permissions.ip-allow-lists-enable %}
+{% data reusables.identity-and-permissions.ip-allow-lists-enable %} {% data reusables.identity-and-permissions.ip-allow-lists-enterprise %} 
 
 You can also configure allowed IP addresses for an individual organization. For more information, see "[Managing allowed IP addresses for your organization](/organizations/keeping-your-organization-secure/managing-allowed-ip-addresses-for-your-organization)."
 
@@ -36,6 +37,10 @@ For instance-level restrictions using Azure NSGs, contact {% data variables.cont
 {% data reusables.identity-and-permissions.ip-allow-lists-add-description %}
 {% data reusables.identity-and-permissions.ip-allow-lists-add-entry %}
 
+### Allowing access by {% data variables.product.prodname_github_apps %}
+
+{% data reusables.identity-and-permissions.ip-allow-lists-githubapps-enterprise %}
+
 ### Enabling allowed IP addresses
 
 {% data reusables.enterprise-accounts.access-enterprise %}

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

@@ -23,38 +23,38 @@ topics:
 {% endnote %}
 {% endif %}
 
-{% data reusables.user-settings.access_settings %}
+{% data reusables.apps.settings-step %}
 {% data reusables.user-settings.developer_settings %}
 {% data reusables.user-settings.github_apps %}
-4. Click **New GitHub App**.
+1. Click **New GitHub App**.
 ![Button to create a new GitHub App](/assets/images/github-apps/github_apps_new.png)
-5. In "GitHub App name", type the name of your app.
+1. In "GitHub App name", type the name of your app.
 ![Field for the name of your GitHub App](/assets/images/github-apps/github_apps_app_name.png)
 
   Give your app a clear and succinct name. Your app cannot have the same name as an existing GitHub account, unless it is your own user or organization name. A slugged version of your app's name will be shown in the user interface when your integration takes an action.
 
-6. Optionally, in "Description", type a description of your app that users will see.
+1. Optionally, in "Description", type a description of your app that users will see.
 ![Field for a description of your GitHub App](/assets/images/github-apps/github_apps_description.png)
-7. In "Homepage URL", type the full URL to your app's website.
+1. In "Homepage URL", type the full URL to your app's website.
 ![Field for the homepage URL of your GitHub App](/assets/images/github-apps/github_apps_homepage_url.png)
 {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}
-8. In "Callback URL", type the full URL to redirect to after a user authorizes the installation. This URL is used if your app needs to identify and authorize user-to-server requests.
+1. In "Callback URL", type the full URL to redirect to after a user authorizes the installation. This URL is used if your app needs to identify and authorize user-to-server requests.
 
   You can use **Add callback URL** to provide additional callback URLs, up to a maximum of 10.
 
   ![Button for 'Add callback URL' and field for callback URL](/assets/images/github-apps/github_apps_callback_url_multiple.png)
 {% else %}
-8. In "User authorization callback URL", type the full URL to redirect to after a user authorizes an installation. This URL is used if your app needs to identify and authorize user-to-server requests.
+1. In "User authorization callback URL", type the full URL to redirect to after a user authorizes an installation. This URL is used if your app needs to identify and authorize user-to-server requests.
 ![Field for the user authorization callback URL of your GitHub App](/assets/images/github-apps/github_apps_user_authorization.png)
 
 {% endif %}
 {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.21" or currentVersion == "github-ae@latest" %}
-9. By default, to improve your app's security, your app will use expiring user authorization tokens. To opt-out of using expiring user tokens, you must deselect "Expire user authorization tokens". To learn more about setting up a refresh token flow and the benefits of expiring user tokens, see "[Refreshing user-to-server access tokens](/apps/building-github-apps/refreshing-user-to-server-access-tokens/)."
+1. By default, to improve your app's security, your app will use expiring user authorization tokens. To opt-out of using expiring user tokens, you must deselect "Expire user authorization tokens". To learn more about setting up a refresh token flow and the benefits of expiring user tokens, see "[Refreshing user-to-server access tokens](/apps/building-github-apps/refreshing-user-to-server-access-tokens/)."
   ![Option to opt-in to expiring user tokens during GitHub Apps setup](/assets/images/github-apps/expire-user-tokens-selection.png)
 {% endif %}
-9. If your app authorizes users using the OAuth flow, you can select **Request user authorization (OAuth) during installation** to allow people to authorize the app when they install it, saving a step. If you select this option, the "Setup URL" becomes unavailable and users will be redirected to your "User authorization callback URL" after installing the app. See "[Authorizing users during installation](/apps/installing-github-apps/#authorizing-users-during-installation)" for more information.
+1. If your app authorizes users using the OAuth flow, you can select **Request user authorization (OAuth) during installation** to allow people to authorize the app when they install it, saving a step. If you select this option, the "Setup URL" becomes unavailable and users will be redirected to your "User authorization callback URL" after installing the app. See "[Authorizing users during installation](/apps/installing-github-apps/#authorizing-users-during-installation)" for more information.
 ![Request user authorization during installation](/assets/images/github-apps/github_apps_request_auth_upon_install.png)
-10. If additional setup is required after installation, add a "Setup URL" to redirect users to after they install your app.
+1. If additional setup is required after installation, add a "Setup URL" to redirect users to after they install your app.
 ![Field for the setup URL of your GitHub App ](/assets/images/github-apps/github_apps_setup_url.png)
 
   {% note %}
@@ -63,10 +63,10 @@ topics:
 
   {% endnote %}
 
-11. In "Webhook URL", type the URL that events will POST to. Each app receives its own webhook which will notify you every time the app is installed or modified, as well as any other events the app subscribes to.
+1. In "Webhook URL", type the URL that events will POST to. Each app receives its own webhook which will notify you every time the app is installed or modified, as well as any other events the app subscribes to.
 ![Field for the webhook URL of your GitHub App](/assets/images/github-apps/github_apps_webhook_url.png)
 
-12. Optionally, in "Webhook Secret", type an optional secret token used to secure your webhooks.
+1. Optionally, in "Webhook Secret", type an optional secret token used to secure your webhooks.
 ![Field to add a secret token for your webhook](/assets/images/github-apps/github_apps_webhook_secret.png)
 
   {% note %}
@@ -75,10 +75,10 @@ topics:
 
   {% endnote %}
 
-13. In "Permissions", choose the permissions your app will request. For each type of permission, use the drop-down menu and click **Read-only**, **Read & write**, or **No access**.
+1. In "Permissions", choose the permissions your app will request. For each type of permission, use the drop-down menu and click **Read-only**, **Read & write**, or **No access**.
 ![Various permissions for your GitHub App](/assets/images/github-apps/github_apps_new_permissions_post2dot13.png)
-14. In "Subscribe to events", choose the events you want your app to receive.
-15. To choose where the app can be installed, select either **Only on this account** or **Any account**. For more information on installation options, see "[Making a GitHub App public or private](/apps/managing-github-apps/making-a-github-app-public-or-private/)."
+1. In "Subscribe to events", choose the events you want your app to receive.
+1. To choose where the app can be installed, select either **Only on this account** or **Any account**. For more information on installation options, see "[Making a GitHub App public or private](/apps/managing-github-apps/making-a-github-app-public-or-private/)."
 ![Installation options for your GitHub App](/assets/images/github-apps/github_apps_installation_options.png)
-16. Click **Create GitHub App**.
+1. Click **Create GitHub App**.
 ![Button to create your GitHub App](/assets/images/github-apps/github_apps_create_github_app.png)

content/developers/apps/building-github-apps/index.md

@@ -13,6 +13,7 @@ topics:
 children:
   - /creating-a-github-app
   - /setting-permissions-for-github-apps
+  - /managing-allowed-ip-addresses-for-a-github-app
   - /authenticating-with-github-apps
   - /identifying-and-authorizing-users-for-github-apps
   - /rate-limits-for-github-apps

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

@@ -0,0 +1,33 @@
+---
+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.
+versions:
+  free-pro-team: '*'
+  github-ae: '*'
+topics:
+  - GitHub Apps
+---
+
+### About IP address allow lists for {% data variables.product.prodname_github_apps %}
+
+Enterprise and organization owners can restrict access to assets by configuring an IP address allow list. This list specifies the IP addresses that are allowed to connect. For more information, see "[Managing allowed IP addresses for your organization](/organizations/keeping-your-organization-secure/managing-allowed-ip-addresses-for-your-organization#enabling-allowed-ip-addresses)" and {% if currentVersion == "github-ae@latest" %}"[Restricting network traffic to your enterprise](/admin/configuration/configuring-your-enterprise/restricting-network-traffic-to-your-enterprise)." {% else %}"[Enforcing security settings in your enterprise account](/github/setting-up-and-managing-your-enterprise/setting-policies-for-organizations-in-your-enterprise-account/enforcing-security-settings-in-your-enterprise-account#managing-allowed-ip-addresses-for-organizations-in-your-enterprise-account)." {% endif %}
+
+When an organization has an allow list, third-party applications that connect via a {% data variables.product.prodname_github_app %} will be denied access unless both of the following are true:
+
+* The creator of the {% data variables.product.prodname_github_app %} has configured an allow list for the application that specifies the IP addresses at which their application runs. See below for details of how to do this.
+* The organization owner has chosen to permit the addresses in the {% data variables.product.prodname_github_app %}'s allow list to be added to their own allow list. For more information, see "[Managing allowed IP addresses for your organization](/organizations/keeping-your-organization-secure/managing-allowed-ip-addresses-for-your-organization#allowing-access-by-github-apps)."
+
+{% data reusables.apps.ip-allow-list-only-apps %}
+
+### Adding an IP address allow list to a {% data variables.product.prodname_github_app %}
+
+{% 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. Scroll down to the "IP allow list" section.
+![Basic information section for your GitHub App](/assets/images/github-apps/github-apps-allow-list-empty.png)
+{% data reusables.identity-and-permissions.ip-allow-lists-add-ip %}
+{% data reusables.identity-and-permissions.ip-allow-lists-add-description %}
+  The description is for your reference and is not used in the allow list of organizations where the {% data variables.product.prodname_github_app %} is installed. Instead, organization allow lists will include "Managed by the NAME GitHub App" as the description.
+{% data reusables.identity-and-permissions.ip-allow-lists-add-entry %}

content/github/setting-up-and-managing-your-enterprise/setting-policies-for-organizations-in-your-enterprise-account/enforcing-security-settings-in-your-enterprise-account.md

@@ -49,7 +49,7 @@ Enterprise owners can restrict access to assets owned by organizations in an ent
 
 {% data reusables.identity-and-permissions.ip-allow-lists-cidr-notation %}
 
-{% data reusables.identity-and-permissions.ip-allow-lists-enable %}
+{% data reusables.identity-and-permissions.ip-allow-lists-enable %} {% data reusables.identity-and-permissions.ip-allow-lists-enterprise %} 
 
 You can also configure allowed IP addresses for an individual organization. For more information, see "[Managing allowed IP addresses for your organization](/organizations/keeping-your-organization-secure/managing-allowed-ip-addresses-for-your-organization)."
 
@@ -62,6 +62,10 @@ You can also configure allowed IP addresses for an individual organization. For
 {% data reusables.identity-and-permissions.ip-allow-lists-add-description %}
 {% data reusables.identity-and-permissions.ip-allow-lists-add-entry %}
 
+#### Allowing access by {% data variables.product.prodname_github_apps %}
+
+{% data reusables.identity-and-permissions.ip-allow-lists-githubapps-enterprise %}
+
 #### Enabling allowed IP addresses
 
 {% data reusables.enterprise-accounts.access-enterprise %}

content/organizations/keeping-your-organization-secure/managing-allowed-ip-addresses-for-your-organization.md

@@ -22,6 +22,8 @@ You can restrict access to organization assets by configuring an allow list for
 
 {% data reusables.identity-and-permissions.ip-allow-lists-enable %}
 
+If you set up an allow list you can also choose to automatically add to your allow list any IP addresses configured for {% data variables.product.prodname_github_apps %} that you install in your organization. The creator of a {% data variables.product.prodname_github_app %} can configure an allow list for their application, specifying the IP addresses at which the application runs. By inheriting their allow list into yours, you avoid connection requests from the application being refused. For more information, see "[Allowing access by {% data variables.product.prodname_github_apps %}](#allowing-access-by-github-apps)."
+
 You can also configure allowed IP addresses for the organizations in an enterprise account. For more information, see {% if currentVersion == "github-ae@latest" %}"[Restricting network traffic to your enterprise](/admin/configuration/restricting-network-traffic-to-your-enterprise)." {% else %}"[Enforcing security settings in your enterprise account](/github/setting-up-and-managing-your-enterprise/enforcing-security-settings-in-your-enterprise-account#managing-allowed-ip-addresses-for-organizations-in-your-enterprise-account)."{% endif %}
 
 ### Adding an allowed IP address
@@ -38,9 +40,26 @@ You can also configure allowed IP addresses for the organizations in an enterpri
 {% data reusables.profile.access_org %}
 {% data reusables.profile.org_settings %}
 {% data reusables.organizations.security %}
-3. Under "IP allow list", select **Enable IP allow list**.
+1. Under "IP allow list", select **Enable IP allow list**.
   ![Checkbox to allow IP addresses](/assets/images/help/security/enable-ip-allowlist-organization-checkbox.png)
-4. Click **Save**.
+1. Click **Save**.
+
+### Allowing access by {% data variables.product.prodname_github_apps %}
+
+If you're using an allow list, you can also choose to automatically add to your allow list any IP addresses configured for {% data variables.product.prodname_github_apps %} that you install in your organization. 
+
+{% data reusables.identity-and-permissions.ip-allow-lists-address-inheritance %}
+
+{% data reusables.apps.ip-allow-list-only-apps %}
+
+For more information about how to create an allow list for a {% data variables.product.prodname_github_app %} you have created, see "[Managing allowed IP addresses for a GitHub App](/developers/apps/building-github-apps/managing-allowed-ip-addresses-for-a-github-app)."
+
+{% data reusables.profile.access_org %}
+{% data reusables.profile.org_settings %}
+{% data reusables.organizations.security %}
+1. Under "IP allow list", select **Enable IP allow list configuration for installed GitHub Apps**.
+  ![Checkbox to allow GitHub App IP addresses](/assets/images/help/security/enable-ip-allowlist-githubapps-checkbox.png)
+1. Click **Save**.
 
 ### Editing an allowed IP address
 
@@ -50,7 +69,7 @@ You can also configure allowed IP addresses for the organizations in an enterpri
 {% data reusables.identity-and-permissions.ip-allow-lists-edit-entry %}
 {% data reusables.identity-and-permissions.ip-allow-lists-edit-ip %}
 {% data reusables.identity-and-permissions.ip-allow-lists-edit-description %}
-8. Click **Update**.
+1. Click **Update**.
 
 ### Deleting an allowed IP address
 

data/reusables/apps/ip-allow-list-only-apps.md

@@ -0,0 +1,5 @@
+{% note %}
+
+**Note:** The addresses in the IP allow list of a {% data variables.product.prodname_github_app %} only affect requests made by installations of the {% data variables.product.prodname_github_app %}. The automatic addition of a {% data variables.product.prodname_github_app %}'s IP address to an organization's allow list does not allow access to a {% data variables.product.product_name %} user who connects from that IP address.
+
+{% endnote %}

data/reusables/apps/settings-step.md

@@ -0,0 +1,6 @@
+1. Navigate to your account settings.
+   - For a {% data variables.product.prodname_github_app %} owned by a user account, in the upper-right corner of any page, click your profile photo, then click **Settings**.
+    ![Settings icon in the user bar](/assets/images/settings/userbar-account-settings_post2dot12.png)
+   - For a {% data variables.product.prodname_github_app %} owned by an organization, in the upper-right corner of any page, click your profile photo, then click **Your organizations**. Then, to the right of the organization, click **Settings**.
+    ![Your organizations in the profile menu](/assets/images/help/profile/your-organizations.png)
+    ![The settings button](/assets/images/help/organizations/settings-button.png)

data/reusables/identity-and-permissions/ip-allow-lists-add-description.md

@@ -1,2 +1,2 @@
-1. Under "Description", type a description of the allowed IP address or range.
+1. Optionally, enter a description of the allowed IP address or range.
   ![Key field to add name for IP address](/assets/images/help/security/ip-address-name-field.png)

data/reusables/identity-and-permissions/ip-allow-lists-add-ip.md

@@ -1,2 +1,2 @@
-1. Under "IP Address", type an IP address, or range of addresses, in CIDR notation.
+1. At the bottom of the "IP allow list" section, enter an IP address, or a range of addresses in CIDR notation.
   ![Key field to add IP address](/assets/images/help/security/ip-address-field.png)

data/reusables/identity-and-permissions/ip-allow-lists-address-inheritance.md

@@ -0,0 +1,3 @@
+If you select **Enable IP allow list configuration for installed GitHub Apps** in your allow list settings, then IP addresses from installed {% data variables.product.prodname_github_apps %} are added to your allow list. This happens irrespective of whether your allow list is currently enabled. If you install a {% data variables.product.prodname_github_app %} and then the creator of that application changes the addresses in its allow list, your allow list is automatically updated with those changes.
+
+You can identify the IP addresses that have been automatically added from {% data variables.product.prodname_github_apps %} by reviewing the description field. The description for these IP addresses is: "Managed by the NAME GitHub App." Unlike addresses you add manually, you cannot edit, delete, or disable IP addresses that are automatically added from {% data variables.product.prodname_github_apps %}.

data/reusables/identity-and-permissions/ip-allow-lists-enterprise.md

@@ -0,0 +1,3 @@
+When you enable the allow list, the IP addresses you have configured are immediately added to the allow lists of organizations in your enterprise. If you disable the allow list, the addresses are removed from the organization allow lists.
+
+You can choose to automatically add to your allow list any IP addresses configured for {% data variables.product.prodname_github_apps %} installed in your enterprise. The creator of a {% data variables.product.prodname_github_app %} can configure an allow list for their application, specifying the IP addresses at which the application runs. By inheriting their allow list into yours, you avoid connection requests from the application being refused. For more information, see "[Allowing access by GitHub Apps](#allowing-access-by-github-apps)."

data/reusables/identity-and-permissions/ip-allow-lists-githubapps-enterprise.md

@@ -0,0 +1,16 @@
+If you're using an allow list, you can also choose to automatically add to your allow list any IP addresses configured for {% data variables.product.prodname_github_apps %} that are installed in your enterprise. 
+
+{% data reusables.identity-and-permissions.ip-allow-lists-address-inheritance %}
+
+{% data reusables.apps.ip-allow-list-only-apps %}
+
+For more information about how to create an allow list for a {% data variables.product.prodname_github_app %} you have created, see "[Managing allowed IP addresses for a GitHub App](/developers/apps/building-github-apps/managing-allowed-ip-addresses-for-a-github-app)."
+
+To enable automatic addition of IP addresses for {% data variables.product.prodname_github_apps %}:
+
+{% data reusables.enterprise-accounts.access-enterprise %}
+{% data reusables.enterprise-accounts.settings-tab %}
+{% data reusables.enterprise-accounts.security-tab %}
+1. Under "IP allow list", select **Enable IP allow list configuration for installed GitHub Apps**.
+  ![Checkbox to allow GitHub App IP addresses](/assets/images/help/security/enable-ip-allowlist-githubapps-checkbox.png)
+1. Click **Save**.

data/reusables/user-settings/modify_github_app.md

@@ -1,2 +1,2 @@
-1. Select the GitHub App you want to modify.
+1. To the right of the {% data variables.product.prodname_github_app %} you want to modify, click **Edit**.
 ![App selection](/assets/images/github-apps/github_apps_select-app.png)