Skip to main content
Version: v2

Secret scanning

A password or API token committed to Git stays in the history long after someone deletes the line, so you want to catch it before it merges. This page is for developers and leads on a project built from Vortex. It shows how to run the secret scan locally, ignore a false positive, and read the findings in continuous integration (CI).

Gitleaks catches those secrets: it scans the code for hardcoded secrets like passwords, API keys, and tokens, and fails the security audit when it finds one.

Usage​

Vortex doesn't install Gitleaks locally, so install it on your system first; see the Gitleaks installation instructions. Then run the scan from the project root:

gitleaks dir .

Gitleaks reads .gitleaks.toml from the directory it scans, so run the command from the project root. It prints only the number of findings by default; add -v to see each finding. On a clean codebase, the scan ends with no leaks found.

gitleaks dir scans the files on disk, the same as CI, and skips the Git history. To scan the history too, for example before you make a repository public, run gitleaks git ..

Configuration​

Global configuration lives in the .gitleaks.toml file at the repository root; see the Gitleaks configuration documentation. The file extends Gitleaks' default rule set and allowlists the following paths, which hold third-party, generated, or local-only files:

  • .artifacts/
  • .data/
  • .git/
  • .logs/
  • node_modules/
  • vendor/
  • web/core/
  • web/libraries/
  • web/modules/contrib/
  • web/sites/default/files/
  • web/themes/contrib/

Each pattern matches its directory at any depth. The scan then covers the code your team writes, so a clean install reports no findings while Gitleaks still detects real secrets.

Ignoring​

To ignore a single line you can edit, add a gitleaks:allow comment to it. Gitleaks skips every finding on a line that contains the comment, so the exception moves with the line:

$settings['example'] = 'not-a-real-secret'; // gitleaks:allow

For other exceptions, use 1 of the following:

  • To ignore a path or a known-safe value that recurs across the codebase, add an allowlist entry to the .gitleaks.toml file.
  • To ignore 1 finding on a line that can't hold a comment, such as a line in a JSON file, add its fingerprint to a .gitleaksignore file at the repository root. The fingerprint names the file, the rule, and the line number, so it stops matching when the line moves.

Copy the fingerprint from the Fingerprint: line that gitleaks dir . -v prints for the finding. The file takes 1 fingerprint per line and skips blank lines and lines that start with #:

# Fake token in a Behat fixture.
tests/behat/fixtures/response.json:generic-api-key:3

Confirm that the exception works: run gitleaks dir . -v again and check that the finding no longer appears. When it was the only finding, the scan ends with no leaks found.

Continuous integration​

Gitleaks runs from its official Docker image in the security audit workflow and fails that workflow when it finds a secret. The Vortex CLI turns the scan on by default. Answering no at its Scan for committed secrets with Gitleaks? prompt removes the CI steps and the .gitleaks.toml file.

Ignoring failures​

Set VORTEX_CI_GITLEAKS_IGNORE_FAILURE to 1 to let the workflow pass anyway. Gitleaks still runs and reports how many findings it made. In GitHub Actions, the details reach code scanning and the security-findings artifact; in CircleCI, run gitleaks dir . -v locally to see them.

➡️ See Ignore tool failures.

Where findings appear​

In GitHub Actions, the workflow also uploads Gitleaks findings to the repository's Security → Code scanning tab under the gitleaks category. Each finding becomes an alert naming the rule that matched, located at the line it was found on.

➡️ See Code scanning.

Dismissing a finding​

Dismissing an alert in the Security → Code scanning tab records a reason against that finding and removes it from the open list. That's the right tool for tracking an assessment.

The scan itself keeps matching the value and failing the workflow until you ignore it as described in Ignoring. That takes a gitleaks:allow comment on the line, an allowlist entry in .gitleaks.toml, or the finding's fingerprint in .gitleaksignore.