How to import a project

Preparation

To import a project navigate to the projects overview by clicking the Projects tab in the top navigation bar or by entering /projects in your browser.

Import

../../../_images/import.png

To import a project click the Import Project button and choose one of the two options.

GitLab Project

If the project you want to import is hosted on gitlab.com or a private GitLab instance, choose the first option GitLab Project.

When choosing this option, the importer will configure your GitLab project to integrate well with MergeBoard. This provides a great out-of-the-box experience, but requires you to have maintainer access to the project in GitLab. If you don’t have the necessary permissions, you can still import the project using the Git Project option and configure the integration manually.

  1. Provide your GitLab credentials

../../../_images/import_gitlab_1.png

Enter the URL to your GitLab instance and provide a personal access token or a project access token with api scope.

Afterwards click on Next.

  1. Select the projects you want to import

../../../_images/import_gitlab_2.png

Select the items from the project list that 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 this 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 MegeBoard user. 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 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. All issue tracker updates triggered by MergeBoard will therefore be associated 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.

  1. Actual import and last steps

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.

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_deployment_key.png

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 repository, even though GitLab indicates otherwise.

You can fully use the imported project after the first git sync has finished. Take a look at the remote list of the protect to see the progress.

Git Project

If your project is hosted anywhere else, like on GitHub, Bitbucket or a private server, choose option two: Git Project. MergeBoard supports all git remotes that use the SSH, HTTP(S) or git protocol.

Just enter a name for your project, its url (e.g. git@github.com:<user>/<project>.git) and choose how you want to authenticate against the remote:

None

No credentials are necessary to access the git remote host. This is usually only suitable for testing as no publicly reachable git server should allow pushing changes without authentication. You will therefore not be able to merge anything.

Username and Password

Your project is not publicly available and you can access it by entering your username and password 1. For GitHub projects that would be your GitHub username and password. This will usually not work if you have two factor authentication enabled. Use an SSH key (e.g. a deploy key) in these cases.

SSH / Deploy Key

The git host supports authentication via SSH keys. If you want to know more about this, please check out the great explanation by GitHub.

You can either provide the SSH username as part of the URL (git@...) or via the username field. If both are provided, the username field takes precedence. Please be aware that the SSH username usually does not match your username at the service and is instead something else like git.

Enter a private SSH key in the text box below SSH / Deploy Key 2. It is recommended to use a unique SSH key for MergeBoard, or, if supported by your git hoster, a deploy key, which is basically just a SSH key with access limited to certain repositories. Note that your SSH / deploy key must have write access to perform merges.

Recommended Authentication Method

The recommended authentication method is using an SSH or Deploy key.

By clicking Import Project you are done. Your project should now appear in the list of projects at /projects.

footnotes

1

MergeBoard will store your password in an encrypted fashion and only use it to login into the server stated in the URL. It is recommended to use SSH or HTTPS as protocol to ensure your credentials are only transferred via an encrypted connection. Credentials will never be sent back to the user.

2

MergeBoard will store your SSH key in an encrypted fashion and only use it to login into the server stated in the URL.