Skip to content

Commit 728a66c

Browse files
danciaclaradanciaclara
committed
Configure GitHub App for integration
1 parent 321c33c commit 728a66c

File tree

2 files changed

+129
-0
lines changed

2 files changed

+129
-0
lines changed

‎mint.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,12 @@
9090
"self-hosting/govern/database-and-storage",
9191
"self-hosting/govern/custom-domain",
9292
"self-hosting/govern/private-bucket",
93+
{
94+
"group": "Integrations",
95+
"pages": [
96+
"self-hosting/govern/integrations/github"
97+
]
98+
},
9399
"self-hosting/govern/reverse-proxy",
94100
"self-hosting/telemetry"
95101
]

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

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
title : Configure GitHub App for Plane integration
3+
sidebarTitle: GitHub
4+
---
5+
6+
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.
7+
8+
In this guide, you’ll:
9+
1. [Create and configure a GitHub App](/self-hosting/govern/integrations/github#create-github-app)
10+
2. [Set up permissions and events](/self-hosting/govern/integrations/github#set-up-permissions-and-events)
11+
3. [Configure your Plane instance](/self-hosting/govern/integrations/github#configure-plane-instance)
12+
13+
<Warning>
14+
**Activate GitHub integration**
15+
16+
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.
17+
</Warning>
18+
19+
## Create GitHub App
20+
21+
To configure GitHub integration, you'll need to create a GitHub App within your organization. Follow these steps:
22+
23+
1. Go to **Settings \> Developer Settings \> GitHub Apps** in your GitHub organization.
24+
25+
2. Click **New GitHub App**.
26+
27+
3. Provide a **GitHub App name** and **Homepage URL**.
28+
29+
4. In the **Identifying and authorizing users** section, add the following **Callback URLS**.
30+
31+
```bash
32+
https://<your-domain>/silo/api/github/auth/callback
33+
https://<your-domain>/silo/api/github/auth/user/callback
34+
```
35+
These URLs allow Plane to verify and enable workspace connection with the Github App.
36+
37+
5. In the **Post installation** section, add the below **Setup URL**.
38+
39+
```bash
40+
https://<your-domain>/silo/api/github/auth/callback
41+
```
42+
Redirects users to this URL after GitHub app installation.
43+
44+
45+
6. Turn on **Redirect on update**.
46+
47+
7. In the **Webhook** section, add the below **Webhook URL**.
48+
```bash
49+
https://<your-domain>/silo/api/github/github-webhook
50+
```
51+
This allows Plane to receive updates from GitHub repositories.
52+
53+
### Set up permissions and events
54+
55+
1. Add repository and account permissions by setting the **Access** dropdown next to each permission, as shown in the tables below.
56+
57+
**Repository permissions**
58+
59+
|Permission|Access level|Purpose|
60+
|---------|------------|-----------|
61+
|Commit statuses|Read-only|Monitor CI/CD status of commits|
62+
|Contents|Read and write|Read and modify repository files|
63+
|Issues|Read and write|Sync issues between Plane and GitHub|
64+
|Merge queues|Read-only|View merge queue details|
65+
|Metadata|Read-only|Access repository details|
66+
|Pull requests|Read and write|Manage pull requests|
67+
68+
**Account permissions**
69+
70+
|Permission|Access level|Purpose|
71+
|---------|------------|-----------|
72+
|Email addresses|Read-only|Access user email for notifications|
73+
|Profile|Read and write|Retrieve and update user profile data|
74+
75+
2. In the **Subscribe to events** section, turn on all the required events below.
76+
77+
|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|
78+
|---------|------------|
79+
|Installation target| This is where the repositories or organizations where your GitHub App is installed. This determines which repositories Plane can sync with.|
80+
|Meta|Includes metadata about the app's configuration and setup. This is essential for maintaining integration stability.|
81+
|Issue comment| Triggers when a comment is added, edited, or deleted on an issue. Useful for keeping comments synced between Plane and GitHub.|
82+
|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.|
83+
|Pull request|Fires when a pull request is opened, closed, merged, edited, or labeled. Essential for tracking development progress.|
84+
|Pull request review|Activates when a review is submitted, edited, or dismissed. Keeps review activities aligned between Plane and GitHub.|
85+
|Pull request review comment|Fires when a review comment is added, modified, or removed. Ensures feedback is reflected across both platforms.|
86+
|Pull request review thread|Triggers when a review discussion thread is resolved or reopened. Helps maintain visibility on code review discussions.|
87+
|Push|Activates when new commits are pushed to a repository. Useful for tracking code updates and changes.|
88+
|Rsepository sub issues|Tracks issues within a repository that are linked to or managed by another issue. Ensures accurate synchronization of related issues.|
89+
90+
3. Click the **Create Github App** button.
91+
92+
## Configure Plane instance
93+
94+
1. Go back to **Settings \> Developer Settings \> GitHub Apps**.
95+
96+
2. Click **Edit** on the GitHub you created.
97+
98+
3. In the **General** tab, under the **Client secrets** section, click **Generate a new client secret**.
99+
100+
4. Scroll down to the **Private keys** section.
101+
102+
5. Click **Genereate a private key**.
103+
104+
6. Retrieve the following details from the General tab:
105+
- App ID
106+
- Client ID
107+
- Client secret
108+
- GitHub App name
109+
- Private key
110+
111+
7. Add these environment variables to your Plane instance's `.env` file.
112+
113+
```bash
114+
GITHUB_CLIENT_ID=<CLIENT_ID>
115+
GITHUB_CLIENT_SECRET=<CLIENT_SECRET>
116+
GITHUB_APP_NAME=<APP_NAME>
117+
GITHUB_APP_ID=<APP_ID>
118+
GITHUB_PRIVATE_KEY=<PRIVATE_KEY>
119+
```
120+
121+
8. Save the file and restrat the instance.
122+
123+
9. Once you've completed the instance configuration, [activate the GitHub integration in Plane](https://docs.plane.so/integrations/github).

0 commit comments

Comments
 (0)