GitLab integration

Integrate GitLab commits, branches, and merge requests with ClickUp tasks. This allows you to: 

  • See all GitLab activity related to a task in ClickUp. 
  • Optionally receive ClickUp notifications when new GitLab activity items are added to tasks.
  • Automatically or manually attach GitLab activity to ClickUp tasks
  • Automatically change statuses with GitLab actions by adding the ClickUp task ID to your commits using this format: #{taskID}[status].
    • Example: #1abc2de[closed]

What you'll need

  • The GitLab integration is available on every ClickUp plan.
  • Only Workspace owners and admins can set up integrations.
  • Guests can't use the GitLab integration.
  • The GitLab integration works with both on-premise and self-hosted versions of GitLab.

Personal and team repositories

The table below explains the differences between personal and team repositories.

Repository type Name in ClickUp Description
Personal My repositories from Gitlab

Repositories that you personally have access to in GitLab are displayed under the My repositories from Gitlab section.

The first step in setting up our GitLab integration is authorizing ClickUp's access to these repos so that you can bring them into your ClickUp Workspace's repos. Either HTTP or HTTPS is required to access your hosted servers.

Make sure to use the base URL of your GitLab server.

For example: https://gitlab.mycompany.com

For security purposes, we require all GitLab integrations that use a Self-Hosted GitLab instance to have a Top Level Domain (TLD). We do not allow IP addresses or domains that are not recognized as a Top Level Domain.

Team Gitlab repositories added to ClickUp

Repositories that your Workspace has access to display under the Gitlab repositories added to ClickUp. Repos here indicate that members of your Workspace have authorized them to be accessed by your entire ClickUp Workspace. 

In order to use GitLab repos in ClickUp, they must be added to your ClickUp Workspace repos.

Step 1: Authorize GitLab

You can authorize GitLab with gitlab.com or self-hosted GitLab.

Authorize with gitlab.com

To authorize with gitlab.com:

  1. Open the App Center.
  2. Search for and select GitLab.
  3. Select Manage.
  4. Click Activate Gitlab for Team.
  5. Click + Add Gitlab.
  6. Select No, I use gitlab.com.
  7. Click Link Gitlab.
  8. Click Authorize. You must authorize ClickUp to associate GitLab activity with ClickUp tasks.

Authorize with self-hosted GitLab

To authorize with self-hosted GitLab:

  1. Open the App Center.
  2. Search for and select GitLab.
  3. Select Manage.
  4. Click Activate Gitlab for Team.
  5. Click + Add Gitlab.
  6. Select Yes, I use a hosted version of Gitlab.
  7. Paste your GitLab URL into the Host url text box.
  8. Follow the directions to find, copy, and paste your personal access token into the Access token text box.

    If your team is behind a firewall, include your static IP address in your firewall allow list before integrating. This static IP address will be displayed at this step.

  9. Click Link Gitlab.
  10. Click Authorize. You must authorize ClickUp to associate GitLab activity with ClickUp tasks.

For security purposes, we require all GitLab integrations that use a self-hosted GitLab instance to have a Top Level Domain (TLD). The URL cannot have a port number appended to it. We do not allow IP addresses or domains not recognized as a Top Level Domain. An example of a valid URL would be https://gitlab.clickup.com.

Step 2: Add personal repositories to ClickUp

Multiple people can authorize GitLab within your Workspace. You can customize which repositories are shared with your Workspace, allowing you to authorize your personal account without attaching all of your repositories.

Attaching a repository does not give users access to your repository's codebase. It allows users to attach history items for that repository to the Spaces you specify. 

To add a repository to ClickUp:

  1. In the App Center, search for and select GitLab.
  2. Click Manage.
  3. Repositories are listed in the My repositories from Gitlab section.
  4. To the right of the repository you want to add, click + Add to ClickUp.

Screenshot of someone adding a repository to ClickUp.

Step 3: Select which Spaces are attached to your repositories 

Added repositories are listed in the Gitlab repositories added to ClickUp section in the lower-right.

To attach a repository to a ClickUp Space, click the dropdown to the right of the repository name and select one or more Spaces.

The repository must be attached to a Space before you can attach GitLab items to tasks.

Screenshot of someone selecting ClickUp Spaces for a repository.

Automatically associate GitLab activity in ClickUp 

ClickUp can automatically associate new GitLab activity with tasks.

To do so, add a ClickUp task ID in any part of the merge request title, branch name, or commit message in one of these formats:

#{task_id}

CU-{task_id}

{custom_task_id}

#{custom_task_id}

For example:

#1abc2de

CU-1abc2de

prefix-1

#prefix-1

Manually associate GitLab commits

To manually associate a GitLab commit with a ClickUp task:

  1. Open a task and click the GitLab icon.
  2. Click the Commits tab.
  3. Use the dropdown menu next to New Merge Request to select a Repo.
  4. Use the Select Branch dropdown to select a Branch.
  5. Attach your commit.

Screenshot of someone manually associating a GitLab commit with a ClickUp task.

Manually associate GitLab branches

To manually associate a GitLab branch:

  1. Open a task and click the GitLab icon.
  2. Click the Branches tab.
  3. Use the dropdown menu next to New Merge Request to select a Repo.
  4. Use the Select Branch dropdown to attach a Branch.

Screenshot of someone attaching a branch.

Automatically change task statuses from GitLab 

You can change the status of a task from a commit, issue, or merge request:

  1. Add the ClickUp task ID to any part of the commit message and include the status you want inside square brackets.
    • For example: #u7hu[staged]

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

  2. The task's status will change.

Create new branches from ClickUp

Create new branches using quick actions in ClickUp:

  1. Open a task and click the GitLab icon.
  2. To the left, there are several auto-generated quick copy options. If you prefer to create a new branch directly in GitLab, click Create Branch in the lower-left corner of the modal.

Screenshot of someone creating a new branch from ClickUp.

Customize auto-generated branch names

You can customize the auto-generated branch names formatting used in quick actions:

  1. From the App Center, select GitLab.
  2. Under Auto-generated branch names format, make edits.Screenshot of someone changing the auto-generated branch format.
  3. In the lower-right, click Save.

Create merge requests from ClickUp

Create or link merge requests from ClickUp.

To create a new merge request:

  1. Open a task and click the GitLab icon.
  2. In the lower-left of the modal, click New Merge Request.
  3. Use the pre-made merge request title or create your own.
  4. Select a repository, source branch, and target branch.
  5. Enter a description.
  6. Create the merge request by clicking New Merge Request.

Once you create or merge a request in ClickUp, a link to the associated ClickUp task is automatically added to the merge request in GitLab.

Screenshot of someone creating a marge request from ClickUp.

After a merge request is linked, you can see who opened it, the reviewer, CI/CD status, and merge request status from within the linked ClickUp task.

Connection issues

If you accidentally connected the wrong GitLab account or if there's an issue with the connection, you can disconnect and reconnect your repos or your entire account.

Need to troubleshoot with a GitLab representative? Request GitLab's customer support here.

Remove the GitLab integration

Only Workspace owners and admins can remove the GitLab integration.

To remove the GitLab integration:

  1. From the App Center, select GitLab.
  2. In the lower-right, click Remove Gitlab.

Was this article helpful?