Git hooks

Block commits and pushes that contain secrets with a Git hook installed and managed by the SonarQube CLI.

Warning: This product is in Beta stage and we may release breaking changes.

sonar integrate git installs a Git hook that scans your code for secrets at commit or push time. The hook calls sonar analyze secrets automatically—no extra tooling required.

Prerequisites

• The SonarQube CLI is installed and authenticated.

• A Git repository (for project-scoped installs).

Choose pre-commit or pre-push

The CLI supports two hook types. Both stop a secret from leaving your machine, but at different moments:

Hook	Fires when…	What it scans	Trade-off
pre-commit	You run git commit	Staged files	Catches secrets the earliest. Runs on every commit, which is slower for big change sets.
pre-push	You run git push	Files changed in unpushed commits	Catches secrets just before they leave your machine. Lets you git commit freely locally.

For most teams, pre-commit is the right default—it catches secrets before they enter local history. Choose pre-push if your developers commit constantly and want a single batched check before sharing.

Install

Per repository (default)

# Pre-commit (default)
sonar integrate git

# Or explicitly:
sonar integrate git --hook pre-commit
sonar integrate git --hook pre-push

You can install both hooks in the same repo. Run the command twice with different --hook values.

Globally for every repository

sonar integrate git --global

Globally-installed hooks live in ~/.sonar/sonarqube-cli/hooks/. The CLI sets git config --global core.hooksPath to that directory so every Git repo on your machine uses them, unless a repo has its own hooks path.

Non-interactive install (for provisioning)

sonar integrate git --hook pre-commit --global --non-interactive

In non-interactive mode the CLI does not prompt; it fails fast on conflicts. Combine with --force to overwrite a pre-existing hook (see below).

How the CLI handles existing hooks

When you install per-repo, the CLI looks at your project's hook setup in this order:

1. Husky (.husky/ directory): the CLI registers via Husky.

2. pre-commit framework (.pre-commit-config.yaml): the CLI adds itself as a pre-commit framework hook.

3. Plain Git hooks (.git/hooks/): the CLI writes a hook script directly.

If a hook already exists in the target location and was not installed by sonar integrate git, the command refuses to overwrite it. Pass --force to overwrite:

sonar integrate git --force

This is safe to do when you want SonarQube secrets scanning to chain with an existing hook script — a marker comment identifies the hook, so subsequent sonar integrate git runs recognize and update it without --force.

Verify the hook

1. Create a file with a fake-looking but secret-shaped value:

   // secrets.js
   const API_KEY = "sqp_1aa323ae0689cd4a1abd062a2ad0a224ae8a1d13";

2. Stage and try to commit:

   git add secrets.js
   git commit -m "Test"

3. The commit should be blocked and the secret reported.

Delete the test file once confirmed.

Bypass the hook

If you need to skip the hook for a single commit — for example, while running a script that the hook would interfere with — use Git's built-in --no-verify flag:

git commit --no-verify

Warning: Use --no-verify sparingly. The whole point of the hook is to catch secrets before they enter your history. Prefer fixing the offending file over bypassing the check.

Uninstall

To remove the hook:

• Per-repo (plain Git hooks): delete the file in .git/hooks/pre-commit (or pre-push). The CLI marks its hooks with a comment so you can identify them.

• Per-repo (Husky / pre-commit framework): remove the SonarQube entry from your Husky scripts or .pre-commit-config.yaml.

• Globally: unset the global hooks path with git config --global --unset core.hooksPath and delete the directory at ~/.sonar/sonarqube-cli/hooks/.

See Uninstalling for the full removal procedure.

Related pages

• Secrets scanning

• Claude Code

• GitHub Copilot

• Exit codes