> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Enterprise Server

> Install and configure the Mintlify GitHub App on your GitHub Enterprise Server instance for automated documentation deployments and syncing.

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](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/enterprise-server@3.18/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 recommend 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](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.
    3. Check "Recent Deliveries" for successful webhook deliveries.
    4. 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 needs to be re-approved by organization owners.
    * Notify us of any permission changes so we can advise on any additional steps that may be required.
  </Accordion>

  <Accordion title="Our GHES is behind a corporate firewall, nginx proxy, or similar setup.">
    You must:

    * Add our service domains to your firewall allowlist.
    * 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:support@mintlify.com">[support@mintlify.com](mailto:support@mintlify.com)</a> with:

    * Your GitHub Enterprise Server version.
    * Specific error messages.
    * Screenshots of any issues.
    * Network/firewall configuration details (if relevant).
  </Accordion>
</AccordionGroup>


## Related topics

- [GitHub](/docs/deploy/github.md)
- [GitLab](/docs/deploy/gitlab.md)
- [Cloudflare](/docs/deploy/cloudflare.md)