Skip to main content

Pre-receive

Prelude#

A pre-receive hook allows you to reject commits from being pushed to a git repository if they do not validate every check. Refer to our learning center for more information.

GitGuardian pre-receive 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.

You can find gg-shield's pre-receive hook samples in the doc/pre-receive.sample and doc/pre-receive-python.sample.

Installation#

Python git pre-receive hook#

⚠ This pre-receive hook requires the host machine to have python>=3.6 and pip installed

  1. Install gg-shield from pip: pip install ggshield
  2. Copy the template pre-receive-python.sample to .git/hooks/pre-receive
  3. Do not forget to chmod +x .git/hooks/pre-receive
  4. Create an API key within the API section of your GitGuardian workspace.
  5. Either set an environment variable machine wide GITGUARDIAN_API_KEY or set it in the .git/hooks/pre-receive as instructed in the sample file.

How do I add ignored matches and use a custom config in this pre-receive hook?

  1. Create a gitguardian.yaml somewhere in the system. An example config file is available here.

  2. Replace in the pre-receive hook

    ggshield scan commit-range "${span}" && continue

    with:

    ggshield -c <INSERT path to gitguardian.yaml> scan commit-range "${span}" && continue

Docker git pre-receive hook#

⚠ This pre-receive hook requires the host machine to have docker installed.

  1. Copy the template pre-receive.sample to .git/hooks/pre-receive
  2. Do not forget to chmod +x .git/hooks/pre-receive
  3. Create an API key within the API section of your GitGuardian workspace.
  4. Either set an environment variable machine wide GITGUARDIAN_API_KEY or set it in the .git/hooks/pre-receive as instructed in the sample file.

How do I add ignored matches and use a custom config in this pre-receive hook?

  1. Create a gitguardian.yaml somewhere in the system. An example config file is available here.

  2. Replace in the pre-receive hook

    docker run --rm -v $(pwd):/data -e GITGUARDIAN_API_KEY gitguardian/ggshield:latest ggshield scan commit-range "${span}" && continue

    with:

    docker run --rm -v $(pwd):/data -v <INSERT path of gitguardian.yaml directory>:/config -e GITGUARDIAN_API_KEY gitguardian/ggshield:latest ggshield -c /config/gitguardian.yaml scan commit-range "${span}" && continue