How to set up the GitLab integration in Vaiz

The GitLab integration connects your GitLab projects to Vaiz tasks. You can link merge requests, branches and commits to a task, see their activity right in the task, and create branches without leaving Vaiz. Vaiz can also link merge requests, branches and commits for you when they mention a task key such as APP-123.

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

Step 1. Connect GitLab to your space

Click the space icon in the top-left corner, select the space you want to connect, and choose App center.

In the App Center, click GitLab.

On the GitLab integration page, click Connect. Choose where your GitLab is hosted.

GitLab.com

Select the GitLab.com tab and click Continue to GitLab.

GitLab asks you to authorize Vaiz. Vaiz requests the api scope so it can read your projects, add webhooks and create branches. Click Authorize and GitLab redirects you back to Vaiz.

Self-managed GitLab

To connect your own GitLab instance, first create an OAuth application in it:

1. In your GitLab, open Admin area → Applications (for an instance-wide app) or Preferences → Applications (for a personal app), and click Add new application.
2. In Redirect URI, paste the redirect URI shown in the Vaiz connect window. Click the copy icon next to it to copy it.
3. Select the api scope and save the application.
4. Copy the Application ID and Secret.

Then go back to Vaiz:

1. Select the Self-managed tab.
2. Enter your GitLab instance URL, for example https://gitlab.example.com.
3. Paste the Application ID and Secret.
4. Click Continue to GitLab and authorize Vaiz.

Step 2. Connect GitLab projects

After the connection is complete, the GitLab account appears on the integration page with the Connected status. For a self-managed instance, its address is shown under the account name.

Next, choose which GitLab projects to connect to the space. In the Projects section, open the GitLab projects connected to this space list and select a project. Repeat for every project you need.

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

If a project you expect is missing, click the refresh icon next to the list. To disconnect a project, click the cross icon next to it. Vaiz removes its webhook.

Step 3. Check the integration settings

The integration page shows the available features:

• Projects: GitLab projects available for linking to tasks.
• MR Comments & Activity: comments and updates from linked merge requests appear in the Vaiz task.
• Task Activity to MRs: task status changes in Vaiz are posted as comments on linked merge requests.
• Auto-link by task key: merge requests, branches and commits that mention a task key are linked to the task automatically.
• Create Branches: create new branches in connected projects directly from tasks.

MR Comments & Activity, Task Activity to MRs and Auto-link by task key are on by default. Use the toggle next to each feature to turn it off.

Step 4. Link merge requests, branches and commits to a task

After GitLab is connected, every task has a Repository field. Linked merge requests, branches and commits appear in this field.

To add a link, click + in the Repository field. In the window that opens:

1. Choose the project. Projects are grouped by provider: GitLab.com projects are listed under GitLab, and projects from a self-managed instance are listed under GitLab at followed by the instance address. If you also use GitHub, its repositories are listed in a separate group.
2. Open the MR, Branch or Commit tab.
3. Start typing to search, then click the item you want to link.

Hover over a linked item to see its details. Click it to open it in GitLab, copy its link or name, or unlink it from the task.

Link automatically by task key

You don't have to link everything by hand. 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.

If a key matches a task in your space, Vaiz links the merge request, branch or commit to that task. For example, a branch named APP-123-login-form or a commit message APP-123 Fix the login form is linked to task APP-123.

A few things to keep in mind:

• Auto-link works only in projects connected in Step 2.
• The key must belong to a project in this space. Keys are not case-sensitive.
• If a merge request mentions several tasks, it is linked to each of them.
• Closed merge requests are not linked automatically.
• Existing links are never removed by auto-link.

Step 5. Create a branch from a task

You can create a branch for a task without opening GitLab.

1. In the task, click + in the Repository field.
2. Open the Create branch tab.
3. Choose the project and the base branch.
4. Check the branch name. By default, it is the task key, so the new branch is linked to the task.
5. Click Create.

The new branch is created in GitLab and linked to the task.

Step 6. Follow merge request activity

When MR Comments & Activity is on, the task shows what happens to its linked merge requests: when a 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 also appear in the task.

When Task Activity to MRs is on, Vaiz posts a comment on each linked merge request when the task status changes, so reviewers can see the task progress in GitLab.

Step 7. Manage the integration

You can manage connected GitLab accounts from the GitLab page in the App Center.

• To add another account or another GitLab instance, click Connect another account and repeat the connection flow.
• To disconnect an account, click the three-dot menu next to it and select Disconnect.

When you disconnect an account, Vaiz removes its webhooks from the connected projects. Links already added to tasks stay in place, but they no longer receive status updates or comments.

To revoke Vaiz access on the GitLab side, open Preferences → Applications in GitLab and revoke the Vaiz application in the Authorized applications list.