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.

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.