Skip to content

Commit 57cc722

Browse files
danciaclaradanciaclara
committed
GitLab self-managed
1 parent cf59ae3 commit 57cc722

File tree

2 files changed

+110
-31
lines changed

2 files changed

+110
-31
lines changed

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

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -74,13 +74,13 @@ To configure GitHub integration, you'll need to create a GitHub App within your
7474

7575
1. Go to **Settings \> Developer Settings \> GitHub Apps** in your GitHub organization.
7676

77-
2. Click **New GitHub App**.
77+
2. Click **New GitHub App**.
7878
![Create GitHub App](/images/integrations/github/create-github-app.webp)
7979

80-
3. In the **Register new GitHub App** page, provide a **GitHub App name** and **Homepage URL**.
80+
3. In the **Register new GitHub App** page, provide a **GitHub App name** and **Homepage URL**.
8181
![App name and homepage URL](/images/integrations/github/app-name-homepage-url.webp)
8282

83-
4. In the **Identifying and authorizing users** section, add the following **Callback URLS**.
83+
4. In the **Identifying and authorizing users** section, add the following **Callback URLS**.
8484

8585
**For Plane cloud instance**
8686

@@ -99,7 +99,7 @@ To configure GitHub integration, you'll need to create a GitHub App within your
9999
These URLs allow Plane to verify and enable workspace connection with the Github App.
100100
![Add Callback URL](/images/integrations/github/add-callback-url.webp)
101101

102-
5. In the **Post installation** section, add the below **Setup URL**.
102+
5. In the **Post installation** section, add the below **Setup URL**.
103103

104104
**For Plane cloud instance**
105105
```bash
@@ -114,9 +114,9 @@ To configure GitHub integration, you'll need to create a GitHub App within your
114114
Redirects users to this URL after GitHub app installation.
115115
![Add setup URL](/images/integrations/github/add-setup-url.webp)
116116

117-
6. Turn on **Redirect on update**.
117+
6. Turn on **Redirect on update**.
118118

119-
7. In the **Webhook** section, add the below **Webhook URL**.
119+
7. In the **Webhook** section, add the below **Webhook URL**.
120120

121121
**For Plane cloud instance**
122122
```bash

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

Lines changed: 104 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -5,48 +5,116 @@ sidebarTitle: GitLab
55

66
This guide walks you through setting up a GitLab application to enable GitLab integration for your Plane workspace on a self-hosted instance. Since self-hosted environments don’t come pre-configured for GitLab, you’ll need to create an application, configure authentication, and set the necessary permissions to ensure seamless integration.
77

8+
This guide covers configuration for both:
9+
10+
- **[GitLab.com](/self-hosting/govern/integrations/gitlab?edition=gitlab-cloud#create-gitlab-application)**
11+
The standard cloud-hosted GitLab service
12+
13+
- **[GitLab Self-managed](/self-hosting/govern/integrations/gitlab?edition=gitlab-self-managed#create-gitlab-application)**
14+
Self-hosted GitLab instances for organizations with specific compliance or security requirements
15+
816
In this guide, you’ll:
917

10-
1. [Create and configure a GitLab Application](/self-hosting/govern/integrations/gitlab#create-a-gitlab-application)
18+
1. [Create and configure a GitLab Application](/self-hosting/govern/integrations/gitlab#create-gitlab-application)
1119
2. [Configure your Plane instance](/self-hosting/govern/integrations/gitlab#configure-plane-instance)
1220

21+
<Warning>
22+
**Activate GitLab integration**
23+
24+
After creating and configuring the GitLab application and configuring the instance as detailed on this page, you'll need to [setup the GitLab integration](https://docs.plane.so/integrations/gitlab) within Plane.
25+
</Warning>
26+
1327
## Create GitLab Application
1428

15-
1. On the left sidebar in GitLab, select your avatar.
29+
<Tabs>
30+
<Tab title="GitLab Cloud">
31+
1. On the left sidebar in GitLab, select your avatar.
1632

17-
2. Select **Preferences** tab.
33+
2. Select **Preferences** tab.
1834

19-
3. Navigate to the **Applications** tab.
35+
3. Navigate to the **Applications** tab.
2036

21-
4. Click on **Add new application** to begin the setup.
22-
![Add GitLab application](/images/integrations/gitlab/add-gitlab-application.webp)
37+
4. Click on **Add new application** to begin the setup.
38+
![Add GitLab application](/images/integrations/gitlab/add-gitlab-application.webp)
2339

24-
5. Provide a **Name** for your application.
40+
5. Provide a **Name** for your application.
2541

26-
6. Enter the following **Redirect URI**, replacing [YOUR_DOMAIN] with your actual domain:
27-
```bash
28-
https://[YOUR_DOMAIN]/silo/api/gitlab/auth/callback
29-
```
30-
7. You can choose to check or leave the **Confidential** box unchecked—both options work for Plane.
42+
6. Enter the following **Redirect URI**, replacing [YOUR_DOMAIN] with your actual domain:
43+
```bash
44+
https://[YOUR_DOMAIN]/silo/api/gitlab/auth/callback
45+
```
46+
7. You can choose to check or leave the **Confidential** box unchecked—both options work for Plane.
47+
48+
![Add app details](/images/integrations/gitlab/add-app-details.webp)
49+
50+
8. Set permissions by selecting the required **Scopes**. The table below explains each scope:
51+
52+
|Permission|Explanation|
53+
|----------|-----------|
54+
|`api`|Grants full read/write access to the API, including all groups, projects, container registry, dependency proxy, and package registry. Required for API requests.|
55+
|`read_api`|Allows read-only access to all groups, projects, container registry, and package registry.|
56+
|`read_user`|Grants read-only access to user profiles via the /user API endpoint, including username, public email, and full name. Also provides access to /users endpoints.|
57+
|`read_repository`|Enables read-only access to repositories in private projects via Git-over-HTTP or the Repository Files API.|
58+
|`write_repository`|Allows read/write access to repositories on private projects via Git-over-HTTP (not through the API).|
59+
|`profile`|Grants read-only access to the user's profile data using OpenID Connect.|
60+
|`email`|Provides read-only access to the user's primary email address using OpenID Connect.|
61+
62+
9. Click **Save Application** to finalize the setup.
63+
</Tab>
64+
65+
<Tab title="GitLab Self-managed">
66+
1. Log in to your GitLab instance.
67+
2. Click on your profile icon in the top-right corner.
68+
3. From the dropdown menu that appears, select **Edit profile**.
69+
4. Look for and select the **Applications** option within this menu.
70+
71+
![GitLab Applications](https://media.docs.plane.so/integrations/gitlab/gitlab-applications.webp#center)
72+
73+
5. On the Applications page, click **Add new application** to begin configuring your OAuth application.
3174

32-
![Add app details](/images/integrations/gitlab/add-app-details.webp)
75+
Fill in the application details with the following configuration:
3376

34-
8. Set permissions by selecting the required **Scopes**. The table below explains each scope:
77+
- **Name**
78+
Enter a descriptive name for your application (e.g., `Plane Local Dev` or `Plane Integration`).
3579

36-
|Permission|Explanation|
37-
|----------|-----------|
38-
|`api`|Grants full read/write access to the API, including all groups, projects, container registry, dependency proxy, and package registry. Required for API requests.|
39-
|`read_api`|Allows read-only access to all groups, projects, container registry, and package registry.|
40-
|`read_user`|Grants read-only access to user profiles via the /user API endpoint, including username, public email, and full name. Also provides access to /users endpoints.|
41-
|`read_repository`|Enables read-only access to repositories in private projects via Git-over-HTTP or the Repository Files API.|
42-
|`write_repository`|Allows read/write access to repositories on private projects via Git-over-HTTP (not through the API).|
43-
|`profile`|Grants read-only access to the user's profile data using OpenID Connect.|
44-
|`email`|Provides read-only access to the user's primary email address using OpenID Connect.|
80+
- **Redirect URI**
81+
The redirect URI depends on your Plane deployment:
82+
83+
**For Plane Cloud:**
84+
```
85+
https://silo.plane.so/api/oauth/gitlab-enterprise/auth/callback
86+
```
87+
88+
**For Plane Self-Hosted:**
89+
```
90+
https://<your-domain>/silo/api/oauth/gitlab-enterprise/auth/callback
91+
```
92+
93+
Replace `<your-domain>` with your actual Plane instance domain.
94+
95+
- **Confidential**
96+
Keep the **Confidential** checkbox enabled. This ensures the application uses a client secret for secure authentication.
97+
98+
- **Scopes**
99+
Select the following scopes to grant Plane the necessary permissions:
100+
101+
- **api** - Grants complete read/write access to the API, including all groups and projects
102+
- **read_api** - Grants read access to the API, including all groups and projects
103+
- **read_user** - Grants read-only access to your profile information
104+
- **read_repository** - Grants read-only access to repositories on private projects
105+
- **profile** - Grants read-only access to the user's profile data using OpenID Connect
106+
- **email** - Grants read-only access to the user's primary email address using OpenID Connect
107+
108+
6. Click **Save application** to create the OAuth application.
109+
</Tab>
110+
</Tabs>
45111

46-
9. Click **Save Application** to finalize the setup.
47112

48113
## Configure Plane instance
49114

115+
<Tabs>
116+
<Tab title="GitLab Cloud">
117+
50118
1. Copy the **Application ID** and **Secret** from the newly created application.
51119
![Copy credentials](/images/integrations/gitlab/copy-credentials.webp)
52120

@@ -58,4 +126,15 @@ In this guide, you’ll:
58126
```
59127
3. Save the file and restart the instance.
60128

61-
4. Once you've completed the instance configuration, [activate the GitLab integration in Plane](https://docs.plane.so/integrations/gitlab).
129+
4. Once you've completed the instance configuration, [activate the GitLab integration in Plane](https://docs.plane.so/integrations/gitlab?edition=gitlab-cloud).
130+
131+
</Tab>
132+
133+
<Tab title="GitLab Self-managed">
134+
135+
1. Copy the **Application ID** and **Secret** from the newly created application.
136+
![Copy credentials](/images/integrations/gitlab/copy-credentials.webp)
137+
138+
2. Once you've created the application, [activate the GitLab Self-managed integration in Plane](https://docs.plane.so/integrations/gitlab?edition=gitlab-self-managed).
139+
</Tab>
140+
</Tabs>

0 commit comments

Comments
 (0)