Integrate a new GitLab source

GitGuardian can integrate with GitLab in two different ways: at the instance level with system hooks or at the group level with group hooks.

info

Both integrations require a personal access token for GitGuardian to be able to create such webhooks and to subscribe to GitLab group/system's events for analysis.
You will need Owner or Manager rights in GitGuardian to set up an integration or customize your settings.

Please refer to the GitLab documentation for more information on system hooks and group hooks.

Setup

Create a Personal Access Token

We highly recommend that you use a bot user in order to generate personal access tokens.

1. Navigate to your GitLab user settings
2. Go to Access Tokens section
3. Create a personal access token with a simple name such as "GitGuardian" and api scope.
   The personal token enables GitGuardian to create webhooks through your GitLab permissions. It must have the api scope or we won't be able to create the necessary webhooks.

Please refer to the GitLab documentation for more information about personal access tokens.

Integrate your GitLab instance with system hooks

System hooks can only be created by an Administrator of the instance, they provide access to projects belonging to all users and groups. The system hook integration is only available for the on-premise version of GitLab (such an integration is not possible on GitLab.com).

tip

We recommend that you leverage a bot user when integrating with GitGuardian.

Requirements

• Self-managed GitLab: GitLab Community Edition or any plan of GitLab Enterprise Edition. v11.0+
• GitLab.com (SaaS): IMPORTANT GitGuardian cannot integrate with GitLab.com (SaaS) via System hooks.

Guidelines

1. Navigate to Settings > Workspace > Integrations.
2. Click on Configure for GitLab.
3. Click on Start for the system hook option: "Monitor the entire GitLab instance"
4. Submit your GitLab instance url and the personal access token created.
   
   caution

   GitLab instance URL must be prefixed with https://, instances without a secure connection won't be monitored.

5. GitGuardian will instantly start monitoring your GitLab instance. You can see the projects and groups monitored in your GitLab settings page by clicking on See my GitLab perimeter:
   

Events subscription details

Our system hook will subscribe to the following events:

• Repository update events
• Push events
• Merge request events

and SSL verification will be enabled.

Other events our system hooks will subscribe to but won't process:

• Tag push events
• Issues events
• Confidential issues events
• Comments
• Confidential comments
• Job events
• Pipeline events
• Wiki page events
• Deployments events
• Releases events
• Member events
• Subgroup events
• Feature flag events

Troubleshooting

• GitGuardian automatically detects if the system hook is deleted from GitLab side or if the Personal access token becomes invalid (by expiring or being revoked). We will send an email to notify you. All of your existing data will remain accessible.
• If your GitLab instance is marked as “not monitored" but the personal access token associated is still active, you can reactivate it by clicking on the synchronize button. It will recreate a system hook programmatically.
  
• If the token is invalid you can set a new personal access token by editing it:
  
• If the admin token is revoked, GitGuardian will detect it and automatically deactivate your GitLab integration if no other active token is present. If another token suitable for monitoring exists, the GitLab integration will use that token. All your existing data will remain accessible.

caution

IMPORTANT: Do not change the URL or the Personal access token of the system hook from the GitLab admin interface or this will break the integration.

Integrate your GitLab groups with group hooks

Group hooks require the user to have Owner permissions on the GitLab groups to be monitored. Group hooks do not support the monitoring of GitLab users personal projects. The group hook integration works for both GitLab on-premise and Gitlab.com.

tip

We recommend that you leverage a bot user when integrating with GitGuardian.

Requirements

• Self-managed GitLab: Starter plan and higher tiers. v13.5+
• GitLab.com (SaaS): Premium plan According to GitLab documentation, there is a limitation of 50 groups that you can integrate for GitLab.com.

Guidelines

1. Navigate to Settings > Workspace > Integrations.
2. Click on Configure for GitLab.
3. Click on Start for the group hook option: "Monitor only certain GitLab groups"
4. Submit your GitLab instance url and the personal access token, and make sure to name this personal access token as you might use several of them in the future to integrate more GitLab groups.
   
   caution

   GitLab instance URL must be prefixed with https://, instances without a secure connection won't be monitored.

5. You are then brought to the configuration page of your GitLab integration where you can see the list of all the GitLab groups and subgroups that your personal access token gives access to.
   Click Install for the GitLab groups and subgroups you want GitGuardian to monitor.
   
6. You can see the projects and groups monitored in your GitLab settings page
   

Installation remarks

• When you choose to install a GitLab group, all its sub-groups will also be installed automatically. In doing so, the "parent" group and "children" subgroups are linked together and if you only want to uninstall one subgroup, you will need to uninstall the "parent" group first.
• A GitLab group cannot belong to two personal access tokens. Therefore, when you want to install a "parent" group that has an already-installed subgroup you must first uninstall the "child" subgroup.

Events subscription details

Our group hooks will subscribe to the following events:

• Repository update events
• Push events
• Merge request events

and SSL verification will be enabled.

Other events our group hooks will subscribe to but won't process:

• Tag push events
• Issues events
• Confidential issues events
• Comments
• Confidential comments
• Job events
• Pipeline events
• Wiki page events
• Deployments events
• Releases events
• Member events
• Subgroup events
• Feature flag events

Troubleshooting

• You can submit new personal access tokens if you want to monitor more GitLab groups. Multiple tokens can be added for group hooks integration. If several tokens are associated with the same GitLab group, you have to choose which token will be monitoring it.
  
• If the token is revoked, the group will no longer be monitored (you can install it again with another token, but GitGuardian will not arbitrarily choose another token for you). In this scenario you'll receive an email informing of the unmonitored status of the integration.

Automatic historical scan

By default, GitGuardian performs a historical scan for each newly created GitLab project added to your perimeter.

You can deactivate this behavior in your GitLab settings if you are a Manager of the workspace.

Customize your monitored perimeter

Once you have set up your GitLab integration, you have the possibility to configure which projects to monitor in the GitLab settings section of your workspace.

If you deselect a project from your monitored perimeter:

• GitGuardian will no longer fetch the content of its commits, therefore you won't receive any alerts related to this project.
• The webhook installed on this project will still exist, therefore you can easily turn the monitoring back on at any moment.