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
Customize the remediation message and add your own to offer developers precise guidance for resolving their code issues and continuing their work.
Installation
The pre-commit framework
In order to use ggshield
with the pre-commit framework, you need to perform the following steps.
- Make sure you have pre-commit installed:
$ pip install pre-commit
- 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.33.0
hooks:
- id: ggshield
language_version: python3
stages: [commit]
- 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):
- Sign in to your GitGuardian workspace and create a Personal Access Token from your personal settings.
- Add this Personal Access Token (API key) to the
GITGUARDIAN_API_KEY
environment variable of your development environment. - 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:
- Sign in to your GitGuardian workspace and create a Personal Access Token from your personal settings.
- Add this Personal Access Token (API key) to the
GITGUARDIAN_API_KEY
environment variable in your repository. - 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