Skip to main content

Pre-push

Prelude#

A pre-push hook is a client-side git hook that runs right before a reference is pushed to a remote (git push). Refer to our learning center for more information.

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

Preview#

pre-push preview

Installation#

The pre-commit framework#

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

  1. Make sure you have the pre-commit framework 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/ggshield    rev: main    hooks:      - id: ggshield-push        language_version: python3        stages: [push]
  1. Then install the hook with the command:
$ pre-commit install --hook-type pre-pushpre-commit installed at .git/hooks/pre-push

Now you're good to go!

To avoid long delays, the pre-push hook will not scan pushes with more than a 100 commits. This usually happens on the creation of a new branch.

Global pre-push hook#

To install pre-push 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 -t pre-push

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-push file which will be executed before every commit.
  • give executable access to this file.

Local pre-push 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 -t pre-push

Notes:

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

    You can force override with the --force option:

$ ggshield install --mode local  -t pre-push --force