From 2f27a3cd2ea5b17a07bab27b85c37048cd23aeba Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 21 Nov 2025 10:55:13 -0800 Subject: [PATCH 1/8] create new page --- deploy/ghes.mdx | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 deploy/ghes.mdx diff --git a/deploy/ghes.mdx b/deploy/ghes.mdx new file mode 100644 index 000000000..39d38eb20 --- /dev/null +++ b/deploy/ghes.mdx @@ -0,0 +1,6 @@ +--- +title: "GitHub Enterprise Server" +description: "Set up the GitHub App on your GitHub Enterprise Server installation." +keywords: ["GitHub Enterprise Server", "GHES", "GitHub Enterprise"] +--- + From d169e0184776fe3bcae1229164f2ca1201dd6b01 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 21 Nov 2025 11:03:03 -0800 Subject: [PATCH 2/8] add content --- deploy/ghes.mdx | 147 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 147 insertions(+) diff --git a/deploy/ghes.mdx b/deploy/ghes.mdx index 39d38eb20..aadc2c105 100644 --- a/deploy/ghes.mdx +++ b/deploy/ghes.mdx @@ -4,3 +4,150 @@ description: "Set up the GitHub App on your GitHub Enterprise Server installatio keywords: ["GitHub Enterprise Server", "GHES", "GitHub Enterprise"] --- +This document will guide you through setting up our GitHub App on your GitHub Enterprise Server (GRES) installation. Please see the cloud-hosted guide here, and see details about the cloud-hosted application here. This process creates a local version of our app within your self-hosted environment that will communicate with our remote server. If you encounter any issues with this guide, please do not hesitate to contact your Mintlify representative. +Prerequisites +Before beginning, ensure you have: +Site Admin privileges on your GitHub Enterprise Server Organization where you’d like to install the application +Access to your organization's repositories where you want to install the app +Network connectivity to communicate with our external services (see Network Requirements section) +Step 1: Create the GitHub App +Navigate to Site Admin Settings +Log into your GitHub Enterprise Server as a site administrator +Go to https://your-github-server.com/customer-domain/ (replace with your actual domain) +Click on "Site admin" in the top navigation +Access GitHub Apps Management +In the left sidebar, click "GitHub Apps" +Click "New GitHub App" +Configure Basic App Information +GitHub App name: Mintlify +Description: Integration with Mintlify services +Homepage URL: https://mintlify.com +User authorization callback URL: https://your-github-server.com/ (your GRES domain) +We won’t be using this for the manual configuration +Step 2: Configure App Permissions +Set the following permissions for the app. No Organization, Account, or Enterprise Permissions are required: +Repository Permissions +Checks: Read & Write +Contents: Read & Write +Deployments: Read & Write +Metadata: Read-only +Pull Requests: Read & Write +Subscribe to Events +Select the following webhook events: +Installation Target +Create +Delete +Public +Pull Request +Push +Repository +Step 3: Generate and Secure Credentials +Create the App +Click "Create GitHub App" +You'll be redirected to the app's settings page +Generate Private Key +Scroll down to "Private keys" section +Click "Generate a private key" +IMPORTANT: Download and securely store this .pem file +Note App Credentials +Record the App ID (visible at the top of the settings page) +Record the Client ID (in the "About" section) +Generate a Client Secret and record it securely +Step 4: Install the App +Navigate to App Installation +From the app settings page, click "Install App" in the left sidebar +Select your organization from the list +Choose Installation Scope +Select either: +All repositories (for organization-wide access) +Only select repositories (choose specific repositories) +This is the recommended option +Complete Installation +Click "Install" +Note the Installation ID from the URL (e.g., https://your-github-server.com/settings/installations/12345 - the number 12345 is your Installation ID) +Step 5: Configure Webhook URL +Return to App Settings +Go back to your app's settings page +Scroll to "Webhook" section +Set Webhook URL +Webhook URL: https://leaves.mintlify.com/github-enterprise/:subdomain (we'll provide the exact URL) +Webhook secret: Generate a random string (32+ characters) and record it securely. Mintlify can also generate this and provide it to you. +This can be left inactive until Mintlify completes their side of the setup process. +Credentials to Share with Us +Please 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) +Private Key: The entire contents of the .pem file (should be shared via secure file transfer) +Webhook Secret: (from Step 5) +Optional Information (Helpful for Troubleshooting) +Organization Name: Your GitHub organization name +Repository Names: Specific repositories where the app is installed +GitHub Enterprise Server Version: (found in site admin dashboard) +Our Work +We will take the credentials you’ve provided us and store them, encrypted, in a secure location. From there, we will work with you to either + +Integrate your GRES environment with an existing Mintlify deployment +Integrate your GRES environment with a new Mintlify deployment we provision for you + +After that, you should be able to enable Webhooks for your GitHub App - the Webhook URL may change based on our configuration, and we can test integration. +Network Requirements +Outbound Connectivity +Your GitHub Enterprise Server must be able to reach: +Our API endpoints: https://leaves.mintlify.com and webhook receivers (port 443) +Firewall Configuration +Ensure the following outbound connections are allowed: +Connections from Mintlify’s static IP: 54.242.90.151 +HTTPS (port 443) to our service domains +DNS resolution for our service domains +Testing the Integration +Verify Webhook Delivery +Go to your app settings → "Advanced" tab +Check "Recent Deliveries" for successful webhook deliveries +Look for HTTP 200 responses +Test Repository Access +Create a test issue or pull request in an installed repository +Verify that our service responds appropriately +FAQ and Troubleshooting +Q: The app installation is failing with permission errors +A: Ensure you have: +Site admin privileges for app creation +Organization owner/admin rights for app installation +Proper repository permissions if installing on specific repositories +Q: Webhooks aren't being delivered +Verify the webhook URL is correct and accessible +Ensure your firewall allows outbound HTTPS connections +Check the webhook secret matches what was configured +Review webhook delivery logs in GitHub App settings → Advanced tab +Q: I'm getting SSL/TLS certificate errors +Your GRES might use self-signed certificates +Our services cannot verify your server's certificate +Solution: Ensure your GRES has a valid SSL certificate +Q: The app seems to install but doesn't respond to events +Ensure webhooks are being delivered and acknowledged by our server with response code 200 +Required permissions were granted during installation +Ask the Mintlify team if the application is having trouble writing status updates to the GRES (checks, deployments, etc.) +Q: Can I limit which repositories the app accesses? +Yes, during installation you can select "Only select repositories" and choose specific ones. You can modify this later in your organization's installed apps settings. This is the recommended form of installation. +Q: How do I update app permissions later? +Go to the app settings as a site admin +Modify permissions as needed +The app will need to be re-approved by organization owners +Notify us of any permission changes as they may affect functionality +Q: Our GRES is behind a corporate firewall/nginx proxy/etc. +You'll need to: +Whitelist our service domains in your firewall +Ensure outbound HTTPS (port 443) connectivity +Consider setting up a proxy if direct internet access isn't allowed +Q: Can this work with GRES in air-gapped environments? +No, your GRES must be able to communicate with our cloud-hosted server +Q: Who should I contact if I need help? +Please reach out to your customer success representative who you’ve spoken to at Mintlify, or our support team at support@mintlify.com with: +Your GitHub Enterprise Server version +Specific error messages +Screenshots of any issues +Network/firewall configuration details (if relevant) + From 7353a2252079d00f2d2935da98fe94018346c14d Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 21 Nov 2025 11:11:29 -0800 Subject: [PATCH 3/8] intro and prereqs --- deploy/ghes.mdx | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/deploy/ghes.mdx b/deploy/ghes.mdx index aadc2c105..7238eea1c 100644 --- a/deploy/ghes.mdx +++ b/deploy/ghes.mdx @@ -4,12 +4,21 @@ description: "Set up the GitHub App on your GitHub Enterprise Server installatio keywords: ["GitHub Enterprise Server", "GHES", "GitHub Enterprise"] --- -This document will guide you through setting up our GitHub App on your GitHub Enterprise Server (GRES) installation. Please see the cloud-hosted guide here, and see details about the cloud-hosted application here. This process creates a local version of our app within your self-hosted environment that will communicate with our remote server. If you encounter any issues with this guide, please do not hesitate to contact your Mintlify representative. -Prerequisites -Before beginning, ensure you have: -Site Admin privileges on your GitHub Enterprise Server Organization where you’d like to install the application -Access to your organization's repositories where you want to install the app -Network connectivity to communicate with our external services (see Network Requirements section) +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. + +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 +- Network connectivity to communicate with our external services (see Network Requirements section) + - Outbound connectivity: Your GitHub Enterprise Server must be able to reach our API endpoints (https://leaves.mintlify.com) and webhook receivers (port 443) + - Firewall configuration for the following outbound connections must be allowed: + - Connections from Mintlify's static IP: `54.242.90.151` + - HTTPS (port 443) to Mintlify's service domains + - DNS resolution for Mintlify's service domains + Step 1: Create the GitHub App Navigate to Site Admin Settings Log into your GitHub Enterprise Server as a site administrator From fb14a9547615bcf9a718b3c6c9436b3f3bf2b53d Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 21 Nov 2025 11:34:29 -0800 Subject: [PATCH 4/8] add headings --- deploy/ghes.mdx | 63 ++++++++++++++++++++++++++++--------------------- 1 file changed, 36 insertions(+), 27 deletions(-) diff --git a/deploy/ghes.mdx b/deploy/ghes.mdx index 7238eea1c..1883b212b 100644 --- a/deploy/ghes.mdx +++ b/deploy/ghes.mdx @@ -12,14 +12,24 @@ If you use a cloud-hosted GitHub instance, see the [GitHub](/deploy/github) page - 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 -- Network connectivity to communicate with our external services (see Network Requirements section) - - Outbound connectivity: Your GitHub Enterprise Server must be able to reach our API endpoints (https://leaves.mintlify.com) and webhook receivers (port 443) - - Firewall configuration for the following outbound connections must be allowed: - - Connections from Mintlify's static IP: `54.242.90.151` - - HTTPS (port 443) to Mintlify's service domains - - DNS resolution for Mintlify's service domains - -Step 1: Create the GitHub App +- Network connectivity to communicate with our external services (see [Network requirements](#network-requirements) section below) + +### Network requirements + +#### Outbound connectivity + +Your GitHub Enterprise Server must be able to reach: +- Mintlify's API endpoints (https://leaves.mintlify.com) +- Webhook receivers (port 443) + +#### Firewall configuration + +The following outbound connections must be allowed: +- Connections from Mintlify's static IP: `54.242.90.151` +- HTTPS (port 443) to Mintlify's service domains +- DNS resolution for Mintlify's service domains + +## Create the GitHub App Navigate to Site Admin Settings Log into your GitHub Enterprise Server as a site administrator Go to https://your-github-server.com/customer-domain/ (replace with your actual domain) @@ -33,7 +43,8 @@ Description: Integration with Mintlify services Homepage URL: https://mintlify.com User authorization callback URL: https://your-github-server.com/ (your GRES domain) We won’t be using this for the manual configuration -Step 2: Configure App Permissions + +## Configure App Permissions Set the following permissions for the app. No Organization, Account, or Enterprise Permissions are required: Repository Permissions Checks: Read & Write @@ -50,7 +61,8 @@ Public Pull Request Push Repository -Step 3: Generate and Secure Credentials + +## Generate and Secure Credentials Create the App Click "Create GitHub App" You'll be redirected to the app's settings page @@ -62,7 +74,8 @@ Note App Credentials Record the App ID (visible at the top of the settings page) Record the Client ID (in the "About" section) Generate a Client Secret and record it securely -Step 4: Install the App + +## Install the App Navigate to App Installation From the app settings page, click "Install App" in the left sidebar Select your organization from the list @@ -74,7 +87,8 @@ This is the recommended option Complete Installation Click "Install" Note the Installation ID from the URL (e.g., https://your-github-server.com/settings/installations/12345 - the number 12345 is your Installation ID) -Step 5: Configure Webhook URL + +## Configure Webhook URL Return to App Settings Go back to your app's settings page Scroll to "Webhook" section @@ -82,9 +96,10 @@ Set Webhook URL Webhook URL: https://leaves.mintlify.com/github-enterprise/:subdomain (we'll provide the exact URL) Webhook secret: Generate a random string (32+ characters) and record it securely. Mintlify can also generate this and provide it to you. This can be left inactive until Mintlify completes their side of the setup process. -Credentials to Share with Us + +##Credentials to Share with Us Please share the following information with our team using your secure information transfer method of choice: -Required Credentials +### Required Credentials GitHub Enterprise Server base URL: https://your-github-server.com App ID: (from Step 3) App Client ID: (from Step 3) @@ -92,27 +107,20 @@ App Client Secret: (from Step 3) Installation ID: (from Step 4) Private Key: The entire contents of the .pem file (should be shared via secure file transfer) Webhook Secret: (from Step 5) -Optional Information (Helpful for Troubleshooting) +### Optional Information (Helpful for Troubleshooting) Organization Name: Your GitHub organization name Repository Names: Specific repositories where the app is installed GitHub Enterprise Server Version: (found in site admin dashboard) -Our Work + +## Our Work We will take the credentials you’ve provided us and store them, encrypted, in a secure location. From there, we will work with you to either Integrate your GRES environment with an existing Mintlify deployment Integrate your GRES environment with a new Mintlify deployment we provision for you After that, you should be able to enable Webhooks for your GitHub App - the Webhook URL may change based on our configuration, and we can test integration. -Network Requirements -Outbound Connectivity -Your GitHub Enterprise Server must be able to reach: -Our API endpoints: https://leaves.mintlify.com and webhook receivers (port 443) -Firewall Configuration -Ensure the following outbound connections are allowed: -Connections from Mintlify’s static IP: 54.242.90.151 -HTTPS (port 443) to our service domains -DNS resolution for our service domains -Testing the Integration + +## Testing the Integration Verify Webhook Delivery Go to your app settings → "Advanced" tab Check "Recent Deliveries" for successful webhook deliveries @@ -120,7 +128,8 @@ Look for HTTP 200 responses Test Repository Access Create a test issue or pull request in an installed repository Verify that our service responds appropriately -FAQ and Troubleshooting + +## FAQ and Troubleshooting Q: The app installation is failing with permission errors A: Ensure you have: Site admin privileges for app creation From 3f1f0490290309259ec5148d3d53a6e11df64730 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 21 Nov 2025 11:34:49 -0800 Subject: [PATCH 5/8] turn FAQs into accordiongroup --- deploy/ghes.mdx | 95 ++++++++++++++++++++++++++++++------------------- 1 file changed, 59 insertions(+), 36 deletions(-) diff --git a/deploy/ghes.mdx b/deploy/ghes.mdx index 1883b212b..3295e17a7 100644 --- a/deploy/ghes.mdx +++ b/deploy/ghes.mdx @@ -130,42 +130,65 @@ Create a test issue or pull request in an installed repository Verify that our service responds appropriately ## FAQ and Troubleshooting -Q: The app installation is failing with permission errors -A: Ensure you have: -Site admin privileges for app creation -Organization owner/admin rights for app installation -Proper repository permissions if installing on specific repositories -Q: Webhooks aren't being delivered -Verify the webhook URL is correct and accessible -Ensure your firewall allows outbound HTTPS connections -Check the webhook secret matches what was configured -Review webhook delivery logs in GitHub App settings → Advanced tab -Q: I'm getting SSL/TLS certificate errors -Your GRES might use self-signed certificates -Our services cannot verify your server's certificate -Solution: Ensure your GRES has a valid SSL certificate -Q: The app seems to install but doesn't respond to events -Ensure webhooks are being delivered and acknowledged by our server with response code 200 -Required permissions were granted during installation -Ask the Mintlify team if the application is having trouble writing status updates to the GRES (checks, deployments, etc.) -Q: Can I limit which repositories the app accesses? + + + +Ensure you have: + +- Site admin privileges for app creation +- Organization owner/admin rights for app 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 was configured +- Review webhook delivery logs in GitHub App settings → Advanced tab + + + +Your GRES might use self-signed certificates. Our services cannot verify your server's certificate. + +**Solution:** Ensure your GRES has a valid SSL certificate. + + + +- Ensure webhooks are being delivered and acknowledged by our server with response code 200 +- Required permissions were granted during installation +- Ask the Mintlify team if the application is having trouble writing status updates to the GRES (checks, deployments, etc.) + + + Yes, during installation you can select "Only select repositories" and choose specific ones. You can modify this later in your organization's installed apps settings. This is the recommended form of installation. -Q: How do I update app permissions later? -Go to the app settings as a site admin -Modify permissions as needed -The app will need to be re-approved by organization owners -Notify us of any permission changes as they may affect functionality -Q: Our GRES is behind a corporate firewall/nginx proxy/etc. + + + +- Go to the app settings as a site admin +- Modify permissions as needed +- The app will need to be re-approved by organization owners +- Notify us of any permission changes as they may affect functionality + + + You'll need to: -Whitelist our service domains in your firewall -Ensure outbound HTTPS (port 443) connectivity -Consider setting up a proxy if direct internet access isn't allowed -Q: Can this work with GRES in air-gapped environments? -No, your GRES must be able to communicate with our cloud-hosted server -Q: Who should I contact if I need help? -Please reach out to your customer success representative who you’ve spoken to at Mintlify, or our support team at support@mintlify.com with: -Your GitHub Enterprise Server version -Specific error messages -Screenshots of any issues -Network/firewall configuration details (if relevant) + +- Whitelist our service domains in your firewall +- Ensure outbound HTTPS (port 443) connectivity +- Consider setting up a proxy if direct internet access isn't allowed + + + +No, your GRES must be able to communicate with our cloud-hosted server. + + + +Please reach out to your customer success representative who you've spoken to at Mintlify, or our support team at support@mintlify.com with: + +- Your GitHub Enterprise Server version +- Specific error messages +- Screenshots of any issues +- Network/firewall configuration details (if relevant) + + From 9158803fee116b4f5600a57b9eacdbc153a52497 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 21 Nov 2025 11:36:34 -0800 Subject: [PATCH 6/8] add Steps components --- deploy/ghes.mdx | 174 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 120 insertions(+), 54 deletions(-) diff --git a/deploy/ghes.mdx b/deploy/ghes.mdx index 3295e17a7..ca37f555a 100644 --- a/deploy/ghes.mdx +++ b/deploy/ghes.mdx @@ -30,72 +30,138 @@ The following outbound connections must be allowed: - DNS resolution for Mintlify's service domains ## Create the GitHub App -Navigate to Site Admin Settings -Log into your GitHub Enterprise Server as a site administrator -Go to https://your-github-server.com/customer-domain/ (replace with your actual domain) -Click on "Site admin" in the top navigation -Access GitHub Apps Management -In the left sidebar, click "GitHub Apps" -Click "New GitHub App" -Configure Basic App Information -GitHub App name: Mintlify -Description: Integration with Mintlify services -Homepage URL: https://mintlify.com -User authorization callback URL: https://your-github-server.com/ (your GRES domain) -We won’t be using this for the manual configuration + + + +Log into your GitHub Enterprise Server as a site administrator. + +Go to `https://your-github-server.com/customer-domain/` (replace with your actual domain). + +Click on **Site admin** in the top navigation. + + + +In the left sidebar, click **GitHub Apps**. + +Click **New GitHub App**. + + + +Set the following: + +- **GitHub App name:** Mintlify +- **Description:** Integration with Mintlify services +- **Homepage URL:** https://mintlify.com +- **User authorization callback URL:** `https://your-github-server.com/` (your GRES domain) + + +We won't be using the user authorization callback URL for the manual configuration. + + + ## Configure App Permissions + + + Set the following permissions for the app. No Organization, Account, or Enterprise Permissions are required: -Repository Permissions -Checks: Read & Write -Contents: Read & Write -Deployments: Read & Write -Metadata: Read-only -Pull Requests: Read & Write -Subscribe to Events + +- **Checks:** Read & Write +- **Contents:** Read & Write +- **Deployments:** Read & Write +- **Metadata:** Read-only +- **Pull Requests:** Read & Write + + + Select the following webhook events: -Installation Target -Create -Delete -Public -Pull Request -Push -Repository + +- Installation +- Installation Target +- Create +- Delete +- Public +- Pull Request +- Push +- Repository + + ## Generate and Secure Credentials -Create the App -Click "Create GitHub App" -You'll be redirected to the app's settings page -Generate Private Key -Scroll down to "Private keys" section -Click "Generate a private key" -IMPORTANT: Download and securely store this .pem file -Note App Credentials -Record the App ID (visible at the top of the settings page) -Record the Client ID (in the "About" section) -Generate a Client Secret and record it securely + + + +Click **Create GitHub App**. + +You'll be redirected to the app's settings page. + + + +Scroll down to **Private keys** section. + +Click **Generate a private key**. + + +Download and securely store this .pem file. + + + + +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) + + ## Install the App -Navigate to App Installation -From the app settings page, click "Install App" in the left sidebar -Select your organization from the list -Choose Installation Scope + + + +From the app settings page, click **Install App** in the left sidebar. + +Select your organization from the list. + + + Select either: -All repositories (for organization-wide access) -Only select repositories (choose specific repositories) -This is the recommended option -Complete Installation -Click "Install" -Note the Installation ID from the URL (e.g., https://your-github-server.com/settings/installations/12345 - the number 12345 is your Installation ID) + +- **All repositories** (for organization-wide access) +- **Only select repositories** (choose specific repositories) + + +Selecting "Only select repositories" is the recommended option. + + + + +Click **Install**. + +Note the Installation ID from the URL (e.g., `https://your-github-server.com/settings/installations/12345` - the number `12345` is your Installation ID). + + ## Configure Webhook URL -Return to App Settings -Go back to your app's settings page -Scroll to "Webhook" section -Set Webhook URL -Webhook URL: https://leaves.mintlify.com/github-enterprise/:subdomain (we'll provide the exact URL) -Webhook secret: Generate a random string (32+ characters) and record it securely. Mintlify can also generate this and provide it to you. + + + +Go back to your app's settings page. + +Scroll to **Webhook** section. + + + +Configure the following: + +- **Webhook URL:** `https://leaves.mintlify.com/github-enterprise/:subdomain` (we'll provide the exact URL) +- **Webhook secret:** Generate a random string (32+ characters) and record it securely. Mintlify can also generate this and provide it to you. + + This can be left inactive until Mintlify completes their side of the setup process. + + + ##Credentials to Share with Us Please share the following information with our team using your secure information transfer method of choice: From 4505da36b74a82ea2a851078fc4e19a9f32ef5ea Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 21 Nov 2025 12:06:30 -0800 Subject: [PATCH 7/8] copyedit --- deploy/ghes.mdx | 234 ++++++++++++++++++++++++------------------------ 1 file changed, 116 insertions(+), 118 deletions(-) diff --git a/deploy/ghes.mdx b/deploy/ghes.mdx index ca37f555a..3ebfa0c9b 100644 --- a/deploy/ghes.mdx +++ b/deploy/ghes.mdx @@ -10,7 +10,7 @@ If you use a cloud-hosted GitHub instance, see the [GitHub](/deploy/github) page ## Prerequisites -- Admin privileges on your GitHub Enterprise Server Organization where you want to install the app +- 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 - Network connectivity to communicate with our external services (see [Network requirements](#network-requirements) section below) @@ -29,48 +29,45 @@ The following outbound connections must be allowed: - HTTPS (port 443) to Mintlify's service domains - DNS resolution for Mintlify's service domains -## Create the GitHub App +## Step 1: Register the GitHub App - - -Log into your GitHub Enterprise Server as a site administrator. - -Go to `https://your-github-server.com/customer-domain/` (replace with your actual domain). +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. -Click on **Site admin** in the top navigation. + + +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. - -In the left sidebar, click **GitHub Apps**. - -Click **New GitHub App**. + +1. In the left sidebar, click **Developer settings**. +2. Click **GitHub Apps**. +3. Click **New GitHub App**. - + Set the following: -- **GitHub App name:** Mintlify -- **Description:** Integration with Mintlify services -- **Homepage URL:** https://mintlify.com -- **User authorization callback URL:** `https://your-github-server.com/` (your GRES domain) +- **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) - -We won't be using the user authorization callback URL for the manual configuration. - -## Configure App Permissions +## Step 2: Configure app permissions - -Set the following permissions for the app. No Organization, Account, or Enterprise Permissions are required: + +Set the following permissions for the app. No Organization, Account, or Enterprise permissions are required: -- **Checks:** Read & Write -- **Contents:** Read & Write -- **Deployments:** Read & Write +- **Checks:** Read and write +- **Contents:** Read and write +- **Deployments:** Read and write - **Metadata:** Read-only -- **Pull Requests:** Read & Write +- **Pull Requests:** Read and write @@ -87,26 +84,22 @@ Select the following webhook events: -## Generate and Secure Credentials +## Step 3: Generate and secure credentials - + Click **Create GitHub App**. You'll be redirected to the app's settings page. - -Scroll down to **Private keys** section. - -Click **Generate a private key**. - - -Download and securely store this .pem file. - + +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) @@ -115,114 +108,119 @@ Record the following: -## Install the App +## Step 4: Install the app - -From the app settings page, click **Install App** in the left sidebar. - -Select your organization from the list. + +1. From the app settings page, click **Install App** in the left sidebar. +2. Select your organization from the list. - + Select either: - **All repositories** (for organization-wide access) - **Only select repositories** (choose specific repositories) -Selecting "Only select repositories" is the recommended option. +We reccomend selecting "Only select repositories" and limiting the app to only the repositories where your documentation is located. - -Click **Install**. - -Note the Installation ID from the URL (e.g., `https://your-github-server.com/settings/installations/12345` - the number `12345` is your Installation ID). + +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. -## Configure Webhook URL +## Step 5: Configure webhook URL - -Go back to your app's settings page. - -Scroll to **Webhook** section. + +1. Go back to your app's settings page. +2. Scroll to the **Webhook** section. - + Configure the following: -- **Webhook URL:** `https://leaves.mintlify.com/github-enterprise/:subdomain` (we'll provide the exact URL) +- **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. + + + +## Share credentials with us +Please 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) +- Private key: The entire contents of the `.pem` file (should be shared via secure file transfer) +- Webhook secret: (from step 5) + +### Optional credentials for troubleshooting +- Organization name: Your GitHub organization name +- Repository names: Specific repositories where the app is installed +- 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 deployment. +- Integrate your GHES environment with a new Mintlify deployment that we provision for you. + +After your GHES environment is integrated with a Mintlify deployment, you are ready to enable webhooks for your GitHub App. -This can be left inactive until Mintlify completes their side of the setup process. +The webhook URL may change based on our configuration. We test the integration and provide you with the new URL. + +## Test the integration + + + +1. Go to your GitHub App settings. +2. Click the **Advanced** tab. +2. Check "Recent Deliveries" for successful webhook deliveries. +3. Look for HTTP 200 responses. - -##Credentials to Share with Us -Please 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) -Private Key: The entire contents of the .pem file (should be shared via secure file transfer) -Webhook Secret: (from Step 5) -### Optional Information (Helpful for Troubleshooting) -Organization Name: Your GitHub organization name -Repository Names: Specific repositories where the app is installed -GitHub Enterprise Server Version: (found in site admin dashboard) - -## Our Work -We will take the credentials you’ve provided us and store them, encrypted, in a secure location. From there, we will work with you to either - -Integrate your GRES environment with an existing Mintlify deployment -Integrate your GRES environment with a new Mintlify deployment we provision for you - -After that, you should be able to enable Webhooks for your GitHub App - the Webhook URL may change based on our configuration, and we can test integration. - -## Testing the Integration -Verify Webhook Delivery -Go to your app settings → "Advanced" tab -Check "Recent Deliveries" for successful webhook deliveries -Look for HTTP 200 responses -Test Repository Access -Create a test issue or pull request in an installed repository -Verify that our service responds appropriately + +1. Create a test issue or pull request in an installed repository. +2. Verify that Mintlify responds appropriately. + + ## FAQ and Troubleshooting - + Ensure you have: - Site admin privileges for app creation -- Organization owner/admin rights for app installation -- Proper repository permissions if installing on specific repositories +- Organization owner or admin rights for app 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 was configured -- Review webhook delivery logs in GitHub App settings → Advanced tab +- Verify the webhook URL is correct and accessible. +- Ensure your firewall allows outbound HTTPS connections. +- Check the webhook secret matches what was configured. +- Review webhook delivery logs in the "Advanced" tab of your GitHub App settings. -Your GRES might use self-signed certificates. Our services cannot verify your server's certificate. +Your GHES might use self-signed certificates. Our services cannot verify your server's certificate. -**Solution:** Ensure your GRES has a valid SSL certificate. +**Solution:** Ensure your GHES has a valid SSL certificate. - -- Ensure webhooks are being delivered and acknowledged by our server with response code 200 -- Required permissions were granted during installation -- Ask the Mintlify team if the application is having trouble writing status updates to the GRES (checks, deployments, etc.) + +- Ensure webhooks are being delivered and acknowledged by our server with response code 200. +- Required permissions were granted during installation. @@ -230,31 +228,31 @@ Yes, during installation you can select "Only select repositories" and choose sp -- Go to the app settings as a site admin -- Modify permissions as needed -- The app will need to be re-approved by organization owners -- Notify us of any permission changes as they may affect functionality +- Go to the app settings as a site admin. +- Modify permissions as needed. +- The app will need to be re-approved by organization owners. +- Notify us of any permission changes as they may affect functionality. - -You'll need to: + +You must: -- Whitelist our service domains in your firewall -- Ensure outbound HTTPS (port 443) connectivity -- Consider setting up a proxy if direct internet access isn't allowed +- Whitelist our service domains in your firewall. +- Ensure outbound HTTPS (port 443) connectivity. +- If direct internet access is not allowed, set up a proxy. - -No, your GRES must be able to communicate with our cloud-hosted server. + +No, your GHES must be able to communicate with our cloud-hosted server. -Please reach out to your customer success representative who you've spoken to at Mintlify, or our support team at support@mintlify.com with: +Please reach out to your customer success representative who you've spoken to at Mintlify, or our support team at support@mintlify.com with: -- Your GitHub Enterprise Server version -- Specific error messages -- Screenshots of any issues -- Network/firewall configuration details (if relevant) +- Your GitHub Enterprise Server version. +- Specific error messages. +- Screenshots of any issues. +- Network/firewall configuration details (if relevant). From 9bec2932f12396b92be11845f07f4e07e87de6da Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 21 Nov 2025 12:06:49 -0800 Subject: [PATCH 8/8] add to nav --- docs.json | 1 + 1 file changed, 1 insertion(+) diff --git a/docs.json b/docs.json index f5154b6f8..878b73519 100644 --- a/docs.json +++ b/docs.json @@ -138,6 +138,7 @@ "deploy/monorepo", "deploy/ci", "deploy/github", + "deploy/ghes", "deploy/gitlab" ] },