mintlify__docs/deploy/ghes.mdx

---
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/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
- 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:support@mintlify.com">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>