Skip to main content

GitLab

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

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.

GitLab personal access token

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).

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.

GitLab system hook form

  1. GitGuardian will instantly start monitoring your GitLab instance.

On this page, you can also submit new personal access tokens if you want to monitor more GitLab instances. 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) and 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.

GitLab system hook instances table

If the token is invalid you can set a new personel access token by editing it:

GitLab system hook edit

  1. You can see the projects and groups monitored in your GitLab settings page by clicking on See my GitLab perimeter:

GitLab system hook perimeter

Our system hook will subscribe to the following events:

  • Repository update events
  • Push events
  • Merge request events

and SSL verification will be enabled.

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

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.

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. That is why we recommend that you leverage a bot user when integrating with GitGuardian.

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.

Requirements#

  • Self-managed GitLab: Starter plan and higher tiers. v13.5+
  • GitLab.com (SaaS): Bronze plan and higher tiers. 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 GitHub.
  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.

GitLab group hook form

  1. 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. Note that installing a GitLab group automatically installs all its subgroups.

GitLab group hook configuration

On this page, you can also 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.

GitLab group hook new personal access token

  1. You can see the projects and groups monitored in your GitLab settings page

GitLab group hook perimeter

Our group hooks will subscribe to the following events:

  • Repository update events
  • Push events
  • Merge request events

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.

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

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.