How to set commit range of secret scanning using SECRET_DETECTION_LOG_OPTIONS

Description

When using pipeline secret detection, only the current state of the repository and future commits are scanned for secrets. This behavior can be modified by customizing the SECRET_DETECTION_LOG_OPTIONS variable.

This article covers how to customize this variable to enable secret detection outside the default behavior.

Environment

Impacted offerings:

GitLab.com
GitLab Dedicated
GitLab Self-Managed

Prerequisites

Include the Secret-Detection CI template in your pipeline yaml file:

include:
  - template: Jobs/Secret-Detection.gitlab-ci.yml

Solution

Apply a custom scan range by updating the pipeline yaml file to include the SECRET_DETECTION_LOG_OPTIONS variable.

secret_detection:
  variables:
    SECRET_DETECTION_LOG_OPTIONS: <custom range>

The structure follows the git-log format.

You can use git variables such as, HEAD or origin, and predefined GitLab variables.

Scan between two specific commits

To scan a specific revision range between two commits, use ...

In this example, all commits after origin up to and including 295e57e9 will be scanned.

secret_detection: 
  variables:
    SECRET_DETECTION_LOG_OPTIONS: origin..295e57e9

Scan x number of commits behind

To scan a specific number of commits behind, you can use the ~ operator.

In this example, the scanner checks the commits between HEAD and the 3 previous commits.

secret_detection:
  variables:
    SECRET_DETECTION_LOG_OPTIONS: HEAD~4..HEAD

Additional Information

For scheduled scan execution policies, secret detection by default runs first in historic mode (SECRET_DETECTION_HISTORIC_SCAN = true). All subsequent scheduled scans run in default mode with SECRET_DETECTION_LOG_OPTIONS set to the commit range between last run and current SHA.