GitLab Integration

The GitLab integration allows you to connect repositories hosted on an external GitLab instance to a Tuleap project. Without migrating your code, you benefit from full traceability: every commit, Merge Request, tag, or branch on GitLab referencing a Tuleap artifact automatically creates a bidirectional cross-reference.

Prerequisites

• The Git and GitLab plugins must be installed and enabled.

• You must be a Git service administrator in your Tuleap project.

• You must have a GitLab Access Token granting access to the GitLab API (api scope required).

GitLab token types

Tip

Automatic comments added by Tuleap on GitLab (backlinks) are posted using the account associated with the token. Choose an appropriate token (project or group token preferably) to avoid comments being attributed to a personal user.

Register a GitLab repository

Procedure

1. Navigate to the Git service of your Tuleap project.

2. Click "Create a repository", then "Add GitLab repository".

3. In the modal, enter the URL of your GitLab instance and the access token.

4. The list of repositories you can integrate is displayed. Select the repository to link.

Once registered, the GitLab repository appears in the project repository list, identifiable by the GitLab icon.

When registering a GitLab repository, Tuleap automatically creates a webhook in the GitLab repository. This webhook listens for three event types:

• Push: triggers analysis of commit messages to create cross-references and, when applicable, close Artifacts.

• Merge Request: triggers cross-reference creation from the MR title, description, or source branch name, and updates its status in Tuleap.

• Tag push: triggers tag registration and cross-reference creation if the tag message contains a Tuleap reference.

Warning

Do not modify the webhook settings manually in GitLab. If the webhook is deleted or altered, use the "Regenerate the GitLab webhook" option from Tuleap.

Manage an integrated repository

By clicking the gear icon of the GitLab repository, you can:

• Edit access token: if the token has expired or been revoked. The webhook is automatically regenerated.

• Regenerate the GitLab webhook: if the webhook has been modified or deleted on the GitLab side, this action recreates a functional webhook with a new secret.

• Allow artifact closure: enables GitLab commits to automatically close Tuleap Artifacts (disabled by default).

• Prefix the branch name: defines a prefix for branches created from a Tuleap Artifact (e.g. feature/, fix/).

• Unlink the repository: removes the link between the GitLab repository and the Tuleap project. Existing references are deleted and future commits will no longer create cross-references.

Warning

Unlinking does not delete anything on the GitLab side. It only removes the link in Tuleap.

Link a GitLab group

Instead of integrating repositories one by one, you can link an entire GitLab group to your Tuleap project. All repositories in the group will be automatically integrated.

Information

A Tuleap project can only be linked to one GitLab group at a time.

Procedure

1. In the Git service, navigate to the "GitLab Group Link" administration tab.

2. Click the button to start the wizard.

3. Enter the URL of your GitLab instance and the access token.

4. Select the group to link from the list of visible groups.

5. Configure the default settings for synchronized repositories:

   • Allow artifact closure (optional).

   • Branch name prefix (optional).

All repositories in the group are integrated into the Tuleap project.

Information

Settings configured during linking only apply to new repositories during synchronization. They can be modified individually per repository after synchronization.

Available actions

• Synchronize: retrieves new repositories added to the GitLab group since the last synchronization. Repositories deleted or moved on the GitLab side are not automatically removed from Tuleap.

• Update token: renews the access token if the previous one has expired.

• Update configuration: changes the default settings for future synchronizations.

• Unlink: removes the link between the Tuleap project and the GitLab group. Already integrated repositories remain in place; to remove them, unlink them individually.

Cross-references

The cross-reference system is the heart of the GitLab integration. It works in both directions.

From GitLab to Tuleap

To create a reference to a Tuleap Artifact in GitLab, add the keyword TULEAP-<artifact_id> (case-sensitive) in:

You can reference multiple Artifacts in a single commit or MR. However, a branch can only reference one Artifact.

Information

On the GitLab side, an automatic comment (backlink) is added to commits and Merge Requests containing Tuleap references. This comment lists the referenced Artifacts with clickable links to Tuleap. It is posted using the account associated with the access token configured during repository registration. This is not possible for tags and branches.

From Tuleap to GitLab

From any Tuleap text field (Artifact tracker, comment, etc.), use the following keywords:

The <repo> must correspond to a GitLab repository registered in the project. Clicking on the reference redirects you to the corresponding element on your GitLab instance.

Close Artifacts from GitLab

If the option is enabled on the integrated repository, GitLab commits can automatically close Tuleap Artifacts.

Several conditions are required:

• The "Allow artifact closure" option is enabled on the integrated repository.

• The push is made to the default branch of the GitLab repository.

• The Artifact belongs to the same project as the integration.

• The "Done" semantic or "Status" semantic is defined.

• The Artifact is not already closed.

Closing keywords

The closing keywords are the same as for Tuleap Git, but used with the TULEAP-<id> format:

• Closes TULEAP-1234

• Fixes TULEAP-1234

• Resolves TULEAP-1234

• Implements TULEAP-1234

And their variants: Close, Closed, Closing, Fix, Fixed, Fixing, etc.

Create a GitLab branch from an Artifact

You can create a GitLab branch and, optionally, the associated Merge Request directly from a Tuleap Artifact.

Several conditions are required:

• At least one GitLab repository is integrated in the Artifact's project with a valid token.

• You are a member of the project.

• You have read access to the Artifact.

Procedure

1. Open an Artifact.

2. In the Artifact actions, select "Create branch on a GitLab repository".

3. Select the target GitLab repository.

4. The branch is automatically created with the format: (prefix)TULEAP-{artifact_id}.

Information

The branch prefix is configurable per repository from the GitLab integration settings.

Create a Merge Request

Once the branch is created and your changes pushed, you can create a GitLab Merge Request from the same Tuleap Artifact. The MR is automatically configured:

• Title: TULEAP-{artifact_id}: {Artifact title}.

• Target branch: the default branch of the GitLab repository.

• Initial state: the MR is created in draft mode.

The Merge Request then appears in the Artifact's cross-references, with its status displayed in real time (open, merged, closed).

Known limitations

• If you already have a project reference named gitlab_commit, gitlab_mr, gitlab_tag, or gitlab_branch, it will override the one used by the plugin.

• Tuleap displays the path_with_namespace of the repository (not the name_with_namespace).

• Two repositories with the same name and path from two different GitLab instances cannot be integrated in the same Tuleap project.

• The GitLab project name and namespace must not contain - or ..