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..d85fb63 100644 --- a/docs/integrations/gitlab.mdx +++ b/docs/integrations/gitlab.mdx @@ -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). + +### 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. | + + ## Configure PR state automation 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 ### 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. \ No newline at end of file