gitleaks-action: scanning a repository for leaked secrets on every push

What the action actually does in a workflow

Gitleaks itself is a SAST tool for detecting and preventing hardcoded secrets like passwords, API keys and tokens in git repositories, and the action is the piece that runs it inside GitHub Actions so that you are alerted when secrets are leaked as soon as they happen.

The workflow the README documents is short, and every part of it earns its place:

name: gitleaks
on:
  pull_request:
  push:
  workflow_dispatch:
  schedule:
    - cron: "0 4 * * *" # run once a day at 4 AM
jobs:
  scan:
    name: gitleaks
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - uses: gitleaks/gitleaks-action@v3
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }} # Only required for Organizations, not personal accounts.

The fetch-depth: 0 setting on the checkout is the detail that catches people out. A default checkout is shallow, with only the most recent commit, and a secret that was introduced and then removed two commits ago is invisible in a shallow history. Fetching the full history is what lets the scanner answer the past as well as the present, which is the difference between a scanner that prevents leaks and one that reports them after the fact.

The four triggers cover the realistic cases. A pull request trigger catches a leak before merge, a push trigger catches a direct commit, workflow_dispatch lets you run it by hand, and the schedule entry runs a daily sweep at 4 AM, which is the safety net for secrets that arrive by a route the other triggers do not see, such as a merge from a branch that was never scanned.

The GITHUB_TOKEN is assigned automatically by GitHub when any action starts, and the action uses it to call a GitHub API to comment on pull requests. That is the mechanism behind the review comments, and it is why the token has to be in the environment block rather than passed as an input.

The environment variables are the real configuration surface

There are seven environment variables, and the defaults are chosen well enough that a minimal workflow works. It is worth reading each one, because each turns a behaviour on that you might want off.

GITLEAKS_LICENSE is required for organizations and not for user accounts. The licence is obtained at gitleaks.io and should be added as an encrypted secret to the repo or to the organization. The Questions section explains why this is a real distinction rather than a pricing quirk: if you are scanning repos that belong to an organisation account you need a licence key, and if the repos belong to a personal account you do not. Signing up is a form asking for name, email and company, and the key arrives by email.

GITLEAKS_NOTIFY_USER_LIST takes a comma-separated list of GitHub accounts to alert, each prefixed with an @, for example @octocat,@gitleaks, with spaces allowed. GitHub sends the email if the user's notification settings permit it, which is a caveat worth noting: the delivery depends on the recipient's own configuration, not on yours.

GITLEAKS_ENABLE_COMMENTS is a boolean that turns PR commenting on and off, defaulting to true. GITLEAKS_ENABLE_UPLOAD_ARTIFACT controls whether a SARIF artifact is uploaded when secrets are found, also defaulting to true. GITLEAKS_ENABLE_SUMMARY does the same for the gitleaks job summary, again defaulting to true.

GITLEAKS_VERSION is the one to think about hardest. You can pin a particular Gitleaks version, for example 8.15.3 with no v prefix, or use latest to always get the newest available version. The default is a hard-coded version number, which means a workflow that does nothing about it will get a new scanner version whenever the action is updated. Pinning it explicitly is the more predictable choice, at the cost of needing to bump it deliberately to pick up new detection rules.

GITLEAKS_CONFIG points at a gitleaks configuration file, and the Questions section adds that the action follows a similar order of precedence as the CLI: you can set the path explicitly with that variable, or create a gitleaks.toml at the root of the repo and it will be detected and used automatically.

v3 is a runtime migration, and the deadline it responds to is real

The migration section is short because the change is small, but the reasoning matters for anyone still on v2.

v3 migrates the GitHub Actions runtime from Node 20 to Node 24, and there are no changes to inputs, outputs or behavior. The upgrade is a one-line change in the workflow file, from gitleaks/gitleaks-action@v2 to @v3, plus a bump of actions/checkout to v6, which is the Node 24 release. The README also suggests updating actions/checkout from v3 or v4 to v6.

The reason is a deprecation with two dates. On June 2, 2026 GitHub switches the runner default to Node 24, and workflows using Node 20 actions, including gitleaks-action@v2, require ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION=true to keep running. Without that opt-out, Node 20 actions fail. On September 16, 2026 Node 20 is removed from GitHub-hosted runners entirely, and gitleaks-action@v2 stops working regardless of any opt-out flag.

Both of those dates are behind us as of now, which means a workflow still on v2 is not merely discouraged, it is broken. That is a useful piece of context for anyone evaluating the action now: the v2 line is a dead end rather than an option.

There is a runner requirement attached to v3 as well. It requires GitHub Actions runner v2.327.1 or later, and all current GitHub-hosted runners meet it. Self-hosted runner operators should update their runner before upgrading to v3, which is the one case where the migration is more than a two-line diff.

Why the README warns against using it for code scanning

The Questions section contains an answer that is worth more than the others, because it is the project telling you not to do the obvious thing.

You can use gitleaks-action as a third-party tool for GitHub code scanning, and the README says you can but that it is not recommended because it gives a false sense of security. The reason is a specific and correct one. If a secret is leaked in one commit and then removed in a later commit, the security alert in the GitHub Security dashboard shows as resolved, even though the secret is still visible in the commit history.

This is a general property of secret scanning rather than a flaw in the action. A tool that scans the current state of a tree reports the current state, and a removed secret is not in the current state. The history is where the secret still lives, and the alert that says resolved is reporting the tree, not the repository.

The advice that follows is the correct response: to truly address the leak, you should rotate the secret, and also consider rewriting the git history to remove the leak altogether. Rotation is the part that actually closes the exposure, because a credential that was committed has to be assumed compromised regardless of what the tree says today.

So the action is a prevention and detection mechanism for the moment of introduction. It is excellent at telling you a secret just landed in a pull request you are reviewing, and it is not a complete account of what is in your repository. The daily scheduled run partly compensates by scanning history, and the fetch-depth: 0 setting is what makes that scan meaningful.

The licence changed, and the repository is mostly build output

The licence story is unusual and worth reading before you build on this. Since v2.0.0 of Gitleaks-Action the licence has changed from MIT to a licence file, LICENSE.txt, and versions prior to v2.0.0 remain under MIT. The package.json records the licence field as SEE LICENSE IN COMMERCIAL-LICENSE.txt, and the repository carries the copyright notice for Gitleaks LLC with all rights reserved.

So the historical MIT expectation does not apply to anything you use now, and the terms live in a file you have to read rather than in a well-known identifier. For an organisation with a legal review process, that file is the starting point.

The repository layout is the other thing to understand. The top level holds action.yml, the GitHub Actions metadata, plus src/ for the action source, a dist/ directory, package.json, package-lock.json, a .nvmrc, a .gitleaksignore, and files including v2.md for the previous major version, RELEASING.md, SECURITY.md, CONTRIBUTING.md, the licence file and the README.

The dist/ directory with an ncc dependency in the dev dependencies is the giveaway that this is a bundled action rather than one that runs from source. GitHub Actions executes whatever is checked into the repository, so a JavaScript action has to ship its dependencies with it, and ncc is the bundler that produces the single committed file. That has a consequence for you as a user: you are running the committed bundle, and reviewing it means reading the bundled output rather than the source in src/.

The dependencies themselves are the standard Actions toolkit: the artifact, cache, core, exec and tool-cache packages, plus @octokit/rest for the GitHub API calls that produce the pull request comments. The runtime dependency set is small and legible, which is a reasonable property for something that executes with a token in your repository.

The badge, and what it does and does not claim

There is a small feature in the Questions section that is easy to overlook and that some teams will want anyway. You can get a gitleaks badge on your readme by enabling the action and copying a specific img tag into the README.

The badge says protected by gitleaks, and what it asserts is narrow and accurate: the repository runs this scanner in its workflows. It does not assert that the repository contains no secrets, because the scanner reports on the commits it sees, and a secret that entered before the action was enabled, or through a path the triggers do not cover, is not covered by the badge.

The same caution applies to the daily scheduled run, which is a genuine improvement over pull request only scanning but is still a point-in-time scan of the history as it exists at that moment.

For a team that is rolling this out across an organisation, the practical sequence suggested by the README is straightforward. Enable the action in one repository first, with the licence key in place, and watch what it reports. The most common outcome is a list of historical findings, because most repositories that have been developed for years contain something, and the decision about each one is whether to rotate it, ignore it with the gitleaksignore file, or rewrite the history. The .gitleaksignore file at the repository root is the mechanism for the second of those three answers.

Editorial conclusion

Adopt gitleaks-action if you want secret detection running automatically on every pull request and push, and if you can add the licence key the organisation tier requires, since a personal repository needs none. Do not adopt it as a substitute for rotating a leaked credential, because the README is explicit that a secret removed in a later commit still shows as resolved in the security dashboard even though it remains in the history, and the real fix is rotation. Before you commit, read the environment variable list and set GITLEAKS_ENABLE_COMMENTS and GITLEAKS_ENABLE_UPLOAD_ARTIFACT to suit your repository, decide whether to pin GITLEAKS_VERSION rather than track latest, and check your runner version against the v2.327.1 requirement if you use self-hosted runners.

Frequently asked questions

Official sources

1. gitleaks/gitleaks-action on GitHub
2. Issues
3. README
4. Releases