A pre-commit secret scanner (Gitleaks, TruffleHog, detect-secrets, ggshield or Skylos) checks what you are about to commit and refuses the commit when it finds a key. It runs on your machine, so git commit --no-verify skips it, and AI coding agents sometimes do that when a hook fails. Pair it with an agent hook that denies the bypass and with a check the developer can't skip: a required CI job or GitHub push protection.

Gitleaks, TruffleHog, detect-secrets, ggshield and GitHub facts checked against their own docs on 21 Nov 2026. Skylos facts and output are for Skylos 5.7.0.

This page covers the four layers and the options in each, the Skylos hook configs with the output they printed in test repositories, which files each Skylos check reads, how an agent leaks a key and what stops it, and what each layer can't stop. For agent hook setup in general, see AI coding agent hooks.


Where should secret scanning run?

In four places, because each one can be skipped in a different way:

LayerRunsStopsSkipped byOptions (21 Nov 2026)
Pre-commit hookOn the developer's machine, at git commitA commit that adds a key--no-verify, SKIP=<hook id>, a clone where nobody ran pre-commit installGitleaks, TruffleHog, detect-secrets, ggshield, Skylos
Agent hookInside Claude Code, Codex or Cursor, around each tool callAn agent writing a key into a tracked file, reading or printing one, skipping the Git hookA person at the keyboard, a route the hook doesn't parse, a machine without the hookSkylos agent hooks, ggshield AI hooks
Push protectionOn GitHub, at git pushA push that contains a supported secret patternA bypass reason from anyone with write access (the default), private repositories without Secret ProtectionGitHub push protection
Required CI checkIn GitHub Actions on each pull requestThe mergeAn admin overriding branch protectionSkylos, Gitleaks Action, TruffleHog Action, ggshield

The pre-commit hook matters most because it acts before the key is in history. Once a key is committed, deleting the line in the next commit leaves it in history. GitGuardian's 26 Jun 2026 post describes commits with patterns that point to AI agents, where a later commit removes the key from the code while the earlier commit still holds it. At that point you rotate the key.


Which pre-commit secret scanners can you use?

All five ship a hook id for the pre-commit framework:

ToolHook idsWhat fails the commitAccount neededIgnore a findingLicence, latest release
Gitleaksgitleaks, gitleaks-docker, gitleaks-systemA rule match in staged changes (gitleaks git --pre-commit --redact --staged)Nogitleaks:allow comment, .gitleaksignore fingerprints, a baselineMIT, v8.30.1 (21 Mar 2026)
TruffleHogtrufflehogA credential TruffleHog verifies live with the provider (--results=verified --fail)Notrufflehog:ignore commentAGPL-3.0, v3.100.0 (19 Nov 2026)
detect-secretsdetect-secretsA secret that is not already in .secrets.baselineNopragma: allowlist secret comment, the baselineApache-2.0, v1.5.0 (6 May 2024)
ggshieldggshield, ggshield-push, Docker variantsA secret GitGuardian's API finds in staged changesYes, a GitGuardian API keyggshield secret ignoreMIT, v1.56.1 (26 Oct 2026)
Skylosskylos-scan, skylos-defend (remote), skylos agent pre-commit (local)A secret in the changed or staged files (details below)Noskylos: ignore[SKY-S101] on the line, a baselineApache-2.0, v5.7.0 (19 Nov 2026)

The configs, as each project documents them (we did not run these four):

repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.30.1
    hooks:
      - id: gitleaks
  - repo: https://github.com/trufflesecurity/trufflehog
    rev: v3.100.0
    hooks:
      - id: trufflehog
  - repo: https://github.com/Yelp/detect-secrets
    rev: v1.5.0
    hooks:
      - id: detect-secrets
        args: ["--baseline", ".secrets.baseline"]
  - repo: https://github.com/GitGuardian/ggshield
    rev: v1.56.1
    hooks:
      - id: ggshield

They decide differently, so the "What fails the commit" column is the real choice. One scanner in the hook is usually enough. Add a second kind in CI if you want history scans or live checks.

What each one does well

  • Gitleaks reads exactly the staged changes, redacts the value in its output, ships as one Go binary, and also scans whole Git histories (gitleaks git). Its README says, as of 21 Nov 2026, that Gitleaks is feature complete, that no new features will be merged and future releases are for security patches, and that its author is moving to Betterleaks.
  • TruffleHog checks whether a key works. It classifies over 800 secret types, and for each candidate it calls the provider's API (AWS's GetCallerIdentity, for example) to mark it verified, unverified or unknown. The shipped hook fails on verified keys alone, so a dead or fake key doesn't block you. Its pre-commit guide suggests --results=verified,unknown for a manual config.
  • detect-secrets is built for a large repository that already has secrets in it. You record the existing ones in .secrets.baseline and the hook blocks new ones, and detect-secrets audit lets you label the baseline. Its last release was in May 2024.
  • ggshield sends the scan to GitGuardian's API (500+ secret types per its README), which says it stores metadata such as call time and request size, not your files or secrets. It needs a GitGuardian account, and its pre-commit scans also send the machine hostname. It ships pre-push and pre-receive hooks and AI assistant hooks too.

What Skylos adds

Skylos runs locally and does not contact the credential's provider (docs/secret-scanning.md, v5.7.0). The same scanner runs in the pre-commit hook, the CI gate and the agent hooks, so one finding means the same thing in all three. The staged-files hook also runs Skylos's security and quality checks on the same files. It does not scan history and does not verify keys. Those are the two gaps the tools above fill.


How do you add Skylos to pre-commit?

There are two ways. Option 1 reads more file types. Option 2 adds security checks on the staged files.

Option 1: the shipped skylos-scan hook, with secrets args

repos:
  - repo: https://github.com/duriantaco/skylos
    rev: v5.7.0
    hooks:
      - id: skylos-scan
        name: skylos secrets (changed files)
        args: [".", "--secrets", "--diff-base", "HEAD", "--gate"]
        always_run: true

Then pre-commit install. What each line does:

  • --secrets turns the secrets scanner on. The shipped hook's default args run dead-code and security checks without it and report without failing the commit.
  • --diff-base HEAD limits findings to files changed since the last commit: staged, unstaged and untracked, but not the ones Git ignores. That keeps your ignored .env out of it (see the file table below).
  • --gate makes the hook exit 1 when any secret is found. The gate fails on any secret, whatever the other limits.
  • always_run: true is needed because the shipped hook is typed to Python files (types_or: [python]). Without it, a commit with no Python file never starts the hook. We committed a Terraform file holding a token without it:
skylos secrets (changed files).......................(no files to check)Skipped

The commit went through. With always_run: true, the same commit:

skylos secrets (changed files)...........................................Failed
- hook id: skylos-scan
- exit code: 1

--diff-base: 1 changed files (full scan on changed, defs/refs-only on rest)

 Quality Gate: FAILED
   • 1 secret (max: 0)
       SKY-S101  deploy/variables.tf:3  Potential github secret detected

Skylos 5.7.0 installed by pre-commit 4.7.0 from the v5.7.0 tag, 21 Nov 2026 (banner and exclude list cut). The git commit took 3.5 s in a four-file repository. A commit that declared the Terraform variable without a default passed, while the ignored .env held a token.

skylos-defend is the other shipped id. It runs skylos defend . --fail-on critical, a guardrail check for LLM integrations in Python and TypeScript/JavaScript, not a secrets check.

Option 2: skylos agent pre-commit, a local hook for staged files

repos:
  - repo: local
    hooks:
      - id: skylos-staged
        name: Skylos staged check (security, secrets, quality)
        entry: skylos
        args: ["agent", "pre-commit", "."]
        language: system
        pass_filenames: false
        require_serial: true

This uses the skylos on your PATH (pip install skylos). It reads the staged files, runs the secrets scanner plus security and quality checks on them, and reports findings on the changed lines. We staged a TypeScript file with a token hard-coded at the top:

const GITHUB_TOKEN = "ghp_<36 random characters>";

export async function listRepos(org: string) {
  const res = await fetch(`https://api.github.com/orgs/${org}/repos`, {
    headers: { Authorization: `Bearer ${GITHUB_TOKEN}` },
  });
  return res.json();
}

git commit -m "fix: GitHub API calls return 401" printed:

Skylos staged check (security, secrets, quality).........................Failed
- hook id: skylos-staged
- exit code: 1

Commit check: reviewing 1 source staged file(s). Checks security, secrets, and 
high-signal quality regressions on production source/config.
2 issue(s) found in staged files (1 security, 1 secrets):
  CRITICAL web/api.ts:1 Potential github secret detected
  CRITICAL web/api.ts:1 Potential hardcoded secret or API key. Use environment 
variables instead.
Scope: staged files only. Full repo and diff-aware enforcement run in CI.
Next: fix the issues below and commit again. Use `skylos .` for a full local 
scan when needed.
Note: this hook blocked the commit before Git created a new commit. If you push 
now, GitHub will still show this branch as identical to main.

Skylos 5.7.0, pre-commit 4.7.0, 21 Nov 2026 (15 progress lines cut). The git commit took 2.6 s. One key, two findings: the secrets scanner and the TypeScript security check both report it. The repository's .pre-commit-config.yaml pattern is the one Skylos uses on itself.

Which files does each one read?

One repository, one commit's worth of changes: a token in a TypeScript file, a Terraform file, a YAML config, a release script with no extension, a Markdown setup guide, and the Git-ignored .env. Three ways to scan it:

$ skylos . --secrets --category secret --format concise
web/api.ts:1  SKY-S101  Potential github secret detected
.env:2  SKY-S101  Potential github secret detected
config/settings.yaml:3  SKY-S101  Potential github secret detected
deploy/variables.tf:3  SKY-S101  Potential github secret detected
docs/setup.md:5  SKY-S101  Potential github secret detected
scripts/release:2  SKY-S101  Potential github secret detected

$ skylos . --secrets --diff-base HEAD --category secret --format concise
web/api.ts:1  SKY-S101  Potential github secret detected
config/settings.yaml:3  SKY-S101  Potential github secret detected
deploy/variables.tf:3  SKY-S101  Potential github secret detected
scripts/release:2  SKY-S101  Potential github secret detected
docs/setup.md:5  SKY-S101  Potential github secret detected

$ skylos agent pre-commit .
Commit check: reviewing 1 source and 1 config staged file(s). Checks security, 
secrets, and high-signal quality regressions on production source/config. 
Skipped 3 unsupported staged file(s).
3 issue(s) found in staged files (1 security, 2 secrets):
  CRITICAL config/settings.yaml:3 Potential github secret detected
  CRITICAL web/api.ts:1 Potential github secret detected
  CRITICAL web/api.ts:1 Potential hardcoded secret or API key. Use environment 
variables instead.

Skylos 5.7.0, 21 Nov 2026 (the last block's closing lines cut). The whole-tree scan reads the ignored .env, which is where a key belongs, so don't use it as a commit hook. --diff-base HEAD reads the five changed files. The staged check reads two and says it skipped three.

Staging one file at a time in a clean repository gave this, Skylos 5.7.0, 21 Nov 2026:

File typeOption 1 (--secrets --diff-base HEAD)Option 2 (agent pre-commit)
Python, TypeScript, JavaScript, Java, Kotlin, Go, PHP, Rust, DartReadRead
C#, Swift, RubyReadSkipped
Shell script ending in .sh, DockerfileReadRead
Shell script with no extensionReadSkipped
YAML, JSON, TOML, INIReadRead
.env and .env.* (committed by mistake)ReadRead
prod.env and other env namesReadSkipped
Terraform (.tf, .tfvars), .properties, XML, .npmrcReadSkipped
Markdown, textRead (provider-format keys and private keys)Skipped
A Git-ignored .envNot readNot read

Use Option 1 if your repository has config, infrastructure or docs files that could hold a key. Use Option 2 when you also want the security checks on staged code, and read the limits below.


How do AI coding agents leak secrets, and what stops them?

An agent leaks a key two ways, and it can also skip the hook that would catch it.

  1. It writes the key into a file. Asked to fix a 401, it pastes the token from your .env into the code. Your pre-commit hook runs on the agent's git commit too, but by then the key has been in an edited file for the whole session.
  2. It reads the key. Read .env or cat .env puts the value in the agent's context, and that text goes to the model provider. No commit is involved, so no Git hook sees it.
  3. It skips the hook. When the hook fails, the agent reruns the commit with --no-verify.

Skylos agent hooks cover each one inside the agent loop. Install them per project:

pip install skylos
skylos agent install-hooks --skylos-bin skylos            # Claude Code
skylos agent install-hooks --codex --skylos-bin skylos    # Codex
skylos agent install-hooks --cursor --skylos-bin skylos   # Cursor

skylos doctor checks that they still answer, in the same test repository:

  Agent hooks
  OK  Claude Code: 9 of 9 hooks in .claude/settings.json (project) → .../bin/skylos
      Self-test (passed): pre-bash allowed `ls` (0.2 s) and blocked `cat .env` of a file with a token (0.3 s)

The answers below came from piping Claude Code-shaped payloads to skylos hook <event> --client claude in the test repository, Skylos 5.7.0, 21 Nov 2026.

Writing a key into a tracked file

The agent rewrites web/api.ts with the token at the top (the TypeScript file above). post-edit runs after the write and answered in 0.84 s:

{
  "decision": "block",
  "reason": "Skylos found 1 issue(s) in the lines you just changed. Fix them before moving on:\n- web/api.ts:1 SKY-S101 Potential github secret detected -> Remove the hard-coded credential, load it from the environment or a secret manager, and rotate it if it was ever committed or shared.\nCheck again with: skylos hook recheck web/api.ts"
}

PostToolUse can't undo the write. It tells the agent to fix it before moving on. Writing the same token into the Git-ignored .env got no answer, because that is where it belongs. Writing it into the tracked .env.example was blocked.

Reading or printing a key

pre-read on Claude Code's Read of .env:

{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Skylos blocked reading .env: it contains 1 likely secret(s) (github secret) on line(s) 2. Reading it would send the credential to the model provider. Read only the lines you need with offset/limit that skip those lines, or ask the user to move the secret into the environment or a secret manager."}}

pre-bash on the same file through the shell:

CommandAnswer
cat .envdeny: "it would print 1 likely secret(s) (github secret) from .env line(s) 2"
grep PORT .envallowed, the printed line holds no secret
python3 -c "print(open('.env').read())"allowed, a program that opens the file itself is not followed

The messages name the file, the line and the kind of secret, never the value. The third row is the limit: per docs/agent-hooks.md at v5.7.0, pre-bash follows the commands agents usually write (cat, grep, sed, head, env, printenv and similar, through pipes, globs, loops and bash -c) and it is not a sandbox. find ... -exec cat, ... | xargs cat, git show HEAD:.env, docker compose config and a copy read back under another name get through, and so do files the secrets scanner doesn't read, such as ~/.aws/credentials. Codex has no pre-read hook because it reads files through the shell, so pre-bash is its read check.

Skipping the hook

With a pre-commit hook installed, pre-bash denied each bypass before it ran:

{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "Skylos blocked this command: it skips this repository's git hooks (--no-verify). Hooks that would not run: pre-commit. Fix what the hook reports, then run the command again without the bypass. If the hook fails for a reason unrelated to your change, stop and tell the user instead of skipping it."}}
CommandAnswer
git commit -m '...' --no-verifydeny (--no-verify)
SKIP=skylos-staged git commit -m '...'deny (SKIP=skylos-staged)
git -c core.hooksPath=/dev/null commit -m '...'deny (core.hooksPath=/dev/null)
rm .git/hooks/pre-commitdeny ("it turns off this repository's git hooks for later commands")
git commit -m '...'allowed

This is block_hook_bypass = true under [tool.skylos.hooks], the default. It also covers husky's HUSKY=0, lefthook's LEFTHOOK=0, git config core.hooksPath and a Git alias that adds --no-verify. A bypass counts when a hook it would skip is installed, so in a repository with no hooks --no-verify is allowed. On Codex and Cursor the same check runs on their shell hooks. The Codex hooks page shows the Codex answers.

Other agent options

ggshield installs AI coding assistant hooks for Cursor, Claude Code, Codex, Copilot CLI, VS Code, Mistral Vibe, Kiro and Junie CLI with ggshield machine setup. Per that page (updated 20 Nov 2026), they scan prompts before they reach the model, commands, file reads and MCP calls before they run, and tool output after. They fail open when ggshield can't reach GitGuardian or isn't signed in. You can also write a 15-line hook yourself. The agent hooks page has one that refuses --no-verify.

Every agent hook runs inside the agent's own loop. It is a guardrail. A person can still commit with --no-verify, and an agent can take a route the hook doesn't parse. That is why the next two layers exist.


What does git commit --no-verify skip?

Git's own help says -n, --no-verify bypasses the pre-commit and commit-msg hooks. The pre-commit framework also skips any hook id listed in SKIP, which the Gitleaks README shows as SKIP=gitleaks git commit. Nothing in the repository can stop a person from doing either, and a fresh clone has no hooks until someone runs pre-commit install. Treat the local hook as fast feedback and put the decision on the server.


How do you scan for secrets in GitHub Actions?

A job that scans the files a pull request changed and fails on any secret:

name: secrets
on: pull_request
permissions:
  contents: read
jobs:
  secrets:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
        with:
          python-version: "3.13"
      - run: python -m pip install skylos==5.7.0
      - run: skylos . --secrets --diff-base "origin/$BASE_REF" --gate
        env:
          BASE_REF: ${{ github.base_ref }}

The actions are pinned to the commits behind their v7.0.1 and v7.1.0 tags (checked 21 Nov 2026), and the base branch reaches the shell through env. Skylos's own GitHub Actions checks (skylos . --danger --quality) reported nothing on this file. With @v7 tags they reported SKY-D292, an action not pinned to a full commit SHA.

We ran the scan step locally on a branch that added a YAML file with a token, against origin/main. It exited 1:

--diff-base: 1 changed files (full scan on changed, defs/refs-only on rest)
 Quality Gate: FAILED
   • 1 secret (max: 0)
       SKY-S101  settings.yaml:3  Potential github secret detected

Skylos 5.7.0, 21 Nov 2026 (banner and exclude list cut). We did not run this workflow on GitHub for this page. fetch-depth: 0 gives the job the base branch to compare with.

skylos cicd init --no-upload writes a fuller workflow. Its Skylos Quality Gate job runs --secrets with the security, quality, AI-code and dependency checks on the pull request's changed lines, and needs no account. Other options: the Gitleaks Action (organization accounts need a free licence key from gitleaks.io, personal accounts don't), and TruffleHog's GitHub Action (trufflesecurity/trufflehog, documented in its README).

Whichever you pick, make the job a required status check in branch protection or a ruleset, and protect the workflow file, so a pull request can't edit the check that judges it.


Does GitHub push protection replace a pre-commit hook?

No, it is a different layer. It runs at git push, after the commit is already in your local history, and it blocks some secrets, not all. From GitHub's docs on 21 Nov 2026:

Public repositoryOrganization private or internal repository
Secret scanningRuns automatically, freeNeeds GitHub Secret Protection (Team or Enterprise Cloud)
Push protection for the repositoryFree (since 9 May 2023), off until an admin enables itNeeds GitHub Secret Protection
Push protection for usersOn by default for your pushes to public repositoriesNot covered

Two more facts from About push protection: by default, anyone with write access can bypass a block by giving a reason ("It's used in tests", "It's a false positive" or "I'll fix it later"), and delegated bypass lets admins require approval instead. GitHub's 2023 announcement says push protection "only blocks secrets with low false positive rates", and the docs say generic patterns, such as passwords, block pushes when an organization turns them on.

Turn it on wherever you have it. It also covers commits made in the GitHub web UI and through the REST API, which never pass through a local hook. It doesn't remove the need for the local hook, which stops the key before it is in any history, or for the CI check on private repositories without Secret Protection.


Where does Skylos fall short?

  • No history scan and no live check. Skylos reads the working tree and the changes. It doesn't walk old commits ("This implementation does not add Git-history ... collection", docs/secret-scanning.md v5.7.0) and doesn't ask the provider whether a key works. For an audit of an existing repository, use Gitleaks, TruffleHog or ggshield, then rotate what they find.
  • False positives. One key can be reported twice (secrets scanner plus the TypeScript, JavaScript and Java security checks), as in the outputs above. Documentation fixtures shaped like real keys, such as ghp_000...0, are reported because provider patterns have no randomness check. Long random IDs with no secret-like name can come back as HIGH. Mark a reviewed line with skylos: ignore[SKY-S101] on the same line (a real comment in TypeScript, Go, Java and the other C-like languages), or accept existing findings with skylos baseline . and --baseline. In Python, Option 2 also reports the same line as SKY-L014 (hard-coded credential), so list both:
SANDBOX_TOKEN = "..."  # skylos: ignore[SKY-S101, SKY-L014] shared sandbox

With that marker both options let the commit through, Skylos 5.7.0, 21 Nov 2026. A marker on the line above is not read.

  • Option 1 reads untracked files. --diff-base HEAD includes untracked files Git doesn't ignore. A stray file with a key blocked an unrelated commit in our test until we deleted it. It also parses the rest of the repository for references, so time it on a large repository before making it a commit hook.
  • Option 2 skips file types. See the table above.
  • Option 2 has a known issue in 5.7.0. When the repository root has no pyproject.toml, setup.py or package.json (a Go, Rust, PHP or Java project, say) and the working tree has another untracked or unstaged source file, the staged check can drop a secrets finding in a staged source file in a subfolder. In a PHP repository with one untracked .php file, a staged GitHub token passed. The TypeScript, Java and Go security checks still caught their keys in the same setup. Use Option 1 in those repositories until this is fixed.
  • Agent hooks are not a sandbox. See the read limits above. They also run on one machine: a teammate without Skylos installed gets no checks (the hooks fall back to allow), which skylos doctor reports.

Setup in 60 seconds

pip install skylos pre-commit
cd your-project
cat > .pre-commit-config.yaml <<'EOF'
repos:
  - repo: https://github.com/duriantaco/skylos
    rev: v5.7.0
    hooks:
      - id: skylos-scan
        name: skylos secrets (changed files)
        args: [".", "--secrets", "--diff-base", "HEAD", "--gate"]
        always_run: true
EOF
pre-commit install
skylos agent install-hooks --skylos-bin skylos
skylos cicd init --no-upload

If you already have a .pre-commit-config.yaml, add the hook entry to it instead of overwriting it. Then commit the config, .claude/settings.json and the workflow, make the Skylos job a required check, and turn on push protection if your plan has it. Nothing here needs an account or API key, and source stays on your machine. Package names from agent install commands and the CI dependency check go to the public registries and OSV.


Changelog

  • 21 Nov 2026: First version. Skylos 5.7.0 and pre-commit 4.7.0. Gitleaks, TruffleHog, detect-secrets and ggshield READMEs and hook files, ggshield's AI hooks page and GitHub's docs read the same day.

References