All integrations

GitLab integration

Link merge requests, branches, and commits to tasks on GitLab.com or your own GitLab server

Overview

The Vaiz GitLab integration connects your GitLab projects to Vaiz tasks. Link merge requests, branches, and commits to a task, follow their activity right in the task, and create branches without leaving Vaiz.

You don't have to link everything by hand. When a merge request, branch, or commit mentions a task key such as APP-123, Vaiz links it to that task automatically.

The integration works with both GitLab.com and self-managed GitLab. You can connect several GitLab accounts and instances to one Vaiz Space.

Key benefits:

  • Automatic linking — Merge requests, branches, and commits that mention a task key are linked to the task
  • Full visibility — See linked merge requests, branches, and commits in the task's Repository field
  • Create branches from tasks — New branches are named after the task key and linked to the task
  • Two-way activity — Merge request comments and updates appear in the task, and task status changes are posted on linked merge requests
  • Automations — Run board automations when a merge request is opened, merged, or closed

How to install

  1. Sign in to your Vaiz account and open your Space
  2. Navigate to App Center → GitLab and click Connect
  3. Choose where your GitLab is hosted:
    • GitLab.com — click Continue to GitLab and authorize Vaiz
    • Self-managed — create an OAuth application in your GitLab with the api scope and the redirect URI shown in Vaiz, then enter your instance URL, Application ID, and Secret, and authorize Vaiz
  4. In the Projects section, select the GitLab projects you want to connect to the Space

The list shows projects where you have the Maintainer role or higher. Vaiz adds a webhook to each connected project to keep links up to date, and GitLab only lets maintainers manage webhooks.

For a step-by-step walkthrough, see How to set up the GitLab integration in Vaiz.

Key features

After GitLab is connected, every task has a Repository field. Click +, choose a project, and open the MR, Branch, or Commit tab to search and link an item. Hover over a linked item to see its details, open it in GitLab, copy its link, or unlink it.

Projects are grouped by provider, so GitLab.com projects, self-managed instances, and GitHub repositories each appear in their own group.

When Auto-link by task key is on, Vaiz looks for task keys such as APP-123 in:

  • the title, description, and source branch of a merge request
  • the name of a pushed branch
  • the messages of pushed commits

A branch named APP-123-login-form or a commit message APP-123 Fix the login form is linked to task APP-123. Keys are not case-sensitive, a merge request that mentions several tasks is linked to each of them, closed merge requests are not linked automatically, and existing links are never removed.

3. Create a branch from a task

In the task's Repository field, open the Create branch tab, choose the project and the base branch, and click Create. The branch name defaults to the task key, so the new branch is linked to the task.

4. Follow merge request activity

  • MR Comments & Activity — The task shows when a linked merge request is opened, gets new commits, is marked as ready or as a draft, is merged, closed, or reopened. Comments from the merge request appear in the task too.
  • Task Activity to MRs — Vaiz posts a comment on each linked merge request when the task status changes, so reviewers can see task progress in GitLab.

Both settings, along with Auto-link by task key, are on by default and have their own toggles on the GitLab page in the App Center.

5. React to merge requests in automations

Board automations can react when a merge request is opened, merged, or closed, so tasks can move forward as code gets reviewed and shipped.

Permissions and data access

Vaiz requests the GitLab api scope so it can read your projects, add webhooks to connected projects, and create branches. Only projects you connect in the App Center are used for linking.

Disconnection and cleanup

  1. Go to App Center → GitLab
  2. Click the three-dot menu next to the account and select Disconnect

Vaiz removes its webhooks from the connected projects. Links already added to tasks stay in place but no longer receive status updates or comments. To revoke access on the GitLab side, open Preferences → Applications in GitLab and revoke the Vaiz application.

Support

If you have questions or need help with the GitLab integration, reach out to us: