Skip to main content

Pre-commit

Prelude#

A pre-commit hook is a client-side git hook that runs right before the commit is created. Refer to our learning center for more information.

GitGuardian pre-commit hook is performed through our CLI application gg-shield. gg-shield is a wrapper around GitGuardian API for secrets detection that requires an API key to work.

Preview#

pre-commit preview

Installation#

The pre-commit framework#

In order to use gg-shield with the pre-commit framework, you need to perform the following steps.

  1. Make sure you have pre-commit installed:
$ pip install pre-commit
  1. Create a .pre-commit-config.yaml file in your repository's root path:
repos:  - repo: https://github.com/gitguardian/gg-shield    rev: main    hooks:      - id: ggshield        language_version: python3        stages: [commit]
  1. Then install the hook with the command:
$ pre-commit installpre-commit installed at .git/hooks/pre-commit

Now you're good to go!

Note: If you want to skip the pre-commit check, you can add -n parameter:

$ git commit -m "commit message" -n

Another way is to add SKIP=hook_id before the command:

$ SKIP=ggshield git commit -m "commit message"

Global pre-commit hook#

To install pre-commit globally (for all current and future repos):

  1. Create an API key within the API section of your GitGuardian workspace.
  2. Add this API key to the GITGUARDIAN_API_KEY environment variable of your development environment.
  3. Execute the following command:
$ ggshield install --mode global

It will:

  • verify that if a global hook folder is defined in the global git configuration.
  • create the ~/.git/hooks folder (if needed).
  • create a pre-commit file which will be executed before every commit.
  • give executable access to this file.

Local pre-commit hook#

You can install the hook locally on desired repositories:

  1. Create an API key within the API section of your GitGuardian workspace.
  2. Add this API key to the GITGUARDIAN_API_KEY environment variable in your repository.
  3. Go in the repository and execute the following command:
$ ggshield install --mode local

Notes:

  • If a pre-commit executable file already exists, it will not be overridden.

    You can force override with the --force option:

$ ggshield install --mode local --force
  • If you already have a pre-commit executable file and you want to use gg-shield, all you need to do is to add this line in the file:
$ ggshield scan pre-commit
  • If you want to try pre-commit scanning through the docker image:
$ docker run -e GITGUARDIAN_API_KEY -v $(pwd):/data --rm gitguardian/ggshield ggshield scan pre-commit