Skip to main content
Mintlify

Search documentation

Type to search this documentation.

On this pageOverview

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 page for setup instructions.

Prerequisites

Section titled “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 below)

Network requirements

Section titled “Network requirements”

The integration requires traffic in both directions between your GHES instance and Mintlify. Configure your firewall to allow both of the following connections.

Outbound: your GHES instance to Mintlify

Section titled “Outbound: your GHES instance to Mintlify”

Your GHES instance delivers webhook events to Mintlify over HTTPS (port 443) at leaves.mintlify.com.

  • Allow outbound HTTPS (port 443) to leaves.mintlify.com. Allow this traffic by hostname. Mintlify does not publish a static IP address list for this endpoint, and its underlying IP addresses can change.
  • Ensure your GHES instance can resolve leaves.mintlify.com through DNS. If your servers use an internal DNS resolver, confirm that it resolves public hostnames.

Inbound: Mintlify to your GHES instance

Section titled “Inbound: Mintlify to your GHES instance”

Mintlify connects to your GHES instance over HTTPS (port 443) to call the GitHub API, report check run and deployment statuses, and read repository content. These connections originate from Mintlify's static egress IP address: 54.242.90.151.

If a firewall or IP allowlist restricts access to your GHES instance, allow inbound HTTPS (port 443) from 54.242.90.151.

Step 1: register the GitHub App

Section titled “Step 1: register the GitHub App”

See Registering a GitHub App in the GitHub documentation for detailed instructions.

  1. 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.

  2. Create a new GitHub App

    1. In the left sidebar, click Developer settings.
    2. Click GitHub Apps.
    3. Click New GitHub App.

  3. 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 2: configure app permissions

Section titled “Step 2: configure app permissions”

  1. Set repository permissions

    Set the following permissions for the app. The app needs no Organization, Account, or Enterprise permissions:

    • Checks: Read and write
    • Contents: Read and write
    • Deployments: Read and write
    • Metadata: Read-only
    • Pull Requests: Read and write

  2. Subscribe to events

    Select the following webhook events:

    • Installation
    • Installation Target
    • Create
    • Delete
    • Public
    • Pull Request
    • Push
    • Repository

Step 3: generate and secure credentials

Section titled “Step 3: generate and secure credentials”

  1. Create the app

    Click Create GitHub App.

    GitHub redirects you to the app's settings page.

  2. 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.

  3. 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 4: install the app

Section titled “Step 4: install the app”

  1. Navigate to app installation

    1. From the app settings page, click Install App in the left sidebar.
    2. Select your organization from the list.

  2. Choose installation scope

    Select either:

    • All repositories (for organization-wide access)
    • Only select repositories (choose specific repositories)

  3. 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 5: configure webhook URL

Section titled “Step 5: configure webhook URL”

  1. Return to app settings

    1. Go back to your app's settings page.
    2. Scroll to the Webhook section.

  2. 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.

Share credentials with us

Section titled “Share credentials with us”

Share the following information with our team using your secure information transfer method of choice.

Required credentials

Section titled “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

Section titled “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

Section titled “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.

Test the integration

Section titled “Test the integration”

  1. 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.

  2. Test repository access

    1. Create a test issue or pull request in an installed repository.
    2. Verify that Mintlify responds appropriately.

FAQ and troubleshooting

Section titled “FAQ and troubleshooting”
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.
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 you configured.
  • Review webhook delivery logs in the "Advanced" tab of your GitHub App settings.
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.

The app installs, but doesn't respond to events.
  • Ensure our server receives and acknowledges webhooks with response code 200.
  • You granted the required permissions during installation.
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.

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 you may need.
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.
Can this work with GHES in air-gapped environments?

No, your GHES must be able to communicate with our cloud-hosted server.

Who should I contact if I need help?

Reach out to your customer success representative at Mintlify, or contact our support team at [support@mintlify.com](mailto:support@mintlify.com) with:

  • Your GitHub Enterprise Server version.
  • Specific error messages.
  • Screenshots of any issues.
  • Network/firewall configuration details (if relevant).
Section titled “Related topics”
Suggest an edit

Propose a replacement for this page. The site team reviews it before applying any changes.

Export
Documentation menu