From 57cc72227d05448d8d7bede94a09cc81b81e7916 Mon Sep 17 00:00:00 2001 From: danciaclara Date: Tue, 7 Oct 2025 16:28:43 +0530 Subject: [PATCH 1/4] GitLab self-managed --- self-hosting/govern/integrations/github.mdx | 12 +- self-hosting/govern/integrations/gitlab.mdx | 129 ++++++++++++++++---- 2 files changed, 110 insertions(+), 31 deletions(-) diff --git a/self-hosting/govern/integrations/github.mdx b/self-hosting/govern/integrations/github.mdx index 926f2a4..ecc90e1 100644 --- a/self-hosting/govern/integrations/github.mdx +++ b/self-hosting/govern/integrations/github.mdx @@ -74,13 +74,13 @@ To configure GitHub integration, you'll need to create a GitHub App within your 1. Go to **Settings \> Developer Settings \> GitHub Apps** in your GitHub organization. - 2. Click **New GitHub App**. +2. Click **New GitHub App**. ![Create GitHub App](/images/integrations/github/create-github-app.webp) - 3. In the **Register new GitHub App** page, provide a **GitHub App name** and **Homepage URL**. +3. In the **Register new GitHub App** page, provide a **GitHub App name** and **Homepage URL**. ![App name and homepage URL](/images/integrations/github/app-name-homepage-url.webp) - 4. In the **Identifying and authorizing users** section, add the following **Callback URLS**. +4. In the **Identifying and authorizing users** section, add the following **Callback URLS**. **For Plane cloud instance** @@ -99,7 +99,7 @@ To configure GitHub integration, you'll need to create a GitHub App within your These URLs allow Plane to verify and enable workspace connection with the Github App. ![Add Callback URL](/images/integrations/github/add-callback-url.webp) - 5. In the **Post installation** section, add the below **Setup URL**. +5. In the **Post installation** section, add the below **Setup URL**. **For Plane cloud instance** ```bash @@ -114,9 +114,9 @@ To configure GitHub integration, you'll need to create a GitHub App within your Redirects users to this URL after GitHub app installation. ![Add setup URL](/images/integrations/github/add-setup-url.webp) - 6. Turn on **Redirect on update**. +6. Turn on **Redirect on update**. - 7. In the **Webhook** section, add the below **Webhook URL**. +7. In the **Webhook** section, add the below **Webhook URL**. **For Plane cloud instance** ```bash diff --git a/self-hosting/govern/integrations/gitlab.mdx b/self-hosting/govern/integrations/gitlab.mdx index 4e12c0a..c36d91a 100644 --- a/self-hosting/govern/integrations/gitlab.mdx +++ b/self-hosting/govern/integrations/gitlab.mdx @@ -5,48 +5,116 @@ sidebarTitle: GitLab 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. +This guide covers configuration for both: + +- **[GitLab.com](/self-hosting/govern/integrations/gitlab?edition=gitlab-cloud#create-gitlab-application)** +The standard cloud-hosted GitLab service + +- **[GitLab Self-managed](/self-hosting/govern/integrations/gitlab?edition=gitlab-self-managed#create-gitlab-application)** +Self-hosted GitLab instances for organizations with specific compliance or security requirements + In this guide, you’ll: -1. [Create and configure a GitLab Application](/self-hosting/govern/integrations/gitlab#create-a-gitlab-application) +1. [Create and configure a GitLab Application](/self-hosting/govern/integrations/gitlab#create-gitlab-application) 2. [Configure your Plane instance](/self-hosting/govern/integrations/gitlab#configure-plane-instance) + +**Activate GitLab integration** + +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. + + ## Create GitLab Application -1. On the left sidebar in GitLab, select your avatar. + + + 1. On the left sidebar in GitLab, select your avatar. -2. Select **Preferences** tab. + 2. Select **Preferences** tab. -3. Navigate to the **Applications** tab. + 3. Navigate to the **Applications** tab. -4. Click on **Add new application** to begin the setup. - ![Add GitLab application](/images/integrations/gitlab/add-gitlab-application.webp) + 4. Click on **Add new application** to begin the setup. + ![Add GitLab application](/images/integrations/gitlab/add-gitlab-application.webp) -5. Provide a **Name** for your application. + 5. Provide a **Name** for your application. -6. Enter the following **Redirect URI**, replacing [YOUR_DOMAIN] with your actual domain: - ```bash - https://[YOUR_DOMAIN]/silo/api/gitlab/auth/callback - ``` -7. You can choose to check or leave the **Confidential** box unchecked—both options work for Plane. + 6. Enter the following **Redirect URI**, replacing [YOUR_DOMAIN] with your actual domain: + ```bash + https://[YOUR_DOMAIN]/silo/api/gitlab/auth/callback + ``` + 7. You can choose to check or leave the **Confidential** box unchecked—both options work for Plane. + + ![Add app details](/images/integrations/gitlab/add-app-details.webp) + + 8. Set permissions by selecting the required **Scopes**. The table below explains each scope: + + |Permission|Explanation| + |----------|-----------| + |`api`|Grants full read/write access to the API, including all groups, projects, container registry, dependency proxy, and package registry. Required for API requests.| + |`read_api`|Allows read-only access to all groups, projects, container registry, and package registry.| + |`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.| + |`read_repository`|Enables read-only access to repositories in private projects via Git-over-HTTP or the Repository Files API.| + |`write_repository`|Allows read/write access to repositories on private projects via Git-over-HTTP (not through the API).| + |`profile`|Grants read-only access to the user's profile data using OpenID Connect.| + |`email`|Provides read-only access to the user's primary email address using OpenID Connect.| + + 9. Click **Save Application** to finalize the setup. + + + +1. Log in to your GitLab instance. +2. Click on your profile icon in the top-right corner. +3. From the dropdown menu that appears, select **Edit profile**. +4. Look for and select the **Applications** option within this menu. + +![GitLab Applications](https://media.docs.plane.so/integrations/gitlab/gitlab-applications.webp#center) + +5. On the Applications page, click **Add new application** to begin configuring your OAuth application. - ![Add app details](/images/integrations/gitlab/add-app-details.webp) +Fill in the application details with the following configuration: -8. Set permissions by selecting the required **Scopes**. The table below explains each scope: + - **Name** + Enter a descriptive name for your application (e.g., `Plane Local Dev` or `Plane Integration`). - |Permission|Explanation| - |----------|-----------| - |`api`|Grants full read/write access to the API, including all groups, projects, container registry, dependency proxy, and package registry. Required for API requests.| - |`read_api`|Allows read-only access to all groups, projects, container registry, and package registry.| - |`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.| - |`read_repository`|Enables read-only access to repositories in private projects via Git-over-HTTP or the Repository Files API.| - |`write_repository`|Allows read/write access to repositories on private projects via Git-over-HTTP (not through the API).| - |`profile`|Grants read-only access to the user's profile data using OpenID Connect.| - |`email`|Provides read-only access to the user's primary email address using OpenID Connect.| + - **Redirect URI** + The redirect URI depends on your Plane deployment: + + **For Plane Cloud:** + ``` + https://silo.plane.so/api/oauth/gitlab-enterprise/auth/callback + ``` + + **For Plane Self-Hosted:** + ``` + https:///silo/api/oauth/gitlab-enterprise/auth/callback + ``` + + Replace `` with your actual Plane instance domain. + + - **Confidential** + Keep the **Confidential** checkbox enabled. This ensures the application uses a client secret for secure authentication. + + - **Scopes** + Select the following scopes to grant Plane the necessary permissions: + + - **api** - Grants complete read/write access to the API, including all groups and projects + - **read_api** - Grants read access to the API, including all groups and projects + - **read_user** - Grants read-only access to your profile information + - **read_repository** - Grants read-only access to repositories on private projects + - **profile** - Grants read-only access to the user's profile data using OpenID Connect + - **email** - Grants read-only access to the user's primary email address using OpenID Connect + +6. Click **Save application** to create the OAuth application. + + -9. Click **Save Application** to finalize the setup. ## Configure Plane instance + + + 1. Copy the **Application ID** and **Secret** from the newly created application. ![Copy credentials](/images/integrations/gitlab/copy-credentials.webp) @@ -58,4 +126,15 @@ In this guide, you’ll: ``` 3. Save the file and restart the instance. -4. Once you've completed the instance configuration, [activate the GitLab integration in Plane](https://docs.plane.so/integrations/gitlab). +4. Once you've completed the instance configuration, [activate the GitLab integration in Plane](https://docs.plane.so/integrations/gitlab?edition=gitlab-cloud). + + + + + +1. Copy the **Application ID** and **Secret** from the newly created application. + ![Copy credentials](/images/integrations/gitlab/copy-credentials.webp) + +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). + + \ No newline at end of file From c3ebd6abb4c15ea4bbf361893e9c72e39403368c Mon Sep 17 00:00:00 2001 From: danciaclara Date: Mon, 13 Oct 2025 18:31:56 +0530 Subject: [PATCH 2/4] fixed coderabbit review --- self-hosting/govern/integrations/gitlab.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/self-hosting/govern/integrations/gitlab.mdx b/self-hosting/govern/integrations/gitlab.mdx index c36d91a..02bdfbe 100644 --- a/self-hosting/govern/integrations/gitlab.mdx +++ b/self-hosting/govern/integrations/gitlab.mdx @@ -43,7 +43,7 @@ After creating and configuring the GitLab application and configuring the instan ```bash https://[YOUR_DOMAIN]/silo/api/gitlab/auth/callback ``` - 7. You can choose to check or leave the **Confidential** box unchecked—both options work for Plane. + 7. Check the **Confidential** box.. ![Add app details](/images/integrations/gitlab/add-app-details.webp) @@ -55,7 +55,6 @@ After creating and configuring the GitLab application and configuring the instan |`read_api`|Allows read-only access to all groups, projects, container registry, and package registry.| |`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.| |`read_repository`|Enables read-only access to repositories in private projects via Git-over-HTTP or the Repository Files API.| - |`write_repository`|Allows read/write access to repositories on private projects via Git-over-HTTP (not through the API).| |`profile`|Grants read-only access to the user's profile data using OpenID Connect.| |`email`|Provides read-only access to the user's primary email address using OpenID Connect.| From 53409bbdebe9e85026766f614b4984ee93cf1d6f Mon Sep 17 00:00:00 2001 From: danciaclara Date: Mon, 13 Oct 2025 18:37:31 +0530 Subject: [PATCH 3/4] fixed coderabbit review --- self-hosting/govern/integrations/gitlab.mdx | 44 ++++++++++----------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/self-hosting/govern/integrations/gitlab.mdx b/self-hosting/govern/integrations/gitlab.mdx index 02bdfbe..30799bd 100644 --- a/self-hosting/govern/integrations/gitlab.mdx +++ b/self-hosting/govern/integrations/gitlab.mdx @@ -28,37 +28,37 @@ After creating and configuring the GitLab application and configuring the instan - 1. On the left sidebar in GitLab, select your avatar. +1. On the left sidebar in GitLab, select your avatar. - 2. Select **Preferences** tab. +2. Select **Preferences** tab. - 3. Navigate to the **Applications** tab. +3. Navigate to the **Applications** tab. - 4. Click on **Add new application** to begin the setup. - ![Add GitLab application](/images/integrations/gitlab/add-gitlab-application.webp) +4. Click on **Add new application** to begin the setup. + ![Add GitLab application](/images/integrations/gitlab/add-gitlab-application.webp) - 5. Provide a **Name** for your application. +5. Provide a **Name** for your application. - 6. Enter the following **Redirect URI**, replacing [YOUR_DOMAIN] with your actual domain: - ```bash - https://[YOUR_DOMAIN]/silo/api/gitlab/auth/callback - ``` - 7. Check the **Confidential** box.. +6. Enter the following **Redirect URI**, replacing [YOUR_DOMAIN] with your actual domain: + ```bash + https://[YOUR_DOMAIN]/silo/api/gitlab/auth/callback + ``` +7. Check the **Confidential** box.. - ![Add app details](/images/integrations/gitlab/add-app-details.webp) + ![Add app details](/images/integrations/gitlab/add-app-details.webp) - 8. Set permissions by selecting the required **Scopes**. The table below explains each scope: +8. Set permissions by selecting the required **Scopes**. The table below explains each scope: - |Permission|Explanation| - |----------|-----------| - |`api`|Grants full read/write access to the API, including all groups, projects, container registry, dependency proxy, and package registry. Required for API requests.| - |`read_api`|Allows read-only access to all groups, projects, container registry, and package registry.| - |`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.| - |`read_repository`|Enables read-only access to repositories in private projects via Git-over-HTTP or the Repository Files API.| - |`profile`|Grants read-only access to the user's profile data using OpenID Connect.| - |`email`|Provides read-only access to the user's primary email address using OpenID Connect.| + |Permission|Explanation| + |----------|-----------| + |`api`|Grants full read/write access to the API, including all groups, projects, container registry, dependency proxy, and package registry. Required for API requests.| + |`read_api`|Allows read-only access to all groups, projects, container registry, and package registry.| + |`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.| + |`read_repository`|Enables read-only access to repositories in private projects via Git-over-HTTP or the Repository Files API.| + |`profile`|Grants read-only access to the user's profile data using OpenID Connect.| + |`email`|Provides read-only access to the user's primary email address using OpenID Connect.| - 9. Click **Save Application** to finalize the setup. +9. Click **Save Application** to finalize the setup. From b3269da05be752402f856714c5e3fe37649b1375 Mon Sep 17 00:00:00 2001 From: danciaclara Date: Mon, 13 Oct 2025 18:44:02 +0530 Subject: [PATCH 4/4] minor fixes --- self-hosting/govern/integrations/gitlab.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/self-hosting/govern/integrations/gitlab.mdx b/self-hosting/govern/integrations/gitlab.mdx index 30799bd..d239d5b 100644 --- a/self-hosting/govern/integrations/gitlab.mdx +++ b/self-hosting/govern/integrations/gitlab.mdx @@ -42,8 +42,8 @@ After creating and configuring the GitLab application and configuring the instan 6. Enter the following **Redirect URI**, replacing [YOUR_DOMAIN] with your actual domain: ```bash https://[YOUR_DOMAIN]/silo/api/gitlab/auth/callback - ``` -7. Check the **Confidential** box.. + ``` +7. Check the **Confidential** box. ![Add app details](/images/integrations/gitlab/add-app-details.webp)