Overview

Betterleaks scans source code for exposed passwords, API keys, and tokens.

The plugin embeds the Betterleaks Go SDK and scans the existing local Git checkout by default. It uses the built-in detection rules, recursive decoding up to five levels, and archive traversal up to eight levels. It does not validate credentials against provider APIs or revoke them.

Settings

The container uses its binary as the entrypoint; use settings, without a commands section.

clone:
 git:
  image: docker.io/woodpeckerci/plugin-git
  settings:
   partial: false
   depth: 0

steps:
 secrets:
  image: codeberg.org/woodpecker-plugins/betterleaks

For a current-file scan instead:

steps:
 secrets:
  image: codeberg.org/woodpecker-plugins/betterleaks
  settings:
   mode: filesystem

Pin released image tags for production use.

Setting	Default	Description
mode	git	Scan available Git history or the current filesystem.
path	.	File or directory to scan. In git mode, the history of the files under it.
revision	empty	Git revision or A..B range. Requires git mode.
ignore_file	empty	Fingerprint file to use instead of .betterleaksignore at path. Must exist.
ignore	empty	List of secret fingerprints to ignore, in addition to the ignore file.

Settings are also available as CLI flags (--path, --ignore-file) and PLUGIN_ environment variables. For example, ignore_file maps to PLUGIN_IGNORE_FILE.

Output

The log has two collapsible groups: preparing the scan (including fetching the history of a shallow clone) and the scan itself. Each finding is a colored warning line with its rule ID, file path, line number, and secret fingerprint, plus the commit SHA for Git findings. Any finding that is not ignored fails the step, as do scan and output errors. Secret values, source lines, and surrounding code are never included.

The plugin does not load repository-local Betterleaks configuration. The standard betterleaks:allow and gitleaks:allow markers are honored. In filesystem mode, the .git entry inside the scan root is excluded. Reading its raw files is not a Git-history scan.

Symlinks are not followed. Files excluded by Betterleaks' built-in rules and content beyond its size, diff, or archive limits are not scanned. Betterleaks diagnostics about skipped inputs are logged as warnings.

Ignoring secrets

A betterleaks:allow marker only works on the current line. To ignore a secret that is already in the Git history, for example after it was rotated, list its fingerprint. A fingerprint is the SHA-256 of the exact secret value, as reported in the fingerprint field of each finding or printed by betterleaks fingerprint. It ignores the secret everywhere, independent of rule, path, and commit.

The plugin reads .betterleaksignore at path, or next to path if it is a file, when that file exists. ignore_file names another file instead and fails the step if it is missing. Each line holds one fingerprint; blank lines and # comments are allowed, and invalid lines are skipped with a warning. Fingerprints in the ignore setting are added to those of the file; an invalid one fails the step.

steps:
 secrets:
  image: codeberg.org/woodpecker-plugins/betterleaks
  settings:
   ignore:
    - ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

The ignore file and settings come from the scanned repository, so a change can ignore its own secrets; review changes to them. A fingerprint of a short or guessable secret can be brute-forced, so rotate secrets rather than only ignoring them.

Git history

Git mode finds secrets in committed additions even if later commits removed them. It scans the history reachable from HEAD and available refs, including merge patches. It does not scan uncommitted changes; use mode: filesystem for those.

In git mode, path must be inside a Git repository. A subdirectory or file limits the scan to the history of the files under it. A missing path, or one outside a Git repository, fails the step.

Configure the clone step with partial: false and depth: 0 for a full history audit; plugin-git's default partial: true makes a shallow clone of one commit.

On a shallow clone the plugin prints a warning and fetches the full history of HEAD from the origin remote over HTTP(S), using the clone credentials when Woodpecker provides them to the step (CI_NETRC_*). If that fails, or the clone uses the partialclone extension that Betterleaks cannot read, the step fails. The plugin never fetches other refs.

Revision ranges require both endpoints to exist locally; invalid selections fail the step.

Scope

Only local paths are accepted. The plugin needs no privileged mode, does not clone repositories, and does not execute workspace commands. It only uses the network to complete a shallow clone. The scratch image contains no shell or Git executable.

Multi-platform builds target Linux amd64 and arm64. The image includes a writable /tmp directory for archive processing and the bundled dependencies' license notices.