From 6b4a8aa6b13045296deea1d13c2906ad8ce99f68 Mon Sep 17 00:00:00 2001 From: Saurabhkmr98 Date: Tue, 6 Jan 2026 20:20:34 +0530 Subject: [PATCH 1/2] add gitlab issue sync docs --- docs/integrations/github.mdx | 4 +- docs/integrations/gitlab.mdx | 98 ++++++++++++++++++++++++++++++++++++ 2 files changed, 100 insertions(+), 2 deletions(-) diff --git a/docs/integrations/github.mdx b/docs/integrations/github.mdx index 051892f..9557396 100644 --- a/docs/integrations/github.mdx +++ b/docs/integrations/github.mdx @@ -195,7 +195,7 @@ If you have existing work items in Plane that you want to sync to GitHub, you ca ### What gets synced? :::warning[important] -By default, syncing is unidirectional (GitHub → Plane only). Data from GitHub issues will overwrite corresponding data in Plane. Changes made in Plane will not sync back to GitHub unless you enable Bidirectional sync in your integration settings. +In unidirectional sync mode (GitHub → Plane only), data from GitHub issues will overwrite corresponding data in Plane. Changes made in Plane will not sync back to GitHub unless you enable Bidirectional sync in your integration settings. ::: Here’s what syncs automatically between Plane and GitHub: @@ -206,7 +206,7 @@ Here’s what syncs automatically between Plane and GitHub: | Description | Both ways | Content remains consistent between Plane and GitHub. | | Assignees | Both ways | Assigned users are mapped based on the initial setup. If a user isn’t mapped, the assignee field may be left empty. | | Labels | Both ways | If a Label doesn’t exist in Plane, it will be created (and vice versa). | -| States | GitHub → Plane | Changes in Plane do not update GitHub states. However, if an issue is closed in GitHub, it automatically moves to the Done state in Plane. | +| States | Both ways | Updates in either platform reflect in the other. | | Comments | Both ways | Comments sync between platforms with source attribution. If the commenter isn’t mapped to a Plane user, the comment appears as posted by the GitHub Bot. See [Connect personal GitHub account](/integrations/github#connect-personal-github-account) for more info. | | Mentions | Both ways | Mentioned users sync if they are mapped; otherwise, a GitHub profile link is included. | | Issue links | GitHub → Plane | Any issue references in GitHub descriptions or comments will be displayed in Plane with a direct link to the issue including the repository name and owner. | diff --git a/docs/integrations/gitlab.mdx b/docs/integrations/gitlab.mdx index 35f32c4..6d5054a 100644 --- a/docs/integrations/gitlab.mdx +++ b/docs/integrations/gitlab.mdx @@ -166,3 +166,101 @@ The lifecycle of a pull request can be mapped to workflow states in Plane. The f ### Work item backlinks in pull requests When a PR references Plane work items, Plane will post a confirmation comment on the pull request, ensuring visibility into which issues are linked. + +## Sync issues + +With the GitLab integration set up, you can sync issues between Plane and GitLab at the project level. This ensures GitLab issues and Plane work items stay synchronized within your configured GitLab Projects and Plane projects. + +### Add project work item sync +Once GitLab is connected to Plane, workspace admins can link GitLab Projects with Plane projects. + +1. Navigate to the **Project Issue Sync** section under **Integrations**. +2. Click the (+) button to create a new sync mapping. + + ![Sync project to GitLab](https://media.docs.plane.so/integrations/github/sync-project-github.webp#hero) +3. In the modal that appears, configure the following: + 1. **Plane project** + Select the Plane project you want to sync with. + 2. **GitLab Project** + Choose the GitLab Project to connect. + 3. **Project issue sync** + Map GitLab issue states to Plane states: + - Issue Open → Select a Plane state (e.g., Todo) + - Issue Closed → Select a Plane state (e.g., Done) + 4. **Select issue sync direction** + Choose how issues should sync: + - Unidirectional → Sync issues from GitLab to Plane only. + :::warning + This will overwrite Plane work item content with GitLab issue data. + ::: + - Bidirectional → Sync issues both ways between GitLab and Plane. + + ![Sync direction](https://media.docs.plane.so/integrations/github/sync-direction.webp#hero) + 5. Click **Start Sync**. + +All configured project issue syncs will appear in a list where you can edit or remove them as needed. + +### Sync issues to Plane +After configuring project work item sync, you can link existing GitLab issues into your Plane project. + +#### GitLab → Plane + +1. In your GitLab project, add the `Plane` label to any issue you want to sync. + + ![Add Plane label](https://media.docs.plane.so/integrations/github/add-plane-label.webp#hero) +2. The issue will automatically be created as a work item in the linked Plane project. +3. Plane posts a comment on the GitLab issue with a link to the newly created work item, confirming the connection. + + ![Synced issue from GitLab](https://media.docs.plane.so/integrations/github/synced-issue-from-github.webp#hero) +4. The work item in Plane will include a link back to the original GitLab issue. + + ![Creates issue in Plane](https://media.docs.plane.so/integrations/github/creates-plane-issue.webp#hero) + +### Sync work items to GitLab +If you have existing work items in Plane that you want to sync to GitLab, you can do so using labels. + +#### Plane → GitLab + +1. In your Plane project, add the `gitlab` label to any work item you want to sync. + + ![Add gitlab label](https://media.docs.plane.so/integrations/github/add-github-label.webp#hero) +2. A new issue will automatically be created in the linked GitLab project. + + ![Creates issue in GitLab](https://media.docs.plane.so/integrations/github/create-gitlab-issue.webp#hero) +3. The GitLab issue will be linked back to the Plane work item. +4. Future updates will sync according to your configured sync direction (unidirectional or bidirectional). + +### How issue syncing works + +#### State synchronization + +- When a GitLab issue is opened or closed, the corresponding Plane work item automatically moves to the mapped state. +- With bidirectional sync enabled, state changes in Plane work items will also update the GitLab issue status (open/closed). + +#### Creating synced issues + +- Issues created in GitLab (within a synced project) are automatically created in the linked Plane project. +- With bidirectional sync enabled, work items created in Plane (with the sync configured) are also created in GitLab. + +#### Continuous updates + +- All synced properties (title, description, labels, comments, etc.) update automatically based on your sync direction settings. +- See [What gets synced?](#what-gets-synced) for detailed information on property-level sync behavior + +### What gets synced? + +:::warning[important] +In unidirectional sync mode (GitLab → Plane only), data from GitLab issues will overwrite corresponding data in Plane. Changes made in Plane will not sync back to GitLab unless you enable Bidirectional sync in your integration settings. +::: + +Here’s what syncs automatically between Plane and GitLab: + +| Property   | Sync direction   | Notes | +| -------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Title | Both ways | Updates in either platform reflect in the other. | +| Description | Both ways | Content remains consistent between Plane and GitLab. | +| Labels | Both ways | If a Label doesn’t exist in Plane, it will be created (and vice versa). | +| States | Both ways | Updates in either platform reflect in the other. | +| Comments | Both ways | Comments sync between platforms with source attribution. The comment appears as posted by the Admin with the username of the user who posted the comment. +| Mentions | Both ways | Mentioned users username will be displayed in Plane and in the GitLab issue. | +| Issue links | GitLab → Plane | Any issue references in GitLab descriptions or comments will be displayed in Plane with a direct link to the issue including the project name and owner. | From 90addc3250bcae48138e5989ee35218e226c2be2 Mon Sep 17 00:00:00 2001 From: danciaclara Date: Tue, 13 Jan 2026 20:00:16 +0530 Subject: [PATCH 2/2] Minor content changes and added images --- docs/integrations/gitlab.mdx | 112 +++++++++++++++++------------------ 1 file changed, 56 insertions(+), 56 deletions(-) diff --git a/docs/integrations/gitlab.mdx b/docs/integrations/gitlab.mdx index 6d5054a..d85fb63 100644 --- a/docs/integrations/gitlab.mdx +++ b/docs/integrations/gitlab.mdx @@ -118,55 +118,6 @@ After linking a GitLab project, the next step is to associate it with a Plane pr 3. Once configured, you will see the project connection appear in the **Plane Project Connections** section. -## Configure PR state automation - -Pull requests (PRs) are also synchronized with Plane to ensure work item tracking remains accurate throughout the development lifecycle. - -To automate pull request state changes with Plane work items: - -1. Reference Plane work items in your GitLab PR title or description using the appropriate format. See [Reference formats](#reference-formats) below. -2. Automatic state updates will move the work item state in Plane based on the GitLab PR state defined in your mapping. - -#### Reference formats -There are two ways to reference Plane work items in your GitLab PRs: - -##### With brackets [WEB-344] - State automation - -- Links the work item to the PR -- Adds a comment from Plane App showing linked work items -- Automatically updates the work item state based on PR state changes (as configured in your PR state mapping) - -##### Without brackets WEB-344 - Link only - -- Links the work item to the PR as a reference -- Adds a comment from Plane App showing referenced work items -- Does not trigger automatic state updates - -*Example* -```bash -PR Title: [WEB-344] Add user authentication feature -PR Description: Implements login functionality for WEB-345 -``` - -In this example: -- WEB-344 will be fully automated (state changes with PR state) -- WEB-345 will be linked as a reference only (no state automation) - -### PR lifecycle mapping - -The lifecycle of a pull request can be mapped to workflow states in Plane. The following PR states are available for mapping: - -- A draft PR is created. -- A PR is opened. -- A review is requested. -- The PR is approved and ready to be merged. -- The PR is successfully merged. -- The PR is closed without merging. - -### Work item backlinks in pull requests - -When a PR references Plane work items, Plane will post a confirmation comment on the pull request, ensuring visibility into which issues are linked. - ## Sync issues With the GitLab integration set up, you can sync issues between Plane and GitLab at the project level. This ensures GitLab issues and Plane work items stay synchronized within your configured GitLab Projects and Plane projects. @@ -177,7 +128,7 @@ Once GitLab is connected to Plane, workspace admins can link GitLab Projects wit 1. Navigate to the **Project Issue Sync** section under **Integrations**. 2. Click the (+) button to create a new sync mapping. - ![Sync project to GitLab](https://media.docs.plane.so/integrations/github/sync-project-github.webp#hero) + ![Sync project to GitLab](https://media.docs.plane.so/integrations/gitlab/sync-project-gitlab.webp#hero) 3. In the modal that appears, configure the following: 1. **Plane project** Select the Plane project you want to sync with. @@ -195,7 +146,7 @@ Once GitLab is connected to Plane, workspace admins can link GitLab Projects wit ::: - Bidirectional → Sync issues both ways between GitLab and Plane. - ![Sync direction](https://media.docs.plane.so/integrations/github/sync-direction.webp#hero) + ![Sync direction](https://media.docs.plane.so/integrations/gitlab/sync-direction.webp#hero) 5. Click **Start Sync**. All configured project issue syncs will appear in a list where you can edit or remove them as needed. @@ -207,14 +158,13 @@ After configuring project work item sync, you can link existing GitLab issues in 1. In your GitLab project, add the `Plane` label to any issue you want to sync. - ![Add Plane label](https://media.docs.plane.so/integrations/github/add-plane-label.webp#hero) + ![Add Plane label](https://media.docs.plane.so/integrations/gitlab/add-plane-label.webp#hero) 2. The issue will automatically be created as a work item in the linked Plane project. 3. Plane posts a comment on the GitLab issue with a link to the newly created work item, confirming the connection. - ![Synced issue from GitLab](https://media.docs.plane.so/integrations/github/synced-issue-from-github.webp#hero) 4. The work item in Plane will include a link back to the original GitLab issue. - ![Creates issue in Plane](https://media.docs.plane.so/integrations/github/creates-plane-issue.webp#hero) + ![Creates issue in Plane](https://media.docs.plane.so/integrations/gitlab/creates-plane-issue.webp#hero) ### Sync work items to GitLab If you have existing work items in Plane that you want to sync to GitLab, you can do so using labels. @@ -223,10 +173,10 @@ If you have existing work items in Plane that you want to sync to GitLab, you ca 1. In your Plane project, add the `gitlab` label to any work item you want to sync. - ![Add gitlab label](https://media.docs.plane.so/integrations/github/add-github-label.webp#hero) + ![Add gitlab label](https://media.docs.plane.so/integrations/gitlab/add-gitlab-label.webp#hero) 2. A new issue will automatically be created in the linked GitLab project. - ![Creates issue in GitLab](https://media.docs.plane.so/integrations/github/create-gitlab-issue.webp#hero) + ![Creates issue in GitLab](https://media.docs.plane.so/integrations/gitlab/create-gitlab-issue.webp#hero) 3. The GitLab issue will be linked back to the Plane work item. 4. Future updates will sync according to your configured sync direction (unidirectional or bidirectional). @@ -264,3 +214,53 @@ Here’s what syncs automatically between Plane and GitLab: | Comments | Both ways | Comments sync between platforms with source attribution. The comment appears as posted by the Admin with the username of the user who posted the comment. | Mentions | Both ways | Mentioned users username will be displayed in Plane and in the GitLab issue. | | Issue links | GitLab → Plane | Any issue references in GitLab descriptions or comments will be displayed in Plane with a direct link to the issue including the project name and owner. | + + +## Configure PR state automation + +Pull requests (PRs) are also synchronized with Plane to ensure work item tracking remains accurate throughout the development lifecycle. + +To automate pull request state changes with Plane work items: + +1. Reference Plane work items in your GitLab PR title or description using the appropriate format. See [Reference formats](#reference-formats) below. +2. Automatic state updates will move the work item state in Plane based on the GitLab PR state defined in your mapping. + +#### Reference formats +There are two ways to reference Plane work items in your GitLab PRs: + +##### With brackets [WEB-344] - State automation + +- Links the work item to the PR +- Adds a comment from Plane App showing linked work items +- Automatically updates the work item state based on PR state changes (as configured in your PR state mapping) + +##### Without brackets WEB-344 - Link only + +- Links the work item to the PR as a reference +- Adds a comment from Plane App showing referenced work items +- Does not trigger automatic state updates + +*Example* +```bash +PR Title: [WEB-344] Add user authentication feature +PR Description: Implements login functionality for WEB-345 +``` + +In this example: +- WEB-344 will be fully automated (state changes with PR state) +- WEB-345 will be linked as a reference only (no state automation) + +### PR lifecycle mapping + +The lifecycle of a pull request can be mapped to workflow states in Plane. The following PR states are available for mapping: + +- A draft PR is created. +- A PR is opened. +- A review is requested. +- The PR is approved and ready to be merged. +- The PR is successfully merged. +- The PR is closed without merging. + +### Work item backlinks in pull requests + +When a PR references Plane work items, Plane will post a confirmation comment on the pull request, ensuring visibility into which issues are linked. \ No newline at end of file