Skip to content

Commit 1fda380

Browse files
danciaclaraaheckmann
danciaclara
authored and
aheckmann
committed
Github Enterprise Server - Create GitHub App
1 parent af06ed3 commit 1fda380

File tree

1 file changed

+145
-27
lines changed

1 file changed

+145
-27
lines changed

‎docs/self-hosting/govern/integrations/github.mdx

Lines changed: 145 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -3,64 +3,144 @@ title: Configure GitHub App for Plane integration
33
sidebar_label: GitHub
44
---
55

6+
import Tabs from '@theme/Tabs';
7+
import TabItem from '@theme/TabItem';
8+
69
{frontMatter.description && <h3 className="description">{frontMatter.description}</h3>}
710

811
This guide walks you through setting up a GitHub App to enable GitHub integration for your Plane workspace on a self-hosted instance. Since self-hosted environments don’t come pre-configured for GitHub, you’ll need to set up the necessary authentication, permissions, and webhooks to ensure smooth integration.
912

13+
This guide covers configuration for both:
14+
15+
- **[GitHub Cloud](/self-hosting/govern/integrations/github?edition=github-cloud#create-github-app)**
16+
The standard cloud-hosted GitHub service
17+
18+
- **[GitHub Enterprise Server](/self-hosting/govern/integrations/github?edition=github-enterprise#create-github-app)**
19+
Self-hosted GitHub instances for organizations with specific compliance or security requirements
20+
1021
In this guide, you’ll:
1122

1223
1. [Create and configure a GitHub App](/self-hosting/govern/integrations/github#create-github-app)
1324
2. [Set up permissions and events](/self-hosting/govern/integrations/github#set-up-permissions-and-events)
1425
3. [Configure your Plane instance](/self-hosting/govern/integrations/github#configure-plane-instance)
1526

16-
:::warning
27+
:::warning[IMPORTANT]
1728
**Activate GitHub integration**
1829

1930
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.
2031
:::
2132

2233
## Create GitHub App
2334

24-
To configure GitHub integration, you'll need to create a GitHub App within your organization. Follow these steps:
35+
To configure GitHub integration, you'll need to create a GitHub App within your organization.
2536

26-
1. Go to **Settings \> Developer Settings \> GitHub Apps** in your GitHub organization.
37+
<Tabs queryString="edition" groupId="editions">
38+
<TabItem value="github-cloud" label="GitHub Cloud">
2739

28-
2. Click **New GitHub App**.
29-
![Create GitHub App](/images/integrations/github/create-github-app.webp)
40+
1. Go to **Settings \> Developer Settings \> GitHub Apps** in your GitHub organization.
3041

31-
3. In the **Register new GitHub App** page, provide a **GitHub App name** and **Homepage URL**.
32-
![App name and homepage URL](/images/integrations/github/app-name-homepage-url.webp)
42+
2. Click **New GitHub App**.
43+
![Create GitHub App](/images/integrations/github/create-github-app.webp)
3344

34-
4. In the **Identifying and authorizing users** section, add the following **Callback URLS**.
45+
3. In the **Register new GitHub App** page, provide a **GitHub App name** and **Homepage URL**.
46+
![App name and homepage URL](/images/integrations/github/app-name-homepage-url.webp)
3547

36-
```bash
37-
https://<your-domain>/silo/api/github/auth/callback
38-
https://<your-domain>/silo/api/github/auth/user/callback
39-
```
48+
4. In the **Identifying and authorizing users** section, add the following **Callback URLS**.
4049

41-
These URLs allow Plane to verify and enable workspace connection with the Github App.
42-
![Add Callback URL](/images/integrations/github/add-callback-url.webp)
50+
```bash
51+
https://<your-domain>/silo/api/github/auth/callback
52+
https://<your-domain>/silo/api/github/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)
4357

4458
5. In the **Post installation** section, add the below **Setup URL**.
4559

46-
```bash
47-
https://<your-domain>/silo/api/github/auth/callback
48-
```
60+
```bash
61+
https://<your-domain>/silo/api/github/auth/callback
62+
```
4963

50-
Redirects users to this URL after GitHub app installation.
51-
![Add setup URL](/images/integrations/github/add-setup-url.webp)
64+
Redirects users to this URL after GitHub app installation.
65+
![Add setup URL](/images/integrations/github/add-setup-url.webp)
5266

53-
6. Turn on **Redirect on update**.
67+
6. Turn on **Redirect on update**.
5468

55-
7. In the **Webhook** section, add the below **Webhook URL**.
69+
7. In the **Webhook** section, add the below **Webhook URL**.
5670

57-
```bash
58-
https://<your-domain>/silo/api/github/github-webhook
59-
```
71+
```bash
72+
https://<your-domain>/silo/api/github/github-webhook
73+
```
74+
75+
This allows Plane to receive updates from GitHub repositories.
76+
77+
![Add Webhook URL](/images/integrations/github/add-webhook-url.webp)
78+
</TabItem>
79+
80+
<TabItem value="github-enterprise" label="GitHub Enterprise Server">
81+
1. Go to **Settings \> Developer Settings \> GitHub Apps** in your GitHub organization.
82+
83+
2. Click **New GitHub App**.
84+
![Create GitHub App](/images/integrations/github/create-github-app.webp)
85+
86+
3. In the **Register new GitHub App** page, provide a **GitHub App name** and **Homepage URL**.
87+
![App name and homepage URL](/images/integrations/github/app-name-homepage-url.webp)
88+
89+
4. In the **Identifying and authorizing users** section, add the following **Callback URLS**.
90+
91+
**For Plane cloud instance**
92+
93+
```bash
94+
https://silo.plane.so/api/github/auth/callback
95+
https://silo.plane.so/api/github/auth/user/callback
96+
```
97+
98+
**For Plane self-hosted instance**
99+
100+
```bash
101+
https://<your-domain>/silo/api/github/auth/callback
102+
https://<your-domain>/silo/api/github/auth/user/callback
103+
```
104+
105+
These URLs allow Plane to verify and enable workspace connection with the Github App.
106+
![Add Callback URL](/images/integrations/github/add-callback-url.webp)
107+
108+
5. In the **Post installation** section, add the below **Setup URL**.
109+
110+
**For Plane cloud instance**
111+
```bash
112+
https://silo.plane.so/api/oauth/github-enterprise/auth/callback
113+
```
114+
115+
**For Plane self-hosted instance**
60116

61-
This allows Plane to receive updates from GitHub repositories.
117+
```bash
118+
https://<your-plane-domain>/silo/api/oauth/github-enterprise/auth/callback
119+
```
120+
Redirects users to this URL after GitHub app installation.
121+
![Add setup URL](/images/integrations/github/add-setup-url.webp)
62122

63-
![Add Webhook URL](/images/integrations/github/add-webhook-url.webp)
123+
6. Turn on **Redirect on update**.
124+
125+
7. In the **Webhook** section, add the below **Webhook URL**.
126+
127+
**For Plane cloud instance**
128+
```bash
129+
https://silo.plane.so/api/github-enterprise/github-webhook
130+
```
131+
132+
**For Plane self-hosted instance**
133+
134+
```bash
135+
https://<your-plane-domain>/silo/api/github-enterprise/github-webhook
136+
```
137+
This allows Plane to receive updates from GitHub repositories.
138+
139+
![Add Webhook URL](/images/integrations/github/add-webhook-url.webp)
140+
141+
142+
</TabItem>
143+
</Tabs>
64144

65145
### Set up permissions and events
66146

@@ -106,7 +186,10 @@ To configure GitHub integration, you'll need to create a GitHub App within your
106186

107187
## Configure Plane instance
108188

109-
1. Go back to **Settings \> Developer Settings \> GitHub Apps**.
189+
<Tabs queryString="edition" groupId="editions">
190+
<TabItem value="github-cloud" label="GitHub Cloud">
191+
192+
1. Go back to **Settings \> Developer Settings \> GitHub Apps**.
110193

111194
2. Click **Edit** on the GitHub you created.
112195

@@ -146,3 +229,38 @@ To configure GitHub integration, you'll need to create a GitHub App within your
146229
9. Save the file and restart the instance.
147230

148231
10. Once you've completed the instance configuration, [activate the GitHub integration in Plane](https://docs.plane.so/integrations/github).
232+
233+
</TabItem>
234+
235+
<TabItem value="github-enterprise" label="GitHub Enterprise Server">
236+
237+
238+
1. Go back to **Settings \> Developer Settings \> GitHub Apps**.
239+
240+
2. Click **Edit** on the GitHub you created.
241+
242+
3. In the **General** tab, under the **Client secrets** section, click **Generate a new client secret**.
243+
244+
![General tab](/images/integrations/github/general-tab.webp)
245+
246+
4. Scroll down to the **Private keys** section.
247+
248+
![Private keys](/images/integrations/github/private-keys.webp)
249+
250+
5. Click **Generate a private key**.
251+
252+
6. Retrieve the following details from the **General** tab:
253+
- App ID
254+
- App Slug (You can find this in browser url)
255+
- Client ID
256+
- Client secret
257+
- Private key
258+
259+
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:
260+
```bash
261+
cat private_key.pem | base64 -w 0
262+
```
263+
264+
8. Once you've created the app, [activate the GitHub Enterprise integration in Plane](https://docs.plane.so/integrations/github#connect-github-enterprise-organization).
265+
</TabItem>
266+
</Tabs>

0 commit comments

Comments
 (0)