Skip to content

Commit aa68a16

Browse files
sriramveeraghantasriramveeraghanta
committed
feat: separate the github and gitlab enterprise
1 parent 98703d7 commit aa68a16

5 files changed

Lines changed: 311 additions & 190 deletions

File tree

‎docs/.vitepress/config.mts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -266,7 +266,15 @@ export default withMermaid(
266266
collapsed: true,
267267
items: [
268268
{ text: "GitHub", link: "/self-hosting/govern/integrations/github" },
269+
{
270+
text: "GitHub Enterprise Server",
271+
link: "/self-hosting/govern/integrations/github-enterprise",
272+
},
269273
{ text: "GitLab", link: "/self-hosting/govern/integrations/gitlab" },
274+
{
275+
text: "GitLab Self-managed",
276+
link: "/self-hosting/govern/integrations/gitlab-self-managed",
277+
},
270278
{ text: "Sentry", link: "/self-hosting/govern/integrations/sentry" },
271279
{ text: "Slack", link: "/self-hosting/govern/integrations/slack" },
272280
],

‎docs/self-hosting/govern/integrations/github-enterprise.md‎

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
---
2+
title: Configure GitHub Enterprise Server for Plane integration
3+
description: Connect GitHub Enterprise Server to your Plane instance. Sync pull requests, commits, and branches with Plane work items for seamless development tracking.
4+
keywords: plane github enterprise integration, github enterprise server, github sync, pull request tracking, commit linking, github app, self-hosting, plane devops
5+
---
6+
7+
# Configure GitHub Enterprise Server for Plane integration <Badge type="info" text="Pro" />
8+
9+
This guide walks you through setting up a GitHub App on your GitHub Enterprise Server instance to enable GitHub integration for your Plane workspace. You'll need to set up the necessary authentication, permissions, and webhooks to ensure smooth integration.
10+
11+
::: info
12+
Looking for **GitHub Cloud**? See [Configure GitHub for Plane integration](/self-hosting/govern/integrations/github).
13+
:::
14+
15+
In this guide, you'll:
16+
17+
1. [Create and configure a GitHub App](/self-hosting/govern/integrations/github-enterprise#create-github-app)
18+
2. [Set up permissions and events](/self-hosting/govern/integrations/github-enterprise#set-up-permissions-and-events)
19+
3. [Configure your Plane instance](/self-hosting/govern/integrations/github-enterprise#configure-plane-instance)
20+
21+
::: warning
22+
**Activate GitHub Enterprise integration**
23+
24+
After creating and configuring the GitHub app and configuring the instance as detailed on this page, you'll need to [setup the GitHub integration](https://docs.plane.so/integrations/github) within Plane.
25+
:::
26+
27+
## Create GitHub App
28+
29+
To configure GitHub Enterprise integration, you'll need to create a GitHub App within your organization.
30+
31+
1. Go to **Settings \> Developer Settings \> GitHub Apps** in your GitHub organization.
32+
33+
2. Click **New GitHub App**.
34+
![Create GitHub App](/images/integrations/github/create-github-app.webp)
35+
36+
3. In the **Register new GitHub App** page, provide a **GitHub App name** and **Homepage URL**.
37+
![App name and homepage URL](/images/integrations/github/app-name-homepage-url.webp)
38+
39+
4. In the **Identifying and authorizing users** section, add the following **Callback URLS**.
40+
41+
**For Plane cloud instance**
42+
43+
```bash
44+
https://silo.plane.so/api/oauth/github-enterprise/auth/callback
45+
https://silo.plane.so/api/oauth/github-enterprise/auth/user/callback
46+
```
47+
48+
**For Plane self-hosted instance**
49+
50+
```bash
51+
https://<your-domain>/silo/api/oauth/github-enterprise/auth/callback
52+
https://<your-domain>/silo/api/oauth/github-enterprise/auth/user/callback
53+
```
54+
55+
These URLs allow Plane to verify and enable workspace connection with the Github App.
56+
![Add Callback URL](/images/integrations/github/add-callback-url.webp)
57+
58+
5. In the **Post installation** section, add the below **Setup URL**.
59+
60+
**For Plane cloud instance**
61+
62+
```bash
63+
https://silo.plane.so/api/oauth/github-enterprise/auth/callback
64+
```
65+
66+
**For Plane self-hosted instance**
67+
68+
```bash
69+
https://<your-plane-domain>/silo/api/oauth/github-enterprise/auth/callback
70+
```
71+
72+
Redirects users to this URL after GitHub app installation.
73+
![Add setup URL](/images/integrations/github/add-setup-url.webp)
74+
75+
6. Turn on **Redirect on update**.
76+
77+
7. In the **Webhook** section, add the below **Webhook URL**.
78+
79+
**For Plane cloud instance**
80+
81+
```bash
82+
https://silo.plane.so/api/github-enterprise/github-webhook
83+
```
84+
85+
**For Plane self-hosted instance**
86+
87+
```bash
88+
https://<your-plane-domain>/silo/api/github-enterprise/github-webhook
89+
```
90+
91+
This allows Plane to receive updates from GitHub repositories.
92+
93+
![Add Webhook URL](/images/integrations/github/add-webhook-url.webp)
94+
95+
### Set up permissions and events
96+
97+
1. Add repository and account permissions by setting the **Access** dropdown next to each permission, as shown in the tables below.
98+
![Setup permissions](/images/integrations/github/setup-permissions.webp)
99+
100+
**Repository permissions**
101+
102+
| Permission&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | Access&nbsp;level&nbsp;&nbsp;&nbsp;&nbsp; | Purpose |
103+
| ---------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------ |
104+
| Issues | Read and write | Enables reading, creating, updating, closing, and commenting on issues within the repository. |
105+
| Metadata | Read-only | Provides read-only access to repository metadata, such as its name, description, and visibility. |
106+
| Pull requests | Read and write | Allows reading, creating, updating, merging, and commenting on pull requests. |
107+
108+
**Account permissions**
109+
110+
| Permission&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | Access&nbsp;level&nbsp;&nbsp;&nbsp;&nbsp; | Purpose |
111+
| ---------------------------------------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------- |
112+
| Email addresses | Read-only | Grants access to users' email addresses, typically for notifications or communication. |
113+
| Profile | Read and write | Enables access to user profile details like name, username, and avatar. |
114+
115+
2. In the **Subscribe to events** section, turn on all the required events below.
116+
117+
![Subscribe to events](/images/integrations/github/subscribe-to-events.webp)
118+
119+
| Event&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | Purpose |
120+
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
121+
| Installation target | This is where the repositories or organizations where your GitHub App is installed. This determines which repositories Plane can sync with. |
122+
| Meta | Includes metadata about the app's configuration and setup. This is essential for maintaining integration stability. |
123+
| Issue comment | Triggers when a comment is added, edited, or deleted on an issue. Useful for keeping comments synced between Plane and GitHub. |
124+
| Issues | Triggers when an issue is created, updated, closed, reopened, assigned, labeled, or transferred. Ensures issue status and details remain consistent between Plane and GitHub. |
125+
| Pull request | Fires when a pull request is opened, closed, merged, edited, or labeled. Essential for tracking development progress. |
126+
| Pull request review | Activates when a review is submitted, edited, or dismissed. Keeps review activities aligned between Plane and GitHub. |
127+
| Pull request review comment | Fires when a review comment is added, modified, or removed. Ensures feedback is reflected across both platforms. |
128+
| Pull request review thread | Triggers when a review discussion thread is resolved or reopened. Helps maintain visibility on code review discussions. |
129+
| Push | Activates when new commits are pushed to a repository. Useful for tracking code updates and changes. |
130+
| Repository sub issues | Tracks issues within a repository that are linked to or managed by another issue. Ensures accurate synchronization of related issues. |
131+
132+
3. Click the **Create GitHub App** button at the bottom of the page.
133+
134+
## Configure Plane instance
135+
136+
1. Go back to **Settings \> Developer Settings \> GitHub Apps**.
137+
138+
2. Click **Edit** on the GitHub you created.
139+
140+
3. In the **General** tab, under the **Client secrets** section, click **Generate a new client secret**.
141+
142+
![General tab](/images/integrations/github/general-tab.webp)
143+
144+
4. Scroll down to the **Private keys** section.
145+
146+
![Private keys](/images/integrations/github/private-keys.webp)
147+
148+
5. Click **Generate a private key**.
149+
150+
6. Retrieve the following details from the **General** tab:
151+
- App ID
152+
- App Slug (You can find this in browser url)
153+
- Client ID
154+
- Client secret
155+
- Private key
156+
157+
7. Convert the Private key to convert it to base64. Since private keys are typically multi-line, they can cause parsing errors or issues when setting environment variables. To avoid this, run the following command to convert the key to base64:
158+
159+
```bash
160+
cat private_key.pem | base64 -w 0
161+
```
162+
163+
8. Once you've created the app, [activate the GitHub Enterprise integration in Plane](https://docs.plane.so/integrations/github?edition=github-enterprise#connect-github-organization).
164+
165+
## Troubleshooting
166+
167+
### Invalid private key
168+
169+
<div style="color: red">
170+
Error: Failed to create GitHub connection: Invalid keyData
171+
</div>
172+
173+
This error usually occurs when the private key is not correctly generated. To fix this, follow the below steps.
174+
175+
1. Generate a new private key.
176+
2. Convert the private key to base64.
177+
178+
```bash
179+
cat private_key.pem | base64 -w 0
180+
```
181+
182+
3. Add the private key to the `.env` file.
183+
184+
```bash
185+
GITHUB_PRIVATE_KEY=<private_key>
186+
```
187+
188+
4. Save the file and restart the instance.
189+
190+
### Unable to connect GitHub organization account or personal account
191+
192+
<div style="color: red">
193+
Error: Invalid request callback URL.
194+
</div>
195+
196+
This error usually occurs when the callback URL is not correctly configured or the GitHub App is not marked public. To fix this, follow the below steps.
197+
198+
1. Check if the callback URL is correctly configured.
199+
2. Check if your GitHub App is marked public.
200+
201+
### Application secret value not found
202+
203+
<div style="color: red">
204+
Error: Application secret value not found for key: x-github-id
205+
</div>
206+
207+
This error usually occurs when the application secret is not correctly configured. To fix this, follow the below steps.
208+
209+
1. Delete the `plane_app_details_github` key from redis cache. `del plane_app_details_github`.
210+
2. Set the `SILO_BASE_URL` in env with plane self hosted url and restart the api server. `export SILO_BASE_URL=https://<your-domain>`
211+
3. Run this command in api server shell `python manage.py reset_marketplace_app_secrets` to reset the application secrets.
212+
4. Try to connect again to the organization account to Plane.
213+
214+
### Github integration suddenly stopped working after a while
215+
216+
This error usually occurs when the GitHub integration is not correctly configured. To fix this, follow the below steps.
217+
218+
1. Make sure you've `opted out` of Server Token expiration and reconnect once again to the organization account to Plane. Check in Github App Settings > Optional Features

0 commit comments

Comments
 (0)