diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000000..39bbd2681d --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,4 @@ +{ + "image": "mcr.microsoft.com/devcontainers/universal:2", + "features": {} +} diff --git a/docs/guides/modules/ROOT/images/ghes-app-event-subscriptions.png b/docs/guides/modules/ROOT/images/ghes-app-event-subscriptions.png new file mode 100644 index 0000000000..6dabe0bc4c Binary files /dev/null and b/docs/guides/modules/ROOT/images/ghes-app-event-subscriptions.png differ diff --git a/docs/guides/modules/ROOT/images/ghes-app-permissions-warning.png b/docs/guides/modules/ROOT/images/ghes-app-permissions-warning.png new file mode 100644 index 0000000000..e5ad1cd5e7 Binary files /dev/null and b/docs/guides/modules/ROOT/images/ghes-app-permissions-warning.png differ diff --git a/docs/guides/modules/ROOT/nav.adoc b/docs/guides/modules/ROOT/nav.adoc index 28c55432e0..36d068e5bd 100644 --- a/docs/guides/modules/ROOT/nav.adoc +++ b/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 diff --git a/docs/guides/modules/integration/pages/github-app-configuration-for-github-enterprise-server.adoc b/docs/guides/modules/integration/pages/github-app-configuration-for-github-enterprise-server.adoc new file mode 100644 index 0000000000..b52e36ca46 --- /dev/null +++ b/docs/guides/modules/integration/pages/github-app-configuration-for-github-enterprise-server.adoc @@ -0,0 +1,168 @@ += Configure the CircleCI GitHub App for GitHub Enterprise Server +:page-platform: Cloud, Server +:page-description: Configure the CircleCI GitHub App on GitHub Enterprise Server with required permissions, events, and troubleshooting steps for updating your configuration. +:experimental: + +This page covers the required permissions and event subscriptions for the CircleCI GitHub App on GitHub Enterprise Server, explains why each permission is needed, and provides steps to update your configuration. + +[#required-permissions-and-events] +== Required permissions and events + +Your CircleCI GitHub App on GitHub Enterprise Server must be configured with the following permissions and event subscriptions. If any are missing, some CircleCI features will not work as expected. + +[#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 +|=== +-- + +All other repository permissions are not required. + +[#event-subscriptions] +=== Event subscriptions + +* Delete +* Issue comment +* Meta +* Pull request +* Pull request review +* Pull request review comment +* Push + +.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] + +Verify your App's current configuration by visiting the App settings page on your GitHub Enterprise Server instance: + +[source,text] +---- +https:///organizations//settings/apps/circleci-app +---- + +Select **Permissions & events** from the left sidebar. + +[#why-circleci-needs-these-permissions-and-events] +== Why CircleCI needs these permissions and events + +[#permissions] +=== Permissions + +* **Commit statuses (read and write)** Allows CircleCI to report build status directly on commits in your repository. This creates the green check or red X next to commits and on pull requests, indicating whether CI has passed or failed. + +* **Contents (read and write)** Allows CircleCI to read your repository code to trigger pipelines, and to perform operations like blobless checkout. Write access enables features that push back to the repository, such as automated configuration updates. + +* **Issues (read and write)** Required for CircleCI's AI agent Chunk to interact with issues, and for features that involve commenting on or reading issue context as part of CI workflows. + +* **Pull requests (read and write)** Enables CircleCI to read pull request details for triggering pipelines on PR events, and to post comments or reviews on pull requests. For example, Chunk uses this permission to provide automated PR review feedback. + +[#events] +=== Events + +* **Delete** Notifies CircleCI when branches or tags are deleted, so that associated pipeline schedules and configurations can be cleaned up accordingly. + +* **Issue comment** Enables CircleCI to respond to comments on issues. Chunk uses this to receive commands and provide feedback directly within GitHub issue threads. + +* **Meta** Notifies CircleCI when the App itself is modified or uninstalled, allowing CircleCI to keep its internal state in sync with your GitHub App configuration. + +* **Pull request** Triggers CircleCI pipelines when pull requests are opened, updated, or closed. This is a core event for CI/CD workflows that run on pull request activity. + +* **Pull request review** Allows CircleCI to react when reviews are submitted on pull requests, enabling features like re-running CI after an approval or triggering specific workflows based on review status. + +* **Pull request review comment** Enables CircleCI to respond to inline review comments on pull requests. Chunk uses this for contextual code review interactions. + +* **Push** The fundamental event for CI/CD. Triggers CircleCI pipelines whenever code is pushed to the repository, including commits to branches and tags. + +[#updating-permissions-and-events] +== Update 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] + +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 + +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. Alternatively, navigate directly to: ++ +[source,text] +---- +https:///organizations//settings/installations +---- +. Find the CircleCI App in the list of installed apps and select **Configure**. +. 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 are an admin of. + +[#find-the-app-owner] +==== Find the App owner + +From the App installation page (the same page from Step 1), look at the top of the page for a "Developed by" label or an **App settings** link. This indicates which organization owns the App and takes you to the App configuration page. + +The App settings URL follows this pattern: + +[source,text] +---- +https:///organizations//settings/apps/circleci-app +---- + +NOTE: If the App is owned by a different organization than yours, 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 <> 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 GitHub organization that has 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 to your organization's App installation configuration page: ++ +[source,text] +---- +https:///organizations//settings/installations +---- +. Find the CircleCI App. You will see a notice about new permissions being requested. +. Review and accept the new permissions. + +The updated permissions take effect for that organization immediately after acceptance.