GitLab

Maintainer Access Required

Importing a project from GitLab requires maintainer permissions in the GitLab repository to be imported. If you do not have these permissions, ask an administrator or maintainer to perform the import for you.

The following instructions are compatible with both gitlab.com and self-hosted GitLab instances.

Video Tutorial

Step 1: Generate an Access Token

For authentication, you can use either a personal access token or a project access token with api scope. If you have already created such an access token, you can skip this first step. The steps for generating a Personal Access Token are described below. If you want to use a Project Access Token, we recommend a look at the GitLab documentation.

Open your GitLab instance. In the top-right corner, select your avatar and click on Edit profile.

../../../_images/gitlab_001.png — GitLab dropdown menu after clicking on the avatar icon in the top-right corner.

On the left sidebar, select Access Tokens. Enter a name and optional expiration date, and select the api scope. Afterwards click on Create personal access token. Write down the generated personal access token or save it in your password manager.

Step 2: Import Project into MergeBoard

To import a project into MergeBoard, first click Projects in the navigation bar at the top, then on the Import Projects button. Select GitLab Project from the dropdown menu.

The following dialog will open.

../../../_images/gitlab_002.png — Dialog for importing GitLab projects.

GitLab URL

To import projects from gitlab.com, you can simply leave the default setting as it is. To import projects from a self-hosted GitLab server, enter the base URL of your server, e.g., https://gitlab.company.com.

Note that entering a GitLab project URL is not supported. The project to be imported can be selected in the next step.

Access Token

Enter a personal access token or project access token with api scope.

By clicking Next you will get to the selection of projects to import.

../../../_images/gitlab_003.png — Dialog to select GitLab projects to import.

Select the items from the project list you want to import into MergeBoard. If you select only one project, you can customize how MergeBoard will name the project, otherwise the name is copied from GitLab. If a project is missing in this list, make sure that you have at least maintainer access to the project.

You can also customize whether you want to connect MergeBoard with the GitLab issue tracker of your project. Enabling this feature makes it possible to reference issues from merge requests and update their state based on the merge request status. You can further customize this behavior after the import is completed.

GitLab SaaS hosted repository

MergeBoard creates a project access token with the name MergeBoard in GitLab when Connect Issue Tracker is enabled so that all modifications in the issue tracker are associated with the virtual MergeBoard user. The access token used for the import is no longer needed afterwards. This solution has the advantage that all automated changes are associated with a separate user, who doesn’t count against your license. This feature requires a paid license or a self managed instance of GitLab though.

If you are using a free GitLab SaaS hosted repository, the project access token feature is not available and MergeBoard will fall back to using the API key provided in the first import step (make sure it doesn’t expire!). All issue tracker updates triggered by MergeBoard will therefore be associated with the user owning the API key. We recommend to create a separate GitLab user for the issue tracker integration to avoid confusion whether a change was done by MergeBoard or the actual user. You can also skip the issue tracker integration now and set it up after the import.

After clicking next, the import of the selected projects starts. As part of this process MergeBoard will modify your GitLab projects in the following ways:

Add a newly generated SSH deploy key with write permissions
Add a webhook to inform MergeBoard about push and CI events
Add a project access token when the issue tracker integration is enabled

If an error is encountered during any of these steps, MergeBoard will try to undo all previous changes. You still might want to check the GitLab project settings to make sure that all changes were reverted.

Please note that the import may take a moment depending on the size of the repository. You can view the synchronization status at any time under Remotes in the newly imported project. As soon as the status changes to Synced the project is ready for use.

Step 3: Protected Branch Configuration

If you want to merge into branches that are marked as protected in GitLab, you need to assign the necessary permissions to the newly created deploy key. You can do this by opening the Repository settings of your GitLab project, expanding the Protected branches options and assigning push permissions to the deploy key:

../../../_images/gitlab_004.png — GitLab dialog to customize the Protected Branches configuration. The MergeBoard deploy key should also have permission to push into protected branches.

Permission Issue

There appears to be a permission issue with at least certain versions of GitLab. Assigning push permissions to a deploy key in these versions also results in maintainers getting push access to the branch, even though GitLab indicates otherwise.

Congratulations, you have successfully imported your first project!