Shift Left on Security: Catch Secrets Before They Hit Your GitLab Repo (with Gitleaks)

When it comes to securing your codebase, scanning for accidentally committed secrets like API keys, passwords, or tokens is a must.

If you’re using GitLab CI/CD, GitLab already provides a built-in CI/CD template for secret detection.

GitLab’s Secret Detection tool is powered by Gitleaks, an open-source secrets scanning tool developed by Zachary Rice.

The Gitleaks tool can be run as a standalone job in the GitLab pipeline. However, using the template does offer advantages.

Gitleaks uses regex rules, which are defined in a configuration file) for scanning git commit history to do entropy checks for detecting high-entropy values like random-looking strings.

If you want to learn more about how Gitleaks detection engine works read this blog entry.

Setup

Extend your .gitlab-ci.yml with this:

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

secret_detection:
  stage: .pre

With this you get:

• A pre-configured job that runs the secret detection tool in the .pre stage
• Integration with GitLab’s Security Dashboard
• Artifacts and reports in a standardized format

Customization

Create a file named .gitleaks.toml in your project root and customize detection rules and exclusions. Here you can see a sample configuration file.

Local Testing

Install Gitleaks on your macOS:

brew install gitleaks

Execute the following command:

gitleaks detect --source . --config .gitleaks.toml --report-format json --report-path gl-secret-detection-report.json 

This will create a file named gl-secret-detection-report.json containing the findings.

Executing in CI/CD

The job checks the latest commits only. When a secret is flagged the job fails a warning, but doesn’t block the pipeline.

When you want to block the pipeline set

secret_detection:
  allow_failure: false

Merge Request Integration

From now on, when merge requests are opened, a new section will be displayed where the report can be downloaded.

End

Security shouldn’t be an afterthought, and with applying available tools, it doesn’t have to be. By adding a few lines to your pipeline config, you gain a powerful safeguard against accidental leaks.