GitLab Integration

Applies to Collaborator 14.6, last modified on October 04, 2024

About

  • Collaborator integrates with Git repositories hosted at GitLab.com, or on the GitLab Community or GitLab Enterprise servers in your network.

  • When you integrate Collaborator with a GitLab repository, your Collaborator server creates reviews automatically for merge requests in the repo, as well as for push events that occur in that repo. For complete information on how the integration works, see Integration With Repository Hosting Services.

  • To inform Collaborator about changes, GitLab uses a webhook that sends notification messages to your Collaborator server.

  • To set up the webhook and other integration parameters, you need to set up some options in Collaborator and in GitLab. See the rest of this topic for details.

Supported Hosting Services

  • GitLab (gitlab.com)

  • GitLab Community Edition

  • GitLab Enterprise Edition

LFS is NOT supported for remote systems (supported for native Git only).

Requirements

  • Your Collaborator server must be accessible to GitLab and vice versa. You may need to configure your firewall or enable tunneled connections to expose the server’s External URL to the Web. If needed, ask your system administrator for help.

  • Note that Collaborator makes API calls to https://api.github.com which is a machine separate from https://github.com. When using trusted connections, ensure that the security certificates from both machines are accepted.

  • To configure integration settings in Collaborator, you need Administrator privileges.

1. Get GitLab Tokens

To integrate with GitLab, you need a personal access token that will be used to access your repositories.

For detailed information on generating a personal access token, follow instructions on this page of GitLab documentation:

https://gitlab.com/help/user/profile/personal_access_tokens.md

Notes:

  • When setting up the token parameters, make sure to enable the api scope for the token.

  • After GitLab generated the token, save it somewhere or write it down. We will need the token later, when we will configure the integration between Collaborator and GitLab

2. Set Up Integration

Collaborator offers two groups of settings for configuring integration with remote repositories:

Settings When to use
Easy Add Repository tab We recommend using these settings to set up new connections to your repositories quickly.
Configure Remote Systems tab Use these settings to configure existing connections. Though you can use these settings to set up integration, the settings on the “Easy Add Repository” tab will help you do this faster.

Additionally, you can create auto-polling configuration to periodically look for new repositories on the specified server and suggest creating integrations for them.

Easy Add Repository tab (recommended)

  1. Log in to Collaborator as administrator. (To integrate with GitLab repositories, you need administrator privileges in Collaborator).

  2. On the Collaborator main toolbar, click ADMIN, and then select Repository Hosting Services from the tree on the left. Then switch to the Easy Add Repository tab.

  3. On the tab, select GitLab in the Add repository for box and click Next:

    Integration with GitLab: Start

    Click the image to enlarge it.

  4. Collaborator will displays a page with connection details.

    Integration with GitLab: Settings

    Click the image to enlarge it.

    Specify settings in the the following sections of the wizard:

    Connection settings
    Setting Description

    GitLab host name

    Required for repositories on self-hosted servers. Specifies the host name of your GitLab Enterprise or GitLab Community server.

    Group

    Required only for group owned repositories (https://gitlab.com/GroupName/RepoName). Specifies the name of your GitLab group account (GroupName).

    Private token

    Required. The token for a GitLab account that has access to the remote repository.

    This is the token that we generated in GitLab earlier.

    Webhooks secret token

    Optional. The secret token for webhook events. If provided, must be at least 8 characters long.

    To learn more about webhook settings on the GitLab side, see GitLab documentation:

    https://gitlab.com/help/user/project/integrations/webhooks.md

    After specifying connection settings, you can click Load repositories to retrieve a list of repositories available for the specified user or group.

    Select repositories

    Select repositories

    Optional. Displays a list of repositories available for the specified user or group.

    Select which repositories you need to track. Use Ctrl+click or Shift+click for multi-selection.

    If any of the repositories were chosen, the wizard will display the Create for selected button below the settings section.

    If none of the repositories were chosen, the wizard will display the Create for all button below the settings section.

    Override existing configurations

    Optional. Specifies whether to override existing configurations that track the same repository URI.

    Branches

    Branches to track

    Optional. The names of branches to track changes and create reviews on merge requests and direct pushes. Separate multiple branch names with commas.

    You can use Java-style regular expressions to match specific branch names, or you can use the * wildcard (alone, or separated by commas) to match all branches. Note that wildcards and regular expressions cannot be used if you enable the Status check required setting (see below).

    If this edit box is empty, the branch main will be tracked.

    Ignore pushes for branches

    Optional. Specifies branches for which Collaborator will not create reviews on direct pushes.

    You can enter one or several branch names. Separate multiple branch names with commas. You can also use Java-style regular expressions to match specific branch names, or you can use the * wildcard (alone, or separated by commas) to match all branches.

    Pull request actions

    Create review automatically

    If enabled, reviews for merge request are created automatically.

    If disabled, user can add merge request to a review manually through Remote System links, by API call or by special command directly from merge request.

    When review completed

    Optional. Specifies what action to perform when a review corresponding to a merge request was accomplished:

    • Do nothing: Do not perform any action.
    • Merge the merge request: Merge the request that corresponds to a review.
    • Merge the merge request and delete source branch: Merge the request that corresponds to a review and then delete the respective branch.

    The exact merge strategy cannot be specified on the integration level. If any of merge actions was chosen, merge request will be merged according to project settings on the GitLab side (Settings > General > Merge requests). To learn more about merge request strategies, see GitLab documentation.

    Allow users to select merge strategy in review

    If enabled, regular users would be able to choose pull request merge strategies in each separate review.

    If disabled, all pull requests would behave as specified by the When review completed setting.

    Wait for signature (if enabled) before merge

    Optional. Effective, if any of merge actions was selected in When review completed setting.

    If enabled Collaborator will wait for the completed review to be signed off before merging the respective merge request. Otherwise, merge request will be merged immediately, even if the review have not been signed yet.

    Allow to complete review with conflicts in pull request

    Should it be possible to complete a review if there are conflicts in the respective pull request.

    When review cancelled/deleted/rejected

    Optional. Specifies an action to perform when a review corresponding to a merge request was cancelled, deleted or rejected:

    • Do nothing: Do not perform any action.
    • Close merge request: Close merge request that corresponds to a review.

    Auto assign reviewers

    Whether to assign Collaborator reviewers when some specific users or teams were added as merge request reviewers or specified as code owners on the Gitlab side and integration can match those Gitlab users with Collaborator users.

    Reopen a review when

    Optional. Specifies in what cases Collaborator should reopen completed reviews. May include any combination of the following:

    • when a push to a merge request is made,
    • when a comment is added to a merge request,
    • when a comment is added to commit which is a part of a merge request
    Review settings

    Default review template

    Optional. Specifies the initial template that will be chosen when creating review (if set to "None", the first template in the list will be chosen).

    The value of this setting overrides the value of Default review template setting specified on group level.

    Sync groups

    Specifies whether Collaborator should synchronize its native groups with group information from the GitLab server. Effective if the global Enable group sync setting is turned on.

    Once enabled, on every logging-in, Collaborator will check user membership in groups on the GitLab server, create new groups (if needed), and automatically add this user to the corresponding groups on the Collaborator server. See Syncing Groups and Their Members for details.

    To ensure that Collaborator users do not have access to reviews that contain code from the repositories that they do not have access to, use the Restrict Access to Review Content settings.

  5. Click the Create for selected button or the Create for all button to create repository integrations and automatically create webhooks for each repository in GitLab. To stop suggesting integrations for some specific repositories, select these repositories in the list and click Ignore selected.

    For every repository a separate configuration will be automatically created in Collaborator and a webhook will be automatically added in GitLab.

Configure Remote Systems tab

  1. Log in to Collaborator as an administrator. (To configure integration settings, you need administrator privileges in Collaborator).

  2. On the Collaborator main toolbar, click ADMIN, and then select Repository Hosting Services from the tree on the left. Then switch to the Configure Remote Systems tab.

  3. In the New Remote System Configuration section, select GitLab and click Create:

    Integration with GitLab: Start

    Click the image to enlarge it.

  4. Collaborator will display a page with configuration settings. Specify settings in the following sections:

    GitLab settings
    Setting Description

    Title

    Required. The configuration name as it will be displayed in Collaborator user interface.

    GitLab repo URI

    Required. The URI of the GitLab repository to be tracked, for example, https://gitlab.com/gitlab-org/gitlab-ee.git.

    You can copy the URI from the repository settings in GitLab:

    Getting URI of a GitLab repository

    Click the image to enlarge it.

    Private token

    Required. The personal access token for the GitLab account that has access to the repository.

    This is the token that we generated in GitLab earlier.

    Webhooks secret token

    Optional. The secret token for webhook events. If provided, must be at least 8 characters long.

    To learn more about webhook settings on the GitLab side, see GitLab documentation:

    https://gitlab.com/help/user/project/integrations/webhooks.md

    Webhook status

    Indicates the current status of the webhook:

    • Webhook is absent: The webhook has not been created yet.
    • Webhook isn't active: The webhook has been created, but is inactive.
    • Up and running: The webhook is active.

    To create or activate a webhook, click Update webhook.

    Important: Click this button, when you set up integration with your repository for the first time.

    Branches

    Branches to track

    Optional. The names of branches to track changes and create reviews on merge requests and direct pushes. Separate multiple branch names with commas.

    You can use Java-style regular expressions to match specific branch names, or you can use the * wildcard (alone, or separated by commas) to match all branches. Note that wildcards and regular expressions cannot be used if you enable the Status check required setting (see below).

    If this edit box is empty, the branch main will be tracked.

    Ignore pushes for branches

    Optional. Specifies branches for which Collaborator will not create reviews on direct pushes.

    You can enter one or several branch names. Separate multiple branch names with commas. You can also use Java-style regular expressions to match specific branch names, or you can use the * wildcard (alone, or separated by commas) to match all branches.

    Pull request actions

    Create review automatically

    If enabled, reviews for merge request are created automatically.

    If disabled, user can add merge request to a review manually through Remote System links, by API call or by special command directly from merge request.

    When review completed

    Optional. Specifies what action to perform when a review corresponding to a merge request was accomplished:

    • Do nothing: Do not perform any action.
    • Merge the merge request: Merge the request that corresponds to a review.
    • Merge the merge request and delete source branch: Merge the request that corresponds to a review and then delete the respective branch.

    The exact merge strategy cannot be specified on the integration level. If any of merge actions was chosen, merge request will be merged according to project settings on the GitLab side (Settings > General > Merge requests). To learn more about merge request strategies, see GitLab documentation.

    Allow users to select merge strategy in review

    If enabled, regular users would be able to choose pull request merge strategies in each separate review.

    If disabled, all pull requests would behave as specified by the When review completed setting.

    Wait for signature (if enabled) before merge

    Optional. Effective, if any of merge actions was selected in When review completed setting.

    If enabled Collaborator will wait for the completed review to be signed off before merging the respective merge request. Otherwise, merge request will be merged immediately, even if the review have not been signed yet.

    Allow to complete review with conflicts in pull request

    Should it be possible to complete a review if there are conflicts in the respective pull request.

    When review cancelled/deleted/rejected

    Optional. Specifies an action to perform when a review corresponding to a merge request was cancelled, deleted or rejected:

    • Do nothing: Do not perform any action.
    • Close merge request: Close merge request that corresponds to a review.

    Auto assign reviewers

    Whether to assign Collaborator reviewers when some specific users or teams were added as merge request reviewers or specified as code owners on the Gitlab side and integration can match those Gitlab users with Collaborator users.

    Reopen a review when

    Optional. Specifies in what cases Collaborator should reopen completed reviews. May include any combination of the following:

    • when a push to a merge request is made,
    • when a comment is added to a merge request,
    • when a comment is added to commit which is a part of a merge request
    Review settings

    Default review template

    Optional. Specifies the initial template that will be chosen when creating review (if set to "None", the first template in the list will be chosen).

    The value of this setting overrides the value of Default review template setting specified on group level.

    Sync groups

    Specifies whether Collaborator should synchronize its native groups with group information from the GitLab server. Effective if the global Enable group sync setting is turned on.

    Once enabled, on every logging-in, Collaborator will check user membership in groups on the GitLab server, create new groups (if needed), and automatically add this user to the corresponding groups on the Collaborator server. See Syncing Groups and Their Members for details.

    To ensure that Collaborator users do not have access to reviews that contain code from the repositories that they do not have access to, use the Restrict Access to Review Content settings.

  5. Click Test Connection to verify if you entered data correctly.

    Click Save to store the settings.

    Click on Update Webhook button to add webhook for the repository on the remote system's side.

Creating GitLab auto-polling configuration

Sections above describe how to add integrations for existing repositories. When some new repositories are created on a server, you may integrate them manually. Alternatively, you can setup GitLab auto-polling configuration that will periodically look for new repositories on the specified server, user or group and suggest creating integrations for them.

  1. Log in to Collaborator as administrator. (To integrate with GitLab repositories, you need administrator privileges in Collaborator).

  2. On the Collaborator main toolbar, click ADMIN, and then select Repository Hosting Services from the tree on the left. Then switch to the Repository Auto-Polling tab.

  3. On the tab, select GitLab in the Add configuration box and click Next.

  4. Collaborator will displays a page with connection details.

    Integration with GitLab: Auto-polling Settings

    Click the image to enlarge it.

    Fill in the edit boxes:

    Setting Description
    Server URI Required. The URI of GitLab server, user or group to be polled for new repositories.

    Token

    Required. The private token for the GitLab account.

    This is the token that we generated in GitLab earlier.

    After specifying these values, you can click Test connection to verify if you entered data correctly.

  5. After you specified the values, click Save. This will create an auto-polling configuration and display it in the Auto-Polling Configurations List.
  6. Scroll down the Repository Auto-Polling tab and check that the Enable Auto-Polling setting is on and optionally change the Auto-Polling Interval setting.

Now Collaborator will automatically check if any new repositories were found on the specified server. Once found, it will notify administrators and suggest creating integrations with these newly created repositories via the Easy Add Repository wizard.

Enable/Disable configuration

Once a new repository configuration is created, it is enabled automatically. However, you can enable and disable integration with GitLab manually. To do this:

  1. In Collaborator, go to ADMIN > Integrations.
  2. In the Integration Status section find the Enable GitLab Integration setting and change it to Yes or No, respectively.
Enable Gitlab Integration

Click the image to enlarge it.

Known Issues and Specifics

  • When configuring user remote accounts, user names must be entered as specified in the Full Name field of the Profile settings.

  • Linking user by email address works when email address is specified as Public email in the Profile settings.

  • If repository contains a CODEOWNERS file that defines users responsible for certain files in a repository and integration can match those GitLab users with Collaborator users, then it will automatically add those users as reviewers on Collaborator's side.

  • You can secure webhook calls by providing a secret token while creating or modifying a webhook and integration settings in GitLab and in Collaborator. This token will be used as server signature for verifying webhook events. The webhook token is optional and is absent by default.

  • Collaborator will not create reviews on merge commits of merge requests when their merge commit message starts with the Merge branch substring or when merge commit message was specified in the Pull Request Merge Info section.

  • The exact merge strategy cannot be specified on the integration level. If any of merge actions was chosen, merge request will be merged according to project settings on the GitLab side (Settings > General > Merge requests). To learn more about merge request strategies, see GitLab documentation.

  • If your GitLab repository is configured to use merge request pipelines, Collaborator integration will use them as well. Otherwise, it will use regular pipelines.

  • Currently, GitLab integration does not support connecting to the target GitLab server through the proxy server.

GitLab Community / GitLab Enterprise
  • By default, GitLab Community / GitLab Enterprise servers do not allow performing webhook requests to web services running in the same local network. If your Collaborator server resides on the same machine as GitLab server or within the same local network, then administrator of your GitLab server should enable the Allow requests to the local network from hooks and services option in the Outbound requests section in Admin > Settings.

See Also

Source Control Integrations

About GitLab Integration
 
Highlight search results