Add GitHub App configuration guide for GHES

docs/guides/modules/ROOT/nav.adoc

@@ -271,6 +271,7 @@
 ** VCS integration
 *** xref:integration:version-control-system-integration-overview.adoc[VCS integration overview]
 *** xref:guides:integration:using-the-circleci-github-app-in-an-oauth-org.adoc[Using the CircleCI GitHub App in an OAuth org]
+*** xref:integration:github-app-configuration-for-github-enterprise-server.adoc[GitHub App configuration for GitHub Enterprise Server]
 *** xref:integration:oss.adoc[Build open source projects]
 
 ** Third-party integrations

docs/guides/modules/integration/pages/github-app-configuration-for-github-enterprise-server.adoc

@@ -0,0 +1,137 @@
+= GitHub App configuration for GitHub Enterprise Server
+:page-platform: Cloud, Server
+:page-description: Required permissions and event subscriptions for the CircleCI GitHub App on GitHub Enterprise Server, with steps to verify and update your configuration.
+:experimental:
+
+This page describes the expected GitHub App configuration for GitHub Enterprise Server instances and provides steps to verify and update your configuration.
+
+[#overview]
+== Overview
+
+When you first connect an organization in CircleCI to one on your GitHub Enterprise Server instance using the GitHub App integration, CircleCI creates a GitHub App on your instance. This App (named "CircleCI App" by default) includes all required permissions and event subscriptions. No manual configuration is needed. Other organizations on the same instance do not need their own App. They install the same CircleCI App, which is owned and managed by the organization where it was originally registered.
+
+After creation, the admins of the App's host organization and GitHub Enterprise Server instance admins fully own the App configuration. It is their responsibility to ensure that the App configuration is not modified unexpectedly, as changes affect all organizations the App is installed on. CircleCI has no way to identify or rectify issues stemming from unexpected changes to App configuration on your GitHub Enterprise Server instance.
+
+Occasionally, CircleCI may introduce new features that require additional permissions or event subscriptions. When this happens, admins will need to update the App configuration following the steps described on this page.
+
+[#verifying-your-app-configuration]
+== Verifying your App configuration
+
+You can check your App's current configuration by visiting the App settings page on your GitHub Enterprise Server instance:
+
+[source,text]
+----
+https://<your-ghe-instance>/organizations/<HOST_ORG_NAME>/settings/apps/circleci-app
+----
+
+Use the left sidebar to browse through the different sections of the App configuration.
+
+[#required-permissions-and-events]
+== Required permissions and events
+
+Under **Permissions & events** in your App settings, your CircleCI GitHub App must have the following permissions and event subscriptions. If any are missing, some CircleCI features will not work as expected.
+
+NOTE: These lists are updated as new CircleCI features are introduced that require additional permissions or events.
+
+[#repository-permissions]
+=== Repository permissions
+
+[.table-scroll]
+--
+[cols="1,1", options="header"]
+|===
+| Permission
+| Access level
+
+| Commit statuses
+| Read and write
+
+| Contents
+| Read and write
+
+| Issues
+| Read and write
+
+| Pull requests
+| Read and write
+|===
+--
+
+No additional permissions beyond those listed above are currently required.
+
+[#event-subscriptions]
+=== Event subscriptions
+
+* Delete
+* Issue comment
+* Meta
+* Pull request
+* Pull request review
+* Pull request review comment
+* Push
+
+No additional event subscriptions beyond those listed above are currently required.
+
+.Required event subscriptions on the GitHub App settings page
+image::guides:ROOT:ghes-app-event-subscriptions.png[GitHub App settings page showing the required event subscriptions with Delete, Issue comment, Meta, Pull request, Pull request review, Pull request review comment, and Push selected]
+
+[#updating-permissions-and-events]
+== Updating permissions and events
+
+If your App configuration does not match the requirements above, you may see a warning in CircleCI on your GitHub App Server card: **"Some CircleCI features require updated App permissions."**
+
+.Warning displayed when App permissions need updating
+image::guides:ROOT:ghes-app-permissions-warning.png[CircleCI warning banner showing that some features require updated App permissions with a Learn how to fix this link,width=400]
+
+This can happen for one of two reasons:
+
+. The App settings have not been updated yet. Someone with access to the App configuration needs to manually add the required permissions and event subscriptions.
+. The App settings have been updated, but your organization has not accepted the changes yet. When an App's permissions change, every organization with the App installed must separately approve the new permissions.
+
+The steps below help you determine which situation applies and how to resolve it.
+
+[#step-1-check-pending-permissions]
+=== Step 1: Check if your organization has a pending permissions request
+
+This step requires admin access to the organization on GitHub where the App is installed.
+
+If the App settings have already been updated by the App owner, your organization will have a pending request to accept the new permissions.
+
+. In CircleCI, on the GitHub App Server card, select the **settings icon** to open the App installation configuration page on your GitHub Enterprise Server instance. The URL follows this pattern: `https://<your-ghe-instance>/organizations/<YOUR_ORG_NAME>/settings/installations/<INSTALLATION_ID>`
+. Look for a banner or notice requesting approval of additional permissions.
+
+**If you see a permissions request:** Accept it. The new permissions take effect for your organization immediately.
+
+**If you do not see a permissions request:** The App settings have not been updated yet. Continue to Step 2.
+
+[#step-2-update-app-settings]
+=== Step 2: Update the App settings
+
+This step must be performed by an admin of the organization that _owns_ the CircleCI App on your GitHub Enterprise Server instance. This may be a different organization than the one you have checked installation configuration for in Step 1.
+
+[#find-the-app-owner]
+==== Find the App owner
+
+From the App installation page (the same page from Step 1), select the **App settings** link at the top of the page. This will take you to the App configuration page.
+
+NOTE: If the App is owned by a different organization than yours, you may not have access to this link. Contact an admin of that organization, or a GitHub Enterprise Server instance admin, to perform the following steps.
+
+[#apply-the-required-configuration]
+==== Apply the required configuration
+
+. On the App settings page, select **Permissions & events** from the left sidebar.
+. Update the repository permissions and event subscriptions to match the tables in the <<required-permissions-and-events>> section above.
+. Select **Save changes**.
+
+[#step-3-accept-new-permissions]
+=== Step 3: Accept the new permissions on each organization
+
+Once the App settings have been updated, every organization within the GitHub Enterprise Server instance with the CircleCI App installed needs to accept the new permissions. Organization admins receive an email notification from GitHub prompting them to review and approve the changes.
+
+To accept manually:
+
+. Navigate back to your organization's App installation configuration page. You can get there by navigating to CircleCI > Organization Settings > VCS Connections, and selecting the **settings icon** on the GitHub App Server card.
+. Look for a notice about new permissions being requested.
+. Review and accept the new permissions.
+
+The updated permissions take effect for that organization immediately after acceptance.