From 5648da86128614f1b19a1414c8aeb97a5f5a635d Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 24 Oct 2026 22:04:32 +0000 Subject: [PATCH] Rewrite GHES setup around the dashboard GitHub Enterprise flow Co-authored-by: brandon --- deploy/ghes.mdx | 146 +++++++++++------------------------------------- 1 file changed, 32 insertions(+), 114 deletions(-) diff --git a/deploy/ghes.mdx b/deploy/ghes.mdx index 04cab8120..fa8bf53ba 100644 --- a/deploy/ghes.mdx +++ b/deploy/ghes.mdx @@ -8,14 +8,15 @@ keywords: ["GitHub Enterprise Server", "GHES", "GitHub Enterprise"] Connecting a GitHub Enterprise Server instance requires an [Enterprise plan](https://mintlify.com/pricing?ref=ghes). -This guide walks you through setting up the Mintlify GitHub App on your GitHub Enterprise Server (GHES) installation. To connect a GHES instance to Mintlify, you must create a local version of our app within your self-hosted environment that communicates with our remote server. +This guide walks you through connecting a GitHub Enterprise Server (GHES) instance to Mintlify. You create a GitHub App owned by your GitHub organization from the Mintlify dashboard, install it, and Mintlify links it to your deployment. If you use a cloud-hosted GitHub instance, see the [GitHub](/deploy/github) page for setup instructions. ## Prerequisites -- Admin privileges on your GitHub Enterprise Server organization where you want to install the app -- Access to your organization's repositories where you want to install the app +- GitHub Enterprise enabled for your Mintlify organization. Contact your customer success representative if you don't see the **GitHub Enterprise** section on the [Git settings](https://app.mintlify.com/settings/project/git-settings) page. +- The admin or editor role in your Mintlify organization. +- Owner access to the GitHub organization that should own the app. - Network connectivity to communicate with our external services (see [Network requirements](#network-requirements) section below) ### Network requirements @@ -39,152 +40,70 @@ If a firewall or IP allowlist restricts access to your GHES instance, allow inbo [Agent](/agent) runs clone and push from separate sandbox infrastructure that uses dynamic IP addresses by default. If your GHES instance enforces an IP allowlist, see [Fix agent runs blocked by an IP allow list](/help-center/agent-blocked-by-git-provider-ip-allow-list). -## Step 1: register the GitHub App - -See [Registering a GitHub App](https://docs.github.com/en/enterprise-server@3.18/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) in the GitHub documentation for detailed instructions. +## Step 1: start the setup in your dashboard - -1. In the upper-right corner of any page on GitHub, click your profile picture. -2. Click **Your organizations**. -3. Click **Settings** next to the organization that you want to create the app for. - - - -1. In the left sidebar, click **Developer settings**. -2. Click **GitHub Apps**. -3. Click **New GitHub App**. + +Go to the [Git settings](https://app.mintlify.com/settings/project/git-settings) page and select **GitHub** as your provider. - -Set the following: + +In the **GitHub Enterprise** section, enter: -- **GitHub App name:** `Mintlify` -- **Description:** `Integration with Mintlify services` -- **Homepage URL:** `https://mintlify.com` -- **User authorization callback URL:** `https://your-github-server.com/` (replace with your actual GHES domain) +- **GitHub host:** The URL of your GHES instance, such as `https://github.yourcompany.com`. +- **GitHub organization:** The organization that should own the app. + + +Click **Create GitHub App**. Mintlify sends you to GitHub with the app's name, permissions, events, and webhook URL already filled in. -## Step 2: configure app permissions +## Step 2: create the app on GitHub - -Set the following permissions for the app. The app needs no Organization, Account, or Enterprise permissions: + +GitHub shows the app it is about to create for your organization. You can change the name. Leave the permissions and webhook settings as they are. + +The app requests these repository permissions: - **Checks:** Read and write - **Contents:** Read and write - **Deployments:** Read and write - **Metadata:** Read-only -- **Pull Requests:** Read and write - - - -Select the following webhook events: - -- Installation -- Installation Target -- Create -- Delete -- Public -- Pull Request -- Push -- Repository +- **Pull requests:** Read and write - -## Step 3: generate and secure credentials - - -Click **Create GitHub App**. - -GitHub redirects you to the app's settings page. - +Click **Create GitHub App**. Only an owner of the organization can complete this step. - -1. Scroll down to the **Private keys** section. -2. Click **Generate a private key**. -3. Download the `.pem` file and securely store it. - - - -Record the following: - -- **App ID** (visible at the top of the settings page) -- **Client ID** (in the "About" section) -- **Client Secret** (generate and record it securely) +GitHub generates the app's private key, client secret, and webhook secret and sends them directly to Mintlify, where they are encrypted. You never download or share them. -## Step 4: install the app +## Step 3: install the app - -1. From the app settings page, click **Install App** in the left sidebar. -2. Select your organization from the list. - - - -Select either: + +GitHub sends you to the app's install page. Select either: - **All repositories** (for organization-wide access) - **Only select repositories** (choose specific repositories) - -1. Click **Install**. -2. Record the installation ID from the URL. For example, in `https://your-github-server.com/settings/installations/12345`, the string `12345` is the installation ID. - - - -## Step 5: configure webhook URL - - - -1. Go back to your app's settings page. -2. Scroll to the **Webhook** section. - +Click **Install**. GitHub returns you to the Mintlify dashboard, which links the installation to your deployment. - -Configure the following: - -- **Webhook URL:** `https://leaves.mintlify.com/github-enterprise/:subdomain` (replace `:subdomain` with the URL that we provide you with) -- **Webhook secret:** Generate a random string (32+ characters) and record it securely. Mintlify can also generate this and provide it to you. +When setup finishes, the **GitHub Enterprise** section shows your organization, the app, the installation, and the webhook URL. -## Share credentials with us -Share the following information with our team using your secure information transfer method of choice. - -### Required credentials -- GitHub Enterprise Server base URL: https://your-github-server.com -- App ID: (from step 3) -- App client ID: (from step 3) -- App client secret: (from step 3) -- Installation ID: (from step 4) -- Installation owner: The name of the GitHub organization that owns the app installation -- Private key: The entire contents of the `.pem` file (share it via secure file transfer) -- Webhook secret: (from step 5) - -### Optional credentials for troubleshooting -- Repository names: Specific repositories where you installed the app -- GitHub Enterprise Server version: Found in your site admin dashboard - -## Mintlify connection -We take the credentials you provide us and store them, encrypted, in a secure location. Then we work with you to either: - -- Integrate your GHES environment with an existing Mintlify project. -- Integrate your GHES environment with a new Mintlify project that we provision for you. - -After you integrate your GHES environment with a Mintlify project, you are ready to enable webhooks for your GitHub App. - -The webhook URL may change based on our configuration. We test the integration and provide you with the new URL. + The webhook URL includes your deployment's subdomain. If your subdomain changes, update the webhook URL in your GitHub App settings or reconnect from the dashboard. +To replace the app or its credentials, click **Reconnect** in the **GitHub Enterprise** section and repeat these steps. + ## Test the integration @@ -207,15 +126,14 @@ The webhook URL may change based on our configuration. We test the integration a Ensure you have: -- Site admin privileges for app creation. -- Organization owner or admin rights for app installation. +- Owner access to the GitHub organization for app creation and installation. - Proper repository permissions if installing on specific repositories. - Verify the webhook URL is correct and accessible. - Ensure your firewall allows outbound HTTPS connections. -- Check the webhook secret matches what you configured. +- If you changed the webhook secret on GitHub, click **Reconnect** in the **GitHub Enterprise** section of your Git settings. - Review webhook delivery logs in the "Advanced" tab of your GitHub App settings.