Git hooks

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

sonar integrate git installs Git hooks that scan your code for secrets at commit or push time. Installed hooks delegate to the CLI's Git hook handlers (sonar hook git-pre-commit or sonar hook git-pre-push), which run secrets scanning, with no extra tooling required. In an interactive terminal, the command prompts for install scope (project or global) when you omit both --global and --project, then prompts you to install each hook type (pre-commit and pre-push).

Pass --hook to install a specific hook without prompts, --global for a machine-wide install, or --non-interactive to install without confirmation (see Non-interactive install).

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)

# Interactive: prompts for pre-commit and pre-push separately
sonar integrate git

# Install a specific hook without prompts:
sonar integrate git --hook pre-commit
sonar integrate git --hook pre-push

In an interactive install, you can accept both hooks in one run. You can also install them one at a time by running the command again with a different --hook value.

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

# Without --hook: installs both pre-commit and pre-push
sonar integrate git --global --non-interactive

# Or pick one hook explicitly:
sonar integrate git --hook pre-commit --global --non-interactive

In non-interactive mode the CLI does not prompt for scope or feature selection; scope defaults to project when you omit --global, and without --hook it installs both hook types. 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 a local hook entry that runs sonar hook git-pre-commit or sonar hook git-pre-push with the changed filenames (pass_filenames: true).

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