Skip to content

Commit 7ce7326

Browse files
ethanpalmethanpalm
authored
Add GHES setup guide (#1830)
* create new page * add content * intro and prereqs * add headings * turn FAQs into accordiongroup * add Steps components * copyedit * add to nav
1 parent 7c420a0 commit 7ce7326

File tree

2 files changed

+259
-0
lines changed

2 files changed

+259
-0
lines changed

‎deploy/ghes.mdx‎

Lines changed: 258 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,258 @@
1+
---
2+
title: "GitHub Enterprise Server"
3+
description: "Set up the GitHub App on your GitHub Enterprise Server installation."
4+
keywords: ["GitHub Enterprise Server", "GHES", "GitHub Enterprise"]
5+
---
6+
7+
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.
8+
9+
If you use a cloud-hosted GitHub instance, see the [GitHub](/deploy/github) page for setup instructions.
10+
11+
## Prerequisites
12+
13+
- Admin privileges on your GitHub Enterprise Server organization where you want to install the app
14+
- Access to your organization's repositories where you want to install the app
15+
- Network connectivity to communicate with our external services (see [Network requirements](#network-requirements) section below)
16+
17+
### Network requirements
18+
19+
#### Outbound connectivity
20+
21+
Your GitHub Enterprise Server must be able to reach:
22+
- Mintlify's API endpoints (https://leaves.mintlify.com)
23+
- Webhook receivers (port 443)
24+
25+
#### Firewall configuration
26+
27+
The following outbound connections must be allowed:
28+
- Connections from Mintlify's static IP: `54.242.90.151`
29+
- HTTPS (port 443) to Mintlify's service domains
30+
- DNS resolution for Mintlify's service domains
31+
32+
## Step 1: Register the GitHub App
33+
34+
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.
35+
36+
<Steps>
37+
<Step title="Navigate to your organization settings">
38+
1. In the upper-right corner of any page on GitHub, click your profile picture.
39+
2.Click **Your organizations**.
40+
3. Click **Settings** next to the organization that you want to create the app for.
41+
</Step>
42+
43+
<Step title="Create a new GitHub App">
44+
1. In the left sidebar, click **Developer settings**.
45+
2. Click **GitHub Apps**.
46+
3. Click **New GitHub App**.
47+
</Step>
48+
49+
<Step title="Configure basic app information">
50+
Set the following:
51+
52+
- **GitHub App name:** `Mintlify`
53+
- **Description:** `Integration with Mintlify services`
54+
- **Homepage URL:** `https://mintlify.com`
55+
- **User authorization callback URL:** `https://your-github-server.com/` (replace with your actual GHES domain)
56+
57+
</Step>
58+
</Steps>
59+
60+
## Step 2: Configure app permissions
61+
62+
<Steps>
63+
<Step title="Set repository permissions">
64+
Set the following permissions for the app. No Organization, Account, or Enterprise permissions are required:
65+
66+
- **Checks:** Read and write
67+
- **Contents:** Read and write
68+
- **Deployments:** Read and write
69+
- **Metadata:** Read-only
70+
- **Pull Requests:** Read and write
71+
</Step>
72+
73+
<Step title="Subscribe to Events">
74+
Select the following webhook events:
75+
76+
- Installation
77+
- Installation Target
78+
- Create
79+
- Delete
80+
- Public
81+
- Pull Request
82+
- Push
83+
- Repository
84+
</Step>
85+
</Steps>
86+
87+
## Step 3: Generate and secure credentials
88+
89+
<Steps>
90+
<Step title="Create the app">
91+
Click **Create GitHub App**.
92+
93+
You'll be redirected to the app's settings page.
94+
</Step>
95+
96+
<Step title="Generate private key">
97+
1. Scroll down to the **Private keys** section.
98+
2. Click **Generate a private key**.
99+
3. Download the `.pem` file and securely store it.
100+
</Step>
101+
102+
<Step title="Note app credentials">
103+
Record the following:
104+
105+
- **App ID** (visible at the top of the settings page)
106+
- **Client ID** (in the "About" section)
107+
- **Client Secret** (generate and record it securely)
108+
</Step>
109+
</Steps>
110+
111+
## Step 4: Install the app
112+
113+
<Steps>
114+
<Step title="Navigate to app installation">
115+
1. From the app settings page, click **Install App** in the left sidebar.
116+
2. Select your organization from the list.
117+
</Step>
118+
119+
<Step title="Choose installation scope">
120+
Select either:
121+
122+
- **All repositories** (for organization-wide access)
123+
- **Only select repositories** (choose specific repositories)
124+
125+
<Tip>
126+
We reccomend selecting "Only select repositories" and limiting the app to only the repositories where your documentation is located.
127+
</Tip>
128+
</Step>
129+
130+
<Step title="Complete the installation">
131+
1. Click **Install**.
132+
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.
133+
</Step>
134+
</Steps>
135+
136+
## Step 5: Configure webhook URL
137+
138+
<Steps>
139+
<Step title="Return to app settings">
140+
1. Go back to your app's settings page.
141+
2. Scroll to the **Webhook** section.
142+
</Step>
143+
144+
<Step title="Set webhook URL">
145+
Configure the following:
146+
147+
- **Webhook URL:** `https://leaves.mintlify.com/github-enterprise/:subdomain` (replace `:subdomain` with the URL that we provide you with)
148+
- **Webhook secret:** Generate a random string (32+ characters) and record it securely. Mintlify can also generate this and provide it to you.
149+
</Step>
150+
</Steps>
151+
152+
## Share credentials with us
153+
Please share the following information with our team using your secure information transfer method of choice.
154+
155+
### Required credentials
156+
- GitHub Enterprise Server base URL: https://your-github-server.com
157+
- App ID: (from step 3)
158+
- App client ID: (from step 3)
159+
- App client secret: (from step 3)
160+
- Installation ID: (from step 4)
161+
- Private key: The entire contents of the `.pem` file (should be shared via secure file transfer)
162+
- Webhook secret: (from step 5)
163+
164+
### Optional credentials for troubleshooting
165+
- Organization name: Your GitHub organization name
166+
- Repository names: Specific repositories where the app is installed
167+
- GitHub Enterprise Server version: Found in your site admin dashboard
168+
169+
## Mintlify connection
170+
We take the credentials you provide us and store them, encrypted, in a secure location. Then we work with you to either:
171+
172+
- Integrate your GHES environment with an existing Mintlify deployment.
173+
- Integrate your GHES environment with a new Mintlify deployment that we provision for you.
174+
175+
After your GHES environment is integrated with a Mintlify deployment, you are ready to enable webhooks for your GitHub App.
176+
177+
<Note>
178+
The webhook URL may change based on our configuration. We test the integration and provide you with the new URL.
179+
</Note>
180+
181+
## Test the integration
182+
183+
<Steps>
184+
<Step title="Verify webhook delivery">
185+
1. Go to your GitHub App settings.
186+
2. Click the **Advanced** tab.
187+
2. Check "Recent Deliveries" for successful webhook deliveries.
188+
3. Look for HTTP 200 responses.
189+
</Step>
190+
191+
<Step title="Test repository access">
192+
1. Create a test issue or pull request in an installed repository.
193+
2. Verify that Mintlify responds appropriately.
194+
</Step>
195+
</Steps>
196+
197+
## FAQ and Troubleshooting
198+
199+
<AccordionGroup>
200+
<Accordion title="The app installation is failing with permission errors.">
201+
Ensure you have:
202+
203+
- Site admin privileges for app creation
204+
- Organization owner or admin rights for app installation.
205+
- Proper repository permissions if installing on specific repositories.
206+
</Accordion>
207+
208+
<Accordion title="Webhooks aren't being delivered">
209+
- Verify the webhook URL is correct and accessible.
210+
- Ensure your firewall allows outbound HTTPS connections.
211+
- Check the webhook secret matches what was configured.
212+
- Review webhook delivery logs in the "Advanced" tab of your GitHub App settings.
213+
</Accordion>
214+
215+
<Accordion title="I'm getting SSL/TLS certificate errors">
216+
Your GHES might use self-signed certificates. Our services cannot verify your server's certificate.
217+
218+
**Solution:** Ensure your GHES has a valid SSL certificate.
219+
</Accordion>
220+
221+
<Accordion title="The app installs, but doesn't respond to events.">
222+
- Ensure webhooks are being delivered and acknowledged by our server with response code 200.
223+
- Required permissions were granted during installation.
224+
</Accordion>
225+
226+
<Accordion title="Can I limit which repositories the app accesses?">
227+
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.
228+
</Accordion>
229+
230+
<Accordion title="How do I update app permissions later?">
231+
- Go to the app settings as a site admin.
232+
- Modify permissions as needed.
233+
- The app will need to be re-approved by organization owners.
234+
- Notify us of any permission changes as they may affect functionality.
235+
</Accordion>
236+
237+
<Accordion title="Our GHES is behind a corporate firewall, nginx proxy, or similar setup.">
238+
You must:
239+
240+
- Whitelist our service domains in your firewall.
241+
- Ensure outbound HTTPS (port 443) connectivity.
242+
- If direct internet access is not allowed, set up a proxy.
243+
</Accordion>
244+
245+
<Accordion title="Can this work with GHES in air-gapped environments?">
246+
No, your GHES must be able to communicate with our cloud-hosted server.
247+
</Accordion>
248+
249+
<Accordion title="Who should I contact if I need help?">
250+
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:
251+
252+
- Your GitHub Enterprise Server version.
253+
- Specific error messages.
254+
- Screenshots of any issues.
255+
- Network/firewall configuration details (if relevant).
256+
</Accordion>
257+
</AccordionGroup>
258+

‎docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -138,6 +138,7 @@
138138
"deploy/monorepo",
139139
"deploy/ci",
140140
"deploy/github",
141+
"deploy/ghes",
141142
"deploy/gitlab"
142143
]
143144
},

0 commit comments

Comments
 (0)