GitLab Pre-Hook Configuration

Overview

This page contains all the information needed to install and configure the GitLab pre-hook. This is needed to allow GuardRails to scan Git commits for vulnerabilities before they are accepted and included in the remote Git repository.

Note: The pre-hook will only do a light scan, which will look for passwords and secrets in the commit.

Install the GitLab pre-hook plugin

The Guardrails GitLab pre-hook plugin can be installed per project or globally, read more here on how to install it on the different levels in GitLab.

Here's an example on how it could look like when installing the plugin on global level.

Configure GitLab pre-hook

The name of configuration file is guardrails-config.yml and can be found in your GitLab instance in the same folder as where you installed the pre-hook plugin.

enabled: true # Enable or disable the plugin completely.
pre_hook_token: 'my-secret-pre-hook-token' # The pre hook token secret as it is defined in the replicated settings.
guardrails_url: 'https://guardrails-instance.example.com' # URL to your GuardRails on-premise service.
trust_all_certificates: false # Set this to true if you are using self-signed certificates.
scan_timeout: 60 # How long time we will wait for all scans to finish (in seconds).

Enable/disable the GitLab pre-hook

You can enable or disable the GitLab pre-hook in the dashboard settings on either account level or on repository level, where the configuration on repository level will override the configuration on account level.

You can find the pre-hook configuration on account account level here:

You can find the pre-hook configuration on repository account level here:

Note: If the repository is disabled in the repository list then the pre-hook will also be disabled. So make sure that you have it enabled in the list if you want to use the pre-hook.

Test the pre-hook

To test if the pre-hook is working, clone the repository and make a new commit and push it to the remote repository. If the commit doesn't contain any vulnerabilities the Git push will finish successfully and a message will be displayed in the terminal that the scan was finished with no vulnerabilites found.

If one or more vulnerability is found then the commit the Git push command will fail and a message will be displayed in the terminal (see screenshot below).

Supported GitLab server versions

GitLab server hooks is only supported for on-premise installations of GitLab. The GuardRails pre-hook for GitLab is only supported for GitLab version 12.8 and above as Server hooks was first introduced in GitLab 12.8.