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

info

Customize the remediation message and add your own to offer developers precise guidance for resolving their code issues and continuing their work.

Read more here - GitGuardian CLI custom remediation message

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.34.0
    hooks:
      - id: ggshield
        language_version: python3
        stages: [pre-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