Skip to content

[SILO-821] feat: add gitlab issue sync docs #388

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
danciaclara merged 2 commits into from
Jan 13, 2026
+101 −3
Merged

[SILO-821] feat: add gitlab issue sync docs #388

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6b4a8aa
add gitlab issue sync docs
Saurabhkmr98 Jan 6, 2026
90addc3
Minor content changes and added images
danciaclara Jan 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/integrations/github.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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. |
Expand Down
100 changes: 99 additions & 1 deletion docs/integrations/gitlab.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,104 @@ 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.

## 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/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.
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/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.

### 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/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.

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/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.

#### 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/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/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).

Comment on lines +154 to +182
Copy link

@coderabbitai coderabbitai bot Jan 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# First, run the provided consistency check
rg -nP '`Plane`|`gitlab`|label' docs/integrations/gitlab.mdx

Repository: makeplane/docs

Length of output: 822

🏁 Script executed:

#!/bin/bash
# Search for GitLab integration label handling in the codebase
# Look for files related to GitLab sync implementation
fd -e py -e ts -e tsx -e js -e jsx | xargs rg -l "gitlab.*label|label.*gitlab" -i | head -20

Repository: makeplane/docs

Length of output: 40

🏁 Script executed:

#!/bin/bash
# Search specifically for where these labels are validated/checked
rg -i "plane.*label|gitlab.*label" --type py --type ts --type tsx --type js --type jsx -A 5 -B 5 | head -100

Repository: makeplane/docs

Length of output: 85

🏁 Script executed:

#!/bin/bash
# Search for GitLab sync implementation - label handling in the main plane repo
# Look for files that handle GitLab issue/label sync
find . -type f \( -name "*.py" -o -name "*.ts" -o -name "*.js" \) | xargs rg -l "gitlab.*sync|label.*sync" -i 2>/dev/null | grep -E "(gitlab|integration)" | head -20

Repository: makeplane/docs

Length of output: 40

🏁 Script executed:

#!/bin/bash
# Search for where "Plane" label is checked/validated
rg -i "plane.*label\"|label.*plane\"|\"Plane\"" --type py --type js -A 3 -B 3 2>/dev/null | head -150

Repository: makeplane/docs

Length of output: 40

🏁 Script executed:

#!/bin/bash
# Search for GitLab label trigger constants or configuration
rg -E "(PLANE_LABEL|GITLAB_LABEL|trigger.*label)" --type py --type js -i -A 2 -B 2 2>/dev/null

Repository: makeplane/docs

Length of output: 40

🏁 Script executed:

#!/bin/bash
# Search entire docs repo for mentions of case-sensitivity, customization, or pre-existing labels
rg -i "case.?sensitive|customiz|pre.?exist|must exist|required" docs/ -A 2 -B 2

Repository: makeplane/docs

Length of output: 36018

🏁 Script executed:

#!/bin/bash
# Look at the full GitLab integration doc to see if there's more context
head -n 250 docs/integrations/gitlab.mdx | tail -n 50

Repository: makeplane/docs

Length of output: 4416

🏁 Script executed:

#!/bin/bash
# Check if there are other similar integration docs that explain label behavior
ls -la docs/integrations/

Repository: makeplane/docs

Length of output: 544

🏁 Script executed:

#!/bin/bash
# Search for any configuration or FAQ sections about labels
rg -i "label.*behavior|label.*work|sync.*label|how.*label" docs/ --type mdx -A 3

Repository: makeplane/docs

Length of output: 85

Document the behavior of trigger labels (Plane and gitlab) — docs don't explain if they're case-sensitive or customizable.

The documentation presents these as required "magic" labels but doesn't clarify: whether they're case-sensitive (the inconsistent casing Plane vs gitlab suggests they are), whether they can be customized in settings, or whether they must pre-exist. Users will fail silently if they use Gitlab or plane instead. Add a note explaining exact label requirements, case-sensitivity, and whether labels can be customized or auto-created.

🧰 Tools
🪛 LanguageTool

[style] ~174-~174: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...the gitlab label to any work item you want to sync. ![Add gitlab label](https:...

(REP_WANT_TO_VB)

🤖 Prompt for AI Agents 
In @docs/integrations/gitlab.mdx around lines 154 - 182, The docs don’t explain
the exact behavior of the trigger labels, so add a short clarifying note under
the GitLab sync sections explaining whether the label names 'Plane' and 'gitlab'
are case-sensitive, whether they can be changed in settings, and whether the
integration will auto-create labels or requires them to pre-exist; specifically
state the canonical forms ('Plane' and 'gitlab'), the accepted case behavior
(e.g., case-sensitive or normalized), and whether admins can customize the
trigger label or must create it manually in GitLab for syncing to work.

### 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. |
Comment on lines +208 to +216
Copy link

@coderabbitai coderabbitai bot Jan 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

# First, check the file exists and view the relevant section
head -220 docs/integrations/gitlab.mdx | tail -30

Repository: makeplane/docs

Length of output: 3692

🏁 Script executed:

# Also search for any other mentions of comment attribution behavior in the docs
rg "comment.*admin\|admin.*comment" -i docs/integrations/gitlab.mdx -A 2 -B 2

Repository: makeplane/docs

Length of output: 40

🏁 Script executed:

# Search for implementation details about GitLab integration and comment syncing
fd -e py -e ts -e js -e tsx | xargs rg -l "gitlab.*comment\|comment.*gitlab" -i | head -5

Repository: makeplane/docs

Length of output: 40

🏁 Script executed:

# Search for GitLab integration implementation in the codebase
fd -type f \( -name "*.py" -o -name "*.ts" -o -name "*.tsx" -o -name "*.js" \) | xargs rg -l "gitlab" -i | grep -E "(integr|sync)" | head -10

Repository: makeplane/docs

Length of output: 302

🏁 Script executed:

# Broader search for comment sync or attribution logic
rg "comment.*sync\|sync.*comment" -i -A 3 -B 1 --max-count 10 | head -50

Repository: makeplane/docs

Length of output: 40

🏁 Script executed:

# Look for any integration-related files
fd -type d -name "*integr*" -o -name "*gitlab*"

Repository: makeplane/docs

Length of output: 228

🌐 Web query:

Plane GitLab integration comment attribution how comments are displayed

💡 Result:

Short answer: Plane syncs comments with GitLab and shows an attribution for the source; comments created by GitLab (e.g., MR/issue comments or the Plane backlink comment on an MR) are displayed in Plane with their source noted, and Plane will attribute comments to the mapped Plane user when a GitLab account is mapped — otherwise the comment appears as coming from the integration/bot. You can also create/sync comments via Plane’s API using external_source/external_id fields so imported comments retain external attribution.

Sources:

  • Plane GitLab integration docs (integration behavior, PR backlinks and Plane comments on MRs). [1]
  • Plane GitHub integration docs (comments sync both ways with source attribution; unmapped users show as the platform bot). [2]
  • Plane API comment endpoints (comment_html, external_source, external_id fields used when creating/syncing comments). [3]

References:
[1] Plane — Integrate GitLab.
[2] Plane — Integrate GitHub (comments sync & attribution).
[3] Plane API — Create work item comment (external_source / external_id).

🌐 Web query:

Plane project sync GitLab comments admin attribution

💡 Result:

Short answer: Plane syncs GitLab comments and posts its own “Plane App” comment when work items/PRs are linked; comments are attributed to the original GitLab user only if that GitLab account is mapped to a Plane workspace user — otherwise the comment will be shown as coming from the integration/bot (or the Plane/GitHub bot example). To avoid comments showing as an admin/bot, map users or connect personal accounts so Plane can attribute comments to the correct user. [1][2]

What to do (concise):

  1. Connect GitLab to Plane (workspace Integrations → GitLab) and add the GitLab project connection. This enables webhooks and comment/PR sync. [2]
  2. Ensure each GitLab commenter has a matching Plane workspace account (or have them “Connect personal GitLab account” in Plane) so Plane can map GitLab identities to Plane users. If a GitLab user isn’t mapped, Plane will post/sync comments as the integration/bot. [1][2]
  3. If you must use a shared admin/service account for the integration, expect comments created by that account (or unmapped users) to be attributed to the integration/admin in Plane; instead prefer per-user OAuth connections or invite users to Plane and map identities. [1][2]
  4. If you run a self-managed GitLab and need Org-level admin actions, use the GitLab Admin area to manage user accounts and confirm the accounts exist and can be matched to Plane users. [3]

Sources:

  • Plane — GitLab integration (setup, PR/work-item linking, comment/backlink behavior). [1][2]
  • GitLab — Admin area docs (managing self-hosted users/projects). [3]

References:
[1] Plane — “What gets synced?” / comment attribution notes.
[2] Plane — Integrate with GitLab (connect org/project, PR automation, work item backlinks).
[3] GitLab — Admin area (self‑managed user/project administration).

Fix grammar/clarity issues and correct the misleading comment attribution statement.

The "Mentioned users' usernames" needs proper possessive plural form. More importantly, the Comments row incorrectly claims "appears as posted by the Admin"—in reality, synced comments are attributed to the mapped Plane user if a GitLab-to-Plane user mapping exists; otherwise they appear as coming from the integration bot. This should be clarified rather than vague.

Suggested revisions 
-| 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.                                                                                                                                                              |
+| Comments             | Both ways                       | Comments sync between platforms with source attribution. Comments are attributed to the mapped Plane user; if no mapping exists, they appear as posted by the integration bot. |
+| Mentions             | Both ways                       | Mentioned users' usernames are displayed in Plane and in the GitLab issue. |
🤖 Prompt for AI Agents 
In @docs/integrations/gitlab.mdx around lines 208 - 216, Update the table rows
for "Mentions" and "Comments": change "Mentioned users username" to the correct
possessive plural "Mentioned users' usernames"; and replace the vague "appears
as posted by the Admin with the username of the user who posted the comment" in
the "Comments" row with a clear statement that synced comments are attributed to
the mapped Plane user when a GitLab→Plane user mapping exists, otherwise they
are posted by the integration bot (include “with source attribution” if
desired).



## Configure PR state automation

Pull requests (PRs) are also synchronized with Plane to ensure work item tracking remains accurate throughout the development lifecycle.
Expand Down Expand Up @@ -165,4 +263,4 @@ 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.
When a PR references Plane work items, Plane will post a confirmation comment on the pull request, ensuring visibility into which issues are linked.