Skip to content

Commit cfe1ed9

Browse files
danciaclaradanciaclara
authored
Merge pull request #388 from makeplane/feat-gitlab_issue_sync
[SILO-821] feat: add gitlab issue sync docs
2 parents 9b7d268 + 90addc3 commit cfe1ed9

2 files changed

Lines changed: 101 additions & 3 deletions

File tree

‎docs/integrations/github.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -195,7 +195,7 @@ If you have existing work items in Plane that you want to sync to GitHub, you ca
195195
### What gets synced?
196196

197197
:::warning[important]
198-
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.
198+
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.
199199
:::
200200

201201
Here’s what syncs automatically between Plane and GitHub:
@@ -206,7 +206,7 @@ Here’s what syncs automatically between Plane and GitHub:
206206
| Description | Both ways | Content remains consistent between Plane and GitHub. |
207207
| 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. |
208208
| Labels | Both ways | If a Label doesn’t exist in Plane, it will be created (and vice versa). |
209-
| 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. |
209+
| States | Both ways | Updates in either platform reflect in the other. |
210210
| 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. |
211211
| Mentions | Both ways | Mentioned users sync if they are mapped; otherwise, a GitHub profile link is included. |
212212
| 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. |

‎docs/integrations/gitlab.mdx‎

Lines changed: 99 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,104 @@ After linking a GitLab project, the next step is to associate it with a Plane pr
118118

119119
3. Once configured, you will see the project connection appear in the **Plane Project Connections** section.
120120

121+
## Sync issues
122+
123+
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.
124+
125+
### Add project work item sync
126+
Once GitLab is connected to Plane, workspace admins can link GitLab Projects with Plane projects.
127+
128+
1. Navigate to the **Project Issue Sync** section under **Integrations**.
129+
2. Click the (+) button to create a new sync mapping.
130+
131+
![Sync project to GitLab](https://media.docs.plane.so/integrations/gitlab/sync-project-gitlab.webp#hero)
132+
3. In the modal that appears, configure the following:
133+
1. **Plane project**
134+
Select the Plane project you want to sync with.
135+
2. **GitLab Project**
136+
Choose the GitLab Project to connect.
137+
3. **Project issue sync**
138+
Map GitLab issue states to Plane states:
139+
- Issue Open → Select a Plane state (e.g., Todo)
140+
- Issue Closed → Select a Plane state (e.g., Done)
141+
4. **Select issue sync direction**
142+
Choose how issues should sync:
143+
- Unidirectional → Sync issues from GitLab to Plane only.
144+
:::warning
145+
This will overwrite Plane work item content with GitLab issue data.
146+
:::
147+
- Bidirectional → Sync issues both ways between GitLab and Plane.
148+
149+
![Sync direction](https://media.docs.plane.so/integrations/gitlab/sync-direction.webp#hero)
150+
5. Click **Start Sync**.
151+
152+
All configured project issue syncs will appear in a list where you can edit or remove them as needed.
153+
154+
### Sync issues to Plane
155+
After configuring project work item sync, you can link existing GitLab issues into your Plane project.
156+
157+
#### GitLab → Plane
158+
159+
1. In your GitLab project, add the `Plane` label to any issue you want to sync.
160+
161+
![Add Plane label](https://media.docs.plane.so/integrations/gitlab/add-plane-label.webp#hero)
162+
2. The issue will automatically be created as a work item in the linked Plane project.
163+
3. Plane posts a comment on the GitLab issue with a link to the newly created work item, confirming the connection.
164+
165+
4. The work item in Plane will include a link back to the original GitLab issue.
166+
167+
![Creates issue in Plane](https://media.docs.plane.so/integrations/gitlab/creates-plane-issue.webp#hero)
168+
169+
### Sync work items to GitLab
170+
If you have existing work items in Plane that you want to sync to GitLab, you can do so using labels.
171+
172+
#### Plane → GitLab
173+
174+
1. In your Plane project, add the `gitlab` label to any work item you want to sync.
175+
176+
![Add gitlab label](https://media.docs.plane.so/integrations/gitlab/add-gitlab-label.webp#hero)
177+
2. A new issue will automatically be created in the linked GitLab project.
178+
179+
![Creates issue in GitLab](https://media.docs.plane.so/integrations/gitlab/create-gitlab-issue.webp#hero)
180+
3. The GitLab issue will be linked back to the Plane work item.
181+
4. Future updates will sync according to your configured sync direction (unidirectional or bidirectional).
182+
183+
### How issue syncing works
184+
185+
#### State synchronization
186+
187+
- When a GitLab issue is opened or closed, the corresponding Plane work item automatically moves to the mapped state.
188+
- With bidirectional sync enabled, state changes in Plane work items will also update the GitLab issue status (open/closed).
189+
190+
#### Creating synced issues
191+
192+
- Issues created in GitLab (within a synced project) are automatically created in the linked Plane project.
193+
- With bidirectional sync enabled, work items created in Plane (with the sync configured) are also created in GitLab.
194+
195+
#### Continuous updates
196+
197+
- All synced properties (title, description, labels, comments, etc.) update automatically based on your sync direction settings.
198+
- See [What gets synced?](#what-gets-synced) for detailed information on property-level sync behavior
199+
200+
### What gets synced?
201+
202+
:::warning[important]
203+
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.
204+
:::
205+
206+
Here’s what syncs automatically between Plane and GitLab:
207+
208+
| Property   | Sync direction   | Notes |
209+
| -------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
210+
| Title | Both ways | Updates in either platform reflect in the other. |
211+
| Description | Both ways | Content remains consistent between Plane and GitLab. |
212+
| Labels | Both ways | If a Label doesn’t exist in Plane, it will be created (and vice versa). |
213+
| States | Both ways | Updates in either platform reflect in the other. |
214+
| 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.
215+
| Mentions | Both ways | Mentioned users username will be displayed in Plane and in the GitLab issue. |
216+
| 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. |
217+
218+
121219
## Configure PR state automation
122220

123221
Pull requests (PRs) are also synchronized with Plane to ensure work item tracking remains accurate throughout the development lifecycle.
@@ -165,4 +263,4 @@ The lifecycle of a pull request can be mapped to workflow states in Plane. The f
165263

166264
### Work item backlinks in pull requests
167265

168-
When a PR references Plane work items, Plane will post a confirmation comment on the pull request, ensuring visibility into which issues are linked.
266+
When a PR references Plane work items, Plane will post a confirmation comment on the pull request, ensuring visibility into which issues are linked.

0 commit comments

Comments
 (0)