GitLab

Overview

The purpose of this integration is to link Tuleap projects and GitLab repositories.

If you are using GitLab and want to keep a trace of your commits and merge requests in Tuleap, this plugin will allow you to reference Tuleap artifacts in your commit messages or merge requests title/description and conversely.

References

A GitLab commit or merge request can reference several Tuleap artifacts, in different projects. A Tuleap artifact can reference several commits or merge requests, in different GitLab repositories.

Reference a Tuleap artifact

To be able to create GitLab cross-references, you need to:

  • Register your GitLab repository in the Git service of your Tuleap project

  • Reference Tuleap artifacts in GitLab commit messages

  • Reference Tuleap artifacts in GitLab merge request title or description

To link your commit (or merge request) to the Tuleap artifact of your choice, you must add the keyword TULEAP-<artifact_id> (case-sensitive) to your commit message (or merge request title/description). You can reference as many artifacts as you want in the same commit message (or merge request title/description).

Reference a Tuleap artifact in GitLab commit

When the committer email is matching a Tuleap account, then its avatar and username will be displayed in the reference. Otherwise, the committer name is displayed as received from the GitLab API.

On GitLab side, when a commit message contains some references to Tuleap, then a comment is automatically added to the commit.

A comment is composed of a list of Tuleap references included in the commit message, with links to Tuleap.

Comment on GitLab commit

Reference a Tuleap artifact in GitLab merge request

When the public email of the author of the Merge Request is matching a Tuleap account, then its avatar and username will be displayed in the reference. Otherwise, the author name is displayed as received from the GitLab API.

Note

If the author of the Merge Requests changes its public email after creating the Merge Request, then no refresh will be performed to update data displaying in the reference on Tuleap.

On GitLab side, when a merge request contains some references to Tuleap, then a comment is automatically added.

A comment is composed of a list of Tuleap references included in the merge request title/description, with links to Tuleap.

Comment on GitLab merge request

Reference a GitLab commit or merge request

Please refer to Tuleap references for more details on references.

You can reference a commit or merge request of one of the GitLab repositories registered in your Tuleap project.

Reference a GitLab commit in Tuleap

To reference GitLab commit, you have to use the keyword gitlab_commit followed by a #, the repository name, and the commit sha1:

gitlab_commit #<repository_name>/<sha1>.

<repository_name> must be a registered GitLab repository. If not, no reference will be created.

When you click on this reference, you will be redirected to your GitLab instance, on the page displaying the commit details.

Reference a GitLab merge request in Tuleap

To reference GitLab merge request, you have to use the keyword gitlab_mr followed by a #, the repository name, and the merge request id:

gitlab_mr #<repository_name>/<merge_request_id>

<repository_name> must be a registered GitLab repository. If not, no reference will be created.

When you click on this reference, you will be redirected to your GitLab instance, on the page displaying the merge request details.

Register your GitLab repository

Prerequisites

To be able to register a GitLab repository in your project, please ensure that:

  • both Git and GitLab plugins are installed and activated.

  • you have admin privileges in the Git service of your project.

  • you have a GitLab access token authorized to be used to query the GitLab API (see GitLab access Token)

GitLab access Token

You can use a personal or project access token. The token will be used to manage integration of GitLab repository in Tuleap, and to write comments automatically on GitLab commit or merge requests.

With a project access token, you can only integrate the GitLab repository which provides the project access token. With a personal access token, you can integrate all repositories which you maintain. Don’t forget that comments will be added automatically on GitLab commits and merge requests. These comments will be written with the access token, so if you provide a personal access token, the user providing this token will be displayed next to comments.

Note

If you use a personal access token, you need to be identified by GitLab as the maintainer of the repository that you want integrate.

GitLab API scope

Note

The name of the token is not important, but you need at least to check api in the scopes list.

Once your GitLab access token is created, copy it and save it for later.

GitLab repository registration

Go to the Git service of your Tuleap project, click on [New repository], then click on [Add GitLab repository].

Button integrate GitLab

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

The list of the repositories that you can integrated is displayed. Select the repository to link.

Once the GitLab repository is registered, it is displayed in the repositories list and is visually identifiable thanks to the GitLab icon.

GitLab repository tile

From now on, each time you reference an artifact in a commit or merge request, a cross-reference will be created in the target artifact.

Note

During the registration, a webhook is created in the GitLab repository. If the parameters of this webhook change (URL, events, or anything else), we cannot ensure that cross-references will continue to be created. See Regenerate the GitLab webhook to have more details.

Possible actions on GitLab repository

As a Git administrator, go to the Git service of your project and find the repository that you want to apply action.

When you click on cog icon in GitLab tile, you can:

  • Edit access token

  • Regenerate the GitLab webhook

  • Unlink the repository

Others actions on GitLab repository tile

Edit access token

If the token used during the integration has been revoked, you can change it by clicking on [Edit access token]. See GitLab access Token to have more details.

Editing GitLab access token

Confirm the action.

Confirm editing GitLab access token

Note

When you change access token, the webhook is also regenerated on GitLab side.

Regenerate the GitLab webhook

A webhook allows GitLab to communicate with Tuleap. This webhook is composed of a secret generated automatically by Tuleap and some events (push and merge requests events). If the webhook has been changed and is not functional, you can regenerate it by clicking on [Regenerate GitLab webhook].

When the webhook is regenerated, the old is deleted from GitLab server, and a new webhook with a new secret is created.

Unregister repositories

If you want to unregister a repository, you need to select [Unlink the repository] in the list. Then a modal opens and you need to confirm the action.

From now on, existing references won’t work anymore and any new commit in this repository referencing a Tuleap artifact in this project will not create cross-references.

Attention

Known issues / limitations

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

  • GitLab provides two names for a repository:
    • name_with_namespace is displayed in UI

    • path_with_namespace is used to clone/checkout the repository

    • Tuleap displays only path_with_namespace and references are created with it.

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

  • For the moment, the project name and namespace of your GitLab project must not contain a “-” or a “.”.