Integrate with GitLab

Pro

Integrating GitLab with Plane allows you to sync your development workflow seamlessly by linking GitLab merge requests with Plane work items. This connection enables automated updates and enhances collaboration between developers and project managers.

Plane supports integration with:

• GitLab.com
  The standard cloud-hosted GitLab service

• GitLab Self-managed
  Self-hosted GitLab instances for organizations with specific compliance or security requirements

This guide walks you through the steps to connect your GitLab account, link GitLab projects to Plane, and configure pull request automation.

Set up GitLab integration

Self-hosted Plane instance (Commercial Edition)

If you're running a self-hosted instance of Plane, you'll need to set up a few extra configurations to get GitLab integration working. Check out the setup guide first before diving into the steps on this page.

To get started, you'll need to connect your GitLab account, organization, and repositories with Plane. Follow the steps below to complete the setup:

1. Connect your GitLab organization
2. Connect GitLab project
3. Connect Plane project

Connect GitLab organization

Link your GitLab organization to your Plane workspace to start syncing repositories. This step is crucial for enabling the full range of GitLab-Plane integration.

GitLab.com

Self-hosted Plane instance (Commercial Edition)

If you're running a self-hosted instance of Plane, you'll need to set up a few extra configurations to get GitLab integration working. Check out the setup guide first before diving into the steps on this page.

1. Navigate to Workspace Settings in Plane.

2. Go to the Integrations tab.

3. Locate the GitLab integration section.

4. Click Connect to authenticate your GitLab account and initiate the connection.

   

5. Review the requested permissions and click Authorize Plane to grant access.

6. Once authenticated, you should see your GitLab account listed as connected.

GitLab Self-managed

Plane Cloud and self-hosted instances

Before you can integrate with GitLab Self-managed, you must first set up the necessary configurations in your GitLab instance. This is required for both Plane Cloud and self-hosted users.

Follow this setup guide first before diving into the steps on this section.

1. Navigate to Workspace settings in Plane.

2. On the right pane, select Integrations.

3. Find the GitLab Self-managed integration and click Configure.

4. In the Connect Organization section, click Connect.

   

5. Fill the form with the details of your GitLab self-managed instance and click Connect.

   

6. On the GitLab app installation page, choose the organization you want to connect.

7. Select whether you want to sync all repositories or pick specific ones.

8. Click Install to finalize the connection.

9. After authorization, you’ll be redirected back to Plane, where your GitLab organization will appear as connected.

At this stage, your GitLab account is linked to Plane, but you still need to connect specific GitLab projects to Plane projects.

Connect GitLab project

Connecting a GitLab project allows Plane to receive updates from that project via webhooks. These webhooks are essential for GitLab merge request automation.

To connect a GitLab project:

1. In the GitLab Project Connections section, click Add.

2. Select the GitLab Project you want to link.

3. Click Continue to confirm the selection.

Once connected, the GitLab project will be listed in the UI, confirming the integration.

Connect Plane project

After linking a GitLab project, the next step is to associate it with a Plane project. This connection ensures that Plane work items can be updated automatically based on GitLab merge request activities.

1. Select the Plane Project you want to connect.

2. In the Pull Request Automation section, set up rules for how Plane should update work item states based on merge request lifecycle events.

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.

   

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.

      

   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.

   

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.

   

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.

   

2. A new issue will automatically be created in the linked GitLab project.

   

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? for detailed information on property-level sync behavior

What gets synced?

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.

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

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.