You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -10,7 +10,7 @@ If you use a cloud-hosted GitHub instance, see the [GitHub](/deploy/github) page
10
10
11
11
## Prerequisites
12
12
13
-
- Admin privileges on your GitHub Enterprise Server Organization where you want to install the app
13
+
- Admin privileges on your GitHub Enterprise Server organization where you want to install the app
14
14
- Access to your organization's repositories where you want to install the app
15
15
- Network connectivity to communicate with our external services (see [Network requirements](#network-requirements) section below)
16
16
@@ -29,48 +29,45 @@ The following outbound connections must be allowed:
29
29
- HTTPS (port 443) to Mintlify's service domains
30
30
- DNS resolution for Mintlify's service domains
31
31
32
-
## Create the GitHub App
32
+
## Step 1: Register the GitHub App
33
33
34
-
<Steps>
35
-
<Steptitle="Navigate to Site Admin Settings">
36
-
Log into your GitHub Enterprise Server as a site administrator.
37
-
38
-
Go to `https://your-github-server.com/customer-domain/` (replace with your actual domain).
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.
39
35
40
-
Click on **Site admin** in the top navigation.
36
+
<Steps>
37
+
<Steptitle="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
41
</Step>
42
42
43
-
<Steptitle="Access GitHub Apps Management">
44
-
In the left sidebar, click **GitHub Apps**.
45
-
46
-
Click **New GitHub App**.
43
+
<Steptitle="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
47
</Step>
48
48
49
-
<Steptitle="Configure Basic App Information">
49
+
<Steptitle="Configure basic app information">
50
50
Set the following:
51
51
52
-
-**GitHub App name:** Mintlify
53
-
-**Description:** Integration with Mintlify services
-**Only select repositories** (choose specific repositories)
132
124
133
125
<Tip>
134
-
Selecting "Only select repositories" is the recommended option.
126
+
We reccomend selecting "Only select repositories" and limiting the app to only the repositories where your documentation is located.
135
127
</Tip>
136
128
</Step>
137
129
138
-
<Steptitle="Complete Installation">
139
-
Click **Install**.
140
-
141
-
Note the Installation ID from the URL (e.g., `https://your-github-server.com/settings/installations/12345` - the number `12345` is your Installation ID).
130
+
<Steptitle="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.
142
133
</Step>
143
134
</Steps>
144
135
145
-
## Configure Webhook URL
136
+
## Step 5: Configure webhook URL
146
137
147
138
<Steps>
148
-
<Steptitle="Return to App Settings">
149
-
Go back to your app's settings page.
150
-
151
-
Scroll to **Webhook** section.
139
+
<Steptitle="Return to app settings">
140
+
1. Go back to your app's settings page.
141
+
2. Scroll to the **Webhook** section.
152
142
</Step>
153
143
154
-
<Steptitle="Set Webhook URL">
144
+
<Steptitle="Set webhook URL">
155
145
Configure the following:
156
146
157
-
-**Webhook URL:**`https://leaves.mintlify.com/github-enterprise/:subdomain` (we'll provide the exact URL)
147
+
-**Webhook URL:**`https://leaves.mintlify.com/github-enterprise/:subdomain` (replace `:subdomain` with the URL that we provide you with)
158
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.
159
176
160
177
<Note>
161
-
This can be left inactive until Mintlify completes their side of the setup process.
178
+
The webhook URL may change based on our configuration. We test the integration and provide you with the new URL.
162
179
</Note>
180
+
181
+
## Test the integration
182
+
183
+
<Steps>
184
+
<Steptitle="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.
163
189
</Step>
164
-
</Steps>
165
190
166
-
##Credentials to Share with Us
167
-
Please share the following information with our team using your secure information transfer method of choice:
168
-
### Required Credentials
169
-
GitHub Enterprise Server base URL: https://your-github-server.com
170
-
App ID: (from Step 3)
171
-
App Client ID: (from Step 3)
172
-
App Client Secret: (from Step 3)
173
-
Installation ID: (from Step 4)
174
-
Private Key: The entire contents of the .pem file (should be shared via secure file transfer)
175
-
Webhook Secret: (from Step 5)
176
-
### Optional Information (Helpful for Troubleshooting)
177
-
Organization Name: Your GitHub organization name
178
-
Repository Names: Specific repositories where the app is installed
179
-
GitHub Enterprise Server Version: (found in site admin dashboard)
180
-
181
-
## Our Work
182
-
We will take the credentials you’ve provided us and store them, encrypted, in a secure location. From there, we will work with you to either
183
-
184
-
Integrate your GRES environment with an existing Mintlify deployment
185
-
Integrate your GRES environment with a new Mintlify deployment we provision for you
186
-
187
-
After that, you should be able to enable Webhooks for your GitHub App - the Webhook URL may change based on our configuration, and we can test integration.
188
-
189
-
## Testing the Integration
190
-
Verify Webhook Delivery
191
-
Go to your app settings → "Advanced" tab
192
-
Check "Recent Deliveries" for successful webhook deliveries
193
-
Look for HTTP 200 responses
194
-
Test Repository Access
195
-
Create a test issue or pull request in an installed repository
196
-
Verify that our service responds appropriately
191
+
<Steptitle="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>
197
196
198
197
## FAQ and Troubleshooting
199
198
200
199
<AccordionGroup>
201
-
<Accordiontitle="The app installation is failing with permission errors">
200
+
<Accordiontitle="The app installation is failing with permission errors.">
202
201
Ensure you have:
203
202
204
203
- Site admin privileges for app creation
205
-
- Organization owner/admin rights for app installation
206
-
- Proper repository permissions if installing on specific repositories
204
+
- Organization owner or admin rights for app installation.
205
+
- Proper repository permissions if installing on specific repositories.
207
206
</Accordion>
208
207
209
208
<Accordiontitle="Webhooks aren't being delivered">
210
-
- Verify the webhook URL is correct and accessible
211
-
- Ensure your firewall allows outbound HTTPS connections
212
-
- Check the webhook secret matches what was configured
Your GRES might use self-signed certificates. Our services cannot verify your server's certificate.
216
+
Your GHES might use self-signed certificates. Our services cannot verify your server's certificate.
218
217
219
-
**Solution:** Ensure your GRES has a valid SSL certificate.
218
+
**Solution:** Ensure your GHES has a valid SSL certificate.
220
219
</Accordion>
221
220
222
-
<Accordiontitle="The app seems to install but doesn't respond to events">
223
-
- Ensure webhooks are being delivered and acknowledged by our server with response code 200
224
-
- Required permissions were granted during installation
225
-
- Ask the Mintlify team if the application is having trouble writing status updates to the GRES (checks, deployments, etc.)
221
+
<Accordiontitle="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.
226
224
</Accordion>
227
225
228
226
<Accordiontitle="Can I limit which repositories the app accesses?">
229
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.
230
228
</Accordion>
231
229
232
230
<Accordiontitle="How do I update app permissions later?">
233
-
- Go to the app settings as a site admin
234
-
- Modify permissions as needed
235
-
- The app will need to be re-approved by organization owners
236
-
- Notify us of any permission changes as they may affect functionality
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.
237
235
</Accordion>
238
236
239
-
<Accordiontitle="Our GRES is behind a corporate firewall/nginx proxy/etc.">
240
-
You'll need to:
237
+
<Accordiontitle="Our GHES is behind a corporate firewall, nginx proxy, or similar setup.">
238
+
You must:
241
239
242
-
- Whitelist our service domains in your firewall
243
-
- Ensure outbound HTTPS (port 443) connectivity
244
-
-Consider setting up a proxy if direct internet access isn't allowed
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.
245
243
</Accordion>
246
244
247
-
<Accordiontitle="Can this work with GRES in air-gapped environments?">
248
-
No, your GRES must be able to communicate with our cloud-hosted server.
245
+
<Accordiontitle="Can this work with GHES in air-gapped environments?">
246
+
No, your GHES must be able to communicate with our cloud-hosted server.
249
247
</Accordion>
250
248
251
249
<Accordiontitle="Who should I contact if I need help?">
252
-
Please reach out to your customer success representative who you've spoken to at Mintlify, or our support team at [email protected] with:
250
+
Please reach out to your customer success representative who you've spoken to at Mintlify, or our support team at <ahref="mailto:[email protected]">[email protected]</a> with:
0 commit comments