Link Spaces directly with GitLab projects so you always know what work is related.

Tasks in Spaces with a connected project can be linked with commits, branches, and merge requests.

What you'll need

• The GitLab integration is available on all ClickUp plans.
• Only Workspace owners and admins can add Gitlab projects in the App Center.
• Workspace owners and admins can connect Spaces to their projects, allowing members to add their GitLab work to tasks.
• Only Workspace owners and admins can create Workspace connections. Multiple Workspace connections are allowed.
• Members and above can create personal connections.

• Guests and limited members can't use the GitLab integration.

Connection types

The features and commands available depend on which type of connection you use.

ClickUp commands for GitLab are available only for personal connections. The data is not linked to Workspace connections. When a user has a personal connection enabled and runs a GitLab command, they will see a list of options, like project lists, that they are authorized to view in GitLab.

Set up the integration

There are three required steps to set up the GitLab integration in ClickUp:

1. Connect GitLab.
2. Attach GitLab projects to your Workspace.
   

   Projects are needed so ClickUp can automatically link merge requests to their respective ClickUp tasks.

3. Link GitLab projects to ClickUp Spaces.
4. Optionally, you can set a custom branch name format.

Step 1: Connect GitLab

To connect GitLab from the App Center:

1. Search for and select GitLab.
2. Depending on the type of connection you want, select the Personal or Workspace tab.
3. Choose how you want to authorize:
   • GitLab account: Authorize using your GitLab.com account.
   • Self-hosted version: Authorize using a custom GitLab URL.
4. Click Next.
5. Authorize ClickUp.
6. Click Done.

Step 2: Attach GitLab projects to your Workspace

Only the connection owner can add projects. Attaching a project does not give ClickUp users access to your repo's codebase.

To ensure all GitLab projects are displayed in the App Center, set individual permissions for each project instead of using group permissions.

To add a project to a Workspace:

1. In the App Center, search for and select GitLab.
2. In the upper-right, click Settings.
3. Under Connect Projects to Spaces, click Add project.
4. Select the project you want to add.
5. Repeat the above steps to add more projects.

If you don't see the correct projects, ensure you have signed in to the right account. A Workspace owner or admin must select each project to connect. Linked projects can be viewed in the App Center.

Step 3: Link GitLab projects to ClickUp Spaces

After adding projects to your Workspace, an admin can add each project to one or more Spaces. Each ClickUp Space can have multiple projects added.

You can add or remove projects from Spaces at any time.

To link a project to a Space:

1. In the App Center, search for and select GitLab.
2. In the upper-right, click Settings.
3. Under Connect Projects to Spaces, click the name of the project you want to link.
4. Click Add Space and select a Space. Repeat this step to add more Spaces.

Set your branch name format

If your organization uses a specific format for branch names, you can set it from the GitLab page in the App Center. When people create branches from ClickUp tasks, it will use this format.

The default format is: :taskId:_:taskName:_:username:

For example: CU-ae27de_Auto-generated-naming_John-smith

The available options are shown in the following table:

To set your default name format from GitLab in the App Center:

1. Search for and select GitLab.
2. In the upper-right, click Settings.
3. Under Auto-generated branch name, enter your preferred branch name format.
4. Click Save.

Link tasks from GitLab

ClickUp automatically associates new GitLab activity with tasks if you include a valid ClickUp task ID in any part of the merge request title, merge request description, branch name, or commit message.

When a ClickUp task ID is included in a merge request, a comment with a link to the ClickUp task will be posted in the merge request. A link will not display when manually pasting a merge request into a ClickUp task.

The comment will be posted using the GitLab account of the person who set up the project and Space mapping.

The task ID must be formatted using one of these options:

#{task_id}

CU-{task_id}

{custom_task_id}

#{custom_task_id}

For example:

#1abc2de

CU-1abc2de

eng-123

#eng-123

Link tasks from ClickUp

You can also manually link ClickUp tasks with GitLab commits, branches, and merge requests from the ClickUp task. Ensure the task is located in a Space that is linked to a project.

To link a task:

1. Open a task and click the GitLab icon on the right.
2. On the right, you'll see suggested branch names and commit messages that you can copy to your clipboard. You can also copy the task ID from here.
3. In the lower-right corner, click Add GitLab link.
   
4. Paste a link.
5. In the lower-right corner, click Add.

ClickUp task activity

The task activity feed sometimes collapses similar activity items to ensure you see the most important details.

You can take the following actions to locate GitLab activity:

• Click More updates to reveal activity that has been hidden.
• When a branch is merged, commits display as a single activity item in the task's activity feed.
  • Click the link to all the commits to open a menu.
  • Click an individual commit to open it in GitLab.
• Filter task activity by Git items.

Missing activity 

If you can't locate certain activity, ensure that you're correctly referencing the ClickUp task ID to link activity in GitLab. You can use any of these three options to reference your ClickUp tasks on commits, branch names, and merge requests:

#{task_id}

CU-{task_id}

{custom_task_id}

For example:

#1abc2de

CU-1abc2de

prefix-1

You can manually link ClickUp tasks to GitLab commits, branches, and merge requests from the ClickUp task.

GitLab link previews

When you paste a GitLab link into a ClickUp task, Chat, or Doc, you'll see the option to paste it as a preview, mention, or URL.

Create GitLab issues, branches, and merge requests from ClickUp

You can also create new issues, branches, and merge requests directly from tasks. Ensure the task is located in a Space that is linked to a project.

To create an issue, branch, or merge request:

1. Open a task and click the GitLab icon.
2. On the right, you'll see suggested branch names and commit messages you can copy to your clipboard. You can also copy the task ID from here.
3. In the lower-right corner, click Add GitLab link.
4. Choose one of the following options:
   • New GitLab Branch
   • New GitLab Merge Request
   • New GitLab Issue
5. Name the branch, merge request, or issue.
6. Select a project and fill out the information. Add a source branch and destination branch if applicable.
7. In the lower-right corner, click Create.

GitLab App panel in tasks

After you paste your first GitLab link in a task description or comment, you'll see a new GitLab icon in the right sidebar of any tasks that live in Spaces that are connected to projects. You can click this icon at any time to see every GitLab link posted in the task.

GitLab task activity uses the person's ClickUp username, or their GitLab username if they don't have a ClickUp account.

Update task statuses from GitLab

You can update the status of a ClickUp task when you link a commit, push a commit, or create a merge request. ClickUp automatically picks up new GitLab activity and associates it with tasks if you include a valid task ID in any part of the merge request title, merge request description, branch name, or commit message.

The task ID must be formatted using one of these options:

#{task_id}[status]

CU-{task_id}[status]

{custom_task_id}[status]

#{custom_task_id}[status]

To update a task status:

1. Add the ClickUp task ID in any part of the commit or merge request message.
2. Include the updated task status in square brackets.

For example: #ud5b[ready]

All formats listed in the Link tasks from GitLab section of this article can be used. To ensure proper formatting, do not add a space between the task ID and status information.

Manage GitLab issues, branches, merge requests, and commits from ClickUp

After you link issues, branches, merge requests, or commits, they display on the right side of your task when you click the GitLab icon. Use the ellipsis ... menu to copy the link or delete the item.

If you've joined the Workspace as a guest, you won't be able to use the GitLab integration. Contact your Workspace owner or admin to request an upgrade to a Workspace member.

Once you link a GitLab item, the following information is displayed in your ClickUp task:

Issue information

After an issue is linked, you can see the following details:

• The person who opened the issue, known as the author
• Project
• The issue status
• URL

Branch information

After a branch is linked, you can see the following details:

• The person who created the branch, known as the author
• Link creator
• Project
• URL

Merge request information

After a merge request is linked, you can see the following details:

• The person who opened the merge request, known as the author
• Any assigned reviewers
• Project
• The merge request status
• URL

Commit information

After a commit is linked, you can see the following details:

• The person who created the commit, known as the author
• Line changes
• Project
• URL

Add your GitLab account to ClickUp

Workspace members can link their GitLab accounts to their ClickUp account in advance or when they create a branch or merge request.

To add your GitLab account from the App Center:

1. Search for and select GitLab.
2. Next to Create a personal connection, click Connect.
3. Sign in to GitLab and authorize ClickUp.
4. Click Done.

View merge requests in List or Table view

Add the Pull Requests column to any List view or Table view to quickly view your GitLab merge requests.

Connection issues

Sometimes, the wrong GitLab account is linked or there is an issue with the connection. In this scenario, you can try disconnecting and reconnecting your projects or entire account.

These actions do not impact anyone's ability to access projects using their GitLab account through GitLab.

To disconnect a project:

1. From the App Center, select GitLab.
2. In the upper-right corner, click Settings.
3. Under Project, click the ellipsis ... menu to the right of the project.
4. Click Delete from ClickUp.

The section below includes instructions for disconnecting your entire account.

Disconnect the GitLab integration

If you no longer need to access GitLab files in ClickUp, you can disconnect the integration from your Workspace.

Only owners and admins can disconnect Workspace connections.

From the App Center:

1. Search for and select GitLab.
2. Select the Workspace tab.
3. Next to Connected, click the ellipsis ... menu.
4. Select Disconnect.
5. To confirm, click Disconnect.