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 pull 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
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.
-
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
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. |
| 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. |
Easy Add Repository tab (recommended)
-
Log in to Collaborator as administrator. (To integrate with GitLab repositories, you need administrator privileges in Collaborator).
-
On the Collaborator main toolbar, click ADMIN, and then select Remote System Integration from the tree on the left. Then switch to the Easy Add Repository tab.
-
On the tab, select GitLab in the Add repository for box and click Next:
Click the image to enlarge it.
-
Collaborator will displays a page with connection details.
Fill in the edit boxes:
Click the image to enlarge it.
Setting Description 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.
Group
Required only for group owned repositories (https://gitlab.com/GroupName/RepoName). Specifies the name of your GitLab group account (GroupName).
GitLab Community host name
Required for repositories on self-hosted servers. Specifies the host name of your GitLab Enterprise or GitLab Community server.
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.mdOverride existing configurations
Optional. Specifies whether to override existing configurations that track the same repository URI.
Branches to track
Optional. The names of branches to track changes and create reviews on pull 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 master 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. Note that wildcards and regular expressions cannot be used if you enable the Status check required setting (see below).When review completed
Optional. Specifies an action to perform when a review corresponding to a pull request was accomplished:
Value Description Do nothing Do not perform any action. Merge pull request Merge pull request that matches the review. Merge pull request and delete its branch Merge pull request that matches the review and delete the corresponding branch. Close pull request Close pull request that matches the review. Close pull request and delete its branch Close pull request that matches the review and delete the corresponding branch. When review cancelled/deleted/rejected
Optional. Specifies an action to perform when a review corresponding to a pull request was cancelled, deleted or rejected:
Value Description Do nothing Do not perform any action. Close pull request Close pull request that matches the review. Close pull request and delete its branch Close pull request that matches the review and delete the corresponding branch. 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 pull request is made,
- when a comment is added to a pull request,
- when a comment is added to commit which is a part of a pull request
-
After you specified the settings, click Load repositories. This will display a list of repositories available for the specified user account or organization in GitLab. Select the repositories to track and click Create for selected.
Alternatively, you can click Create for all and use the settings for all repositories that are available for the specified user account or organization in GitLab. Collaborator will create an individual configuration for each repository, and, if needed, will create a webhook for each repo in GitLab.
Configure Remote Systems tab
-
Log in to Collaborator as an administrator. (To configure integration settings, you need administrator privileges in Collaborator).
-
On the Collaborator main toolbar, click ADMIN, and then select Remote System Integration from the tree on the left. Then switch to the Configure Remote Systems tab.
-
In the New Remote System Configuration section, select GitLab and click Create:
Click the image to enlarge it.
-
Collaborator will display a page with configuration settings. Specify the setting values:
Setting Description Title
Required. The configuration name as it will be displayed in Collaborator user interface.
GitLab repo URI
Required. The URI of the GitHub 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:
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.mdBranches to track
Optional. The names of branches to track changes and create reviews on pull 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.If this edit box is empty, the branch master 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.When review completed
Optional. Specifies an action to perform when a review corresponding to a pull request was accomplished:
Value Description Do nothing Do not perform any action. Merge pull request Merge pull request that matches the review. Merge pull request and delete its branch Merge pull request that matches the review and delete the corresponding branch. Close pull request Close pull request that matches the review. Close pull request and delete its branch Close pull request that matches the review and delete the corresponding branch. When Review cancelled/deleted/rejected
Optional. Specifies an action to perform when a review corresponding to a pull request was cancelled, deleted or rejected:
Value Description Do nothing Do not perform any action. Close pull request Close pull request that matches the review. Close pull request and delete its branch Close pull request that matches the review and delete the corresponding branch. 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 pull request is made,
- when a comment is added to a pull request,
- when a comment is added to commit which is a part of a pull request
Webhook status
Indicates the current status of the webhook:
Status Description 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.To learn more about webhook settings on the GitLab side, see GitLab documentation:
https://gitlab.com/help/user/project/integrations/webhooks.md -
Click Test Connection to verify if you entered data correctly.
Click Save to store the settings.
3. Enable Configuration
After you finished configuring integration settings, you need to enable the integration:
- In Collaborator, go to ADMIN > Remote System Integration.
- Switch to the Integration Status tab. Here you can enable or disable integrations quickly.
- Find the Enable GitLab Integration setting and change it to Yes.
Click the image to enlarge it.
Now the integration between Collaborator and GitLab is configured and running.
4. Link Collaborator User Account to GitLab Account
The last step is to link Collaborator user accounts to the GitLab accounts. See —
Note: When linking accounts, enter the GitLab user name as it is specified in the Name edit field of the Profile GitLab settings. Do not use the account name.
Specifics
-
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.
-
To avoid creating reviews for merge commits, keep their messages default or start them with the Merge branch substring.
-
If a push or merge request in GitLab affects more than 200 files, the integration will process only first 200 files from the request and add those files to a review. This is caused by the limitation on the GitLab API side.
-
Currently, GitLab integration does not support connecting to the target GitLab server through the proxy server.
-
When configuring user remote accounts, user names must be entered as specified in the Name field of Profile settings (rather than the Account).
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.