Skip to content

Rewrite GHES setup around the dashboard GitHub Enterprise flow #8049

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
brandonmcconnell wants to merge 1 commit into
base: main
Choose a base branch
from
+32 −114
Draft

Rewrite GHES setup around the dashboard GitHub Enterprise flow #8049

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
146 changes: 32 additions & 114 deletions deploy/ghes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,15 @@
Connecting a GitHub Enterprise Server instance requires an [Enterprise plan](https://mintlify.com/pricing?ref=ghes).
</Info>

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.
This guide walks you through connecting a GitHub Enterprise Server (GHES) instance to Mintlify. You create a GitHub App owned by your GitHub organization from the Mintlify dashboard, install it, and Mintlify links it to your deployment.

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
- GitHub Enterprise enabled for your Mintlify organization. Contact your customer success representative if you don't see the **GitHub Enterprise** section on the [Git settings](https://app.mintlify.com/settings/project/git-settings) page.
- The admin or editor role in your Mintlify organization.
- Owner access to the GitHub organization that should own the app.
- Network connectivity to communicate with our external services (see [Network requirements](#network-requirements) section below)

### Network requirements
Expand All @@ -39,152 +40,70 @@
[Agent](/agent) runs clone and push from separate sandbox infrastructure that uses dynamic IP addresses by default. If your GHES instance enforces an IP allowlist, see [Fix agent runs blocked by an IP allow list](/help-center/agent-blocked-by-git-provider-ip-allow-list).
</Note>

## 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.
## Step 1: start the setup in your dashboard

<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 title="Open Git settings">
Go to the [Git settings](https://app.mintlify.com/settings/project/git-settings) page and select **GitHub** as your provider.
</Step>

<Step title="Configure basic app information">
Set the following:
<Step title="Enter your GitHub instance">
In the **GitHub Enterprise** section, enter:

- **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)
- **GitHub host:** The URL of your GHES instance, such as `https://github.yourcompany.com`.
- **GitHub organization:** The organization that should own the app.
</Step>

<Step title="Create the app">
Click **Create GitHub App**. Mintlify sends you to GitHub with the app's name, permissions, events, and webhook URL already filled in.
</Step>
</Steps>

## Step 2: configure app permissions
## Step 2: create the app on GitHub

<Steps>
<Step title="Set repository permissions">
Set the following permissions for the app. The app needs no Organization, Account, or Enterprise permissions:
<Step title="Review the app">
GitHub shows the app it is about to create for your organization. You can change the name. Leave the permissions and webhook settings as they are.

The app requests these repository permissions:

- **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
- **Pull requests:** Read and write
</Step>
</Steps>

## Step 3: generate and secure credentials

<Steps>
<Step title="Create the app">
Click **Create GitHub App**.

GitHub redirects you to the app's settings page.
</Step>
Click **Create GitHub App**. Only an owner of the organization can complete this 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)
GitHub generates the app's private key, client secret, and webhook secret and sends them directly to Mintlify, where they are encrypted. You never download or share them.

Check warning on line 80 in deploy/ghes.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

deploy/ghes.mdx#L80 

In general, use active voice instead of passive voice ('are encrypted').
</Step>
</Steps>

## Step 4: install the app
## Step 3: 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="Select installation scope">
Select either:
<Step title="Select repositories">
GitHub sends you to the app's install page. Select either:

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

</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>
Click **Install**. GitHub returns you to the Mintlify dashboard, which links the installation to your deployment.

<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.
When setup finishes, the **GitHub Enterprise** section shows your organization, the app, the installation, and the webhook URL.
</Step>
</Steps>

## Share credentials with us
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)
- 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
- Repository names: Specific repositories where you installed the app
- 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 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.

<Note>
The webhook URL may change based on our configuration. We test the integration and provide you with the new URL.
The webhook URL includes your deployment's subdomain. If your subdomain changes, update the webhook URL in your GitHub App settings or reconnect from the dashboard.
</Note>

To replace the app or its credentials, click **Reconnect** in the **GitHub Enterprise** section and repeat these steps.

## Test the integration

<Steps>
Expand All @@ -207,15 +126,14 @@
<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.
- Owner access to the GitHub organization for app creation and 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 you configured.
- If you changed the webhook secret on GitHub, click **Reconnect** in the **GitHub Enterprise** section of your Git settings.
- Review webhook delivery logs in the "Advanced" tab of your GitHub App settings.
</Accordion>

Expand Down
Loading