Pre-commit

Prelude

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

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

Preview

Installation

The pre-commit framework

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

1. Make sure you have pre-commit installed:

$ pip install pre-commit

2. Create a .pre-commit-config.yaml file in your repository's root path with the following content:

repos:
  - repo: https://github.com/gitguardian/ggshield
    rev: v1.26.0
    hooks:
      - id: ggshield
        language_version: python3
        stages: [commit]

3. Then install the hook with the command:

$ pre-commit install
pre-commit installed at .git/hooks/pre-commit

Now you're good to go!

Note: If you want to skip all the pre-commit checks, you can add the -n parameter as follows:

$ git commit -m "commit message" -n

Alternatively if you only want to skip ggshield, you can use SKIP=ggshield 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. Sign in to your GitGuardian workspace and create a Personal Access Token from your personal settings.
2. Add this Personal Access Token (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 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. Sign in to your GitGuardian workspace and create a Personal Access Token from your personal settings.
2. Add this Personal Access Token (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 overriding with the --force option:

$ ggshield install --mode local --force

• If you already have a pre-commit executable file and you want to use ggshield, all you need to do is to add this line in the file:

$ ggshield secret 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 secret scan pre-commit

Was this page helpful?