Add GHES setup guide

deploy/ghes.mdx

@@ -0,0 +1,258 @@
+---
+title: "GitHub Enterprise Server"
+description: "Set up the GitHub App on your GitHub Enterprise Server installation."
+keywords: ["GitHub Enterprise Server", "GHES", "GitHub Enterprise"]
+---
+
+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](#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
+
+## Step 1: Register the GitHub App
+
+See [Registering a GitHub App](https://docs.github.com/en/[email protected]/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) in the GitHub documentation for detailed instructions.
+
+<Steps>
+<Step title="Navigate to your organization settings">
+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.
+</Step>
+
+<Step title="Create a new GitHub App">
+1. In the left sidebar, click **Developer settings**.
+2. Click **GitHub Apps**.
+3. Click **New GitHub App**.
+</Step>
+
+<Step title="Configure basic app information">
+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/` (replace with your actual GHES domain)
+
+</Step>
+</Steps>
+
+## Step 2: Configure app permissions
+
+<Steps>
+<Step title="Set repository permissions">
+Set the following permissions for the app. No Organization, Account, or Enterprise permissions are required:
+
+- **Checks:** Read and write
+- **Contents:** Read and write
+- **Deployments:** Read and write
+- **Metadata:** Read-only
+- **Pull Requests:** Read and write
+</Step>
+
+<Step title="Subscribe to Events">
+Select the following webhook events:
+
+- Installation
+- Installation Target
+- Create
+- Delete
+- Public
+- Pull Request
+- Push
+- Repository
+</Step>
+</Steps>
+
+## Step 3: Generate and secure credentials
+
+<Steps>
+<Step title="Create the app">
+Click **Create GitHub App**.
+
+You'll be redirected to the app's settings page.
+</Step>
+
+<Step title="Generate private key">
+1. Scroll down to the **Private keys** section.
+2. Click **Generate a private key**.
+3. Download the `.pem` file and securely store it.
+</Step>
+
+<Step title="Note app credentials">
+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)
+</Step>
+</Steps>
+
+## Step 4: Install the app
+
+<Steps>
+<Step title="Navigate to app installation">
+1. From the app settings page, click **Install App** in the left sidebar.
+2. Select your organization from the list.
+</Step>
+
+<Step title="Choose installation scope">
+Select either:
+
+- **All repositories** (for organization-wide access)
+- **Only select repositories** (choose specific repositories)
+
+<Tip>
+We reccomend selecting "Only select repositories" and limiting the app to only the repositories where your documentation is located.
+</Tip>
+</Step>
+
+<Step title="Complete the installation">
+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>
+</Steps>
+
+## Step 5: Configure webhook URL
+
+<Steps>
+<Step title="Return to app settings">
+1. Go back to your app's settings page.
+2. Scroll to the **Webhook** section.
+</Step>
+
+<Step title="Set webhook URL">
+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.
+</Step>
+</Steps>
+
+## 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.
+
+<Note>
+The webhook URL may change based on our configuration. We test the integration and provide you with the new URL.
+</Note>
+
+## Test the integration
+
+<Steps>
+<Step title="Verify webhook delivery">
+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.
+</Step>
+
+<Step title="Test repository access">
+1. Create a test issue or pull request in an installed repository.
+2. Verify that Mintlify responds appropriately.
+</Step>
+</Steps>
+
+## FAQ and Troubleshooting
+
+<AccordionGroup>
+<Accordion title="The app installation is failing with permission errors.">
+Ensure you have:
+
+- Site admin privileges for app creation
+- Organization owner or admin rights for app installation.
+- Proper repository permissions if installing on specific repositories.
+</Accordion>
+
+<Accordion title="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 the "Advanced" tab of your GitHub App settings.
+</Accordion>
+
+<Accordion title="I'm getting SSL/TLS certificate errors">
+Your GHES might use self-signed certificates. Our services cannot verify your server's certificate.
+
+**Solution:** Ensure your GHES has a valid SSL certificate.
+</Accordion>
+
+<Accordion title="The app installs, 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.
+</Accordion>
+
+<Accordion title="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.
+</Accordion>
+
+<Accordion title="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.
+</Accordion>
+
+<Accordion title="Our GHES is behind a corporate firewall, nginx proxy, or similar setup.">
+You must:
+
+- Whitelist our service domains in your firewall.
+- Ensure outbound HTTPS (port 443) connectivity.
+- If direct internet access is not allowed, set up a proxy.
+</Accordion>
+
+<Accordion title="Can this work with GHES in air-gapped environments?">
+No, your GHES must be able to communicate with our cloud-hosted server.
+</Accordion>
+
+<Accordion title="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 <a href="mailto:[email protected]">[email protected]</a> with:
+
+- Your GitHub Enterprise Server version.
+- Specific error messages.
+- Screenshots of any issues.
+- Network/firewall configuration details (if relevant).
+</Accordion>
+</AccordionGroup>
+

docs.json

@@ -138,6 +138,7 @@
                   "deploy/monorepo",
                   "deploy/ci",
                   "deploy/github",
+                  "deploy/ghes",
                   "deploy/gitlab"
                 ]
               },