ggshield Documentation

Use the create-ghe-environment script to create a GHES pre-receive hook environment containing GGShield.

Requirements:

• Docker: Must be installed on your machine.
• Architecture: The script must be run on the same machine architecture as the target GHES server where the environment will be uploaded.

For more details on GHES pre-receive hooks, refer to the official GitHub Enterprise Server documentation.

To update a specific dependency within the GGShield project, follow these steps:

1. Update the dependency version in pyproject.toml.
2. Apply any necessary code changes required by the new version.
3. Update the lock file by running uv lock --upgrade-package <dependency>.
4. File a Pull Request.

For testing purposes related to ggshield check-secret-manager hashicorp-vault, you can run a local Hashicorp Vault instance using a provided helper script. This server runs on the default Vault port 8200 and includes pre-populated test data and specific tokens designed to avoid triggering ggshield scans.

Server Details:

• Port: 8200
• Web UI: http://127.0.0.1:8200
• Pre-populated KV Mounts:
  • secret_v1 (version 1)
  • secret (version 2)
• Available Tokens:
  • my_vault_token: Root token with all rights.
  • restricted_token: Token with the default policy (cannot read KV mounts; useful for testing error handling).

To ensure changes in an unreleased version of py-gitguardian pass in Continuous Integration (CI), you must point the dependency to a specific git commit using a git+https URL in pyproject.toml and update the lock file.

1. Update the pygitguardian entry in pyproject.toml to use a git URL with a specific commit hash:

dependencies = [
    (...)
    "pygitguardian @ git+https://github.com/GitGuardian/py-gitguardian.git@<commit_hash>"
    (...)
]

2. Update the lock file using uv:

uv lock --upgrade-package pygitguardian

dependencies = [
    (...)
    # TODO: replace this with a real version number as soon as a new version of
    # py-gitguardian is out
    "pygitguardian @ git+https://github.com/GitGuardian/py-gitguardian.git@cfa919cff68cc4d3ca40bf2bb8a6f245fca786"
    (...)
]

The quickest way to install ggshield is via the official installation scripts. These scripts support options like --instance (to specify a custom GitGuardian instance) and --plugin (to install a plugin).

For EU workspaces or self-hosted instances, set the GITGUARDIAN_INSTANCE environment variable before running the script.

Linux / macOS:

curl -sSfL \
  https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.ps1 | iex

Windows (using curl):

curl.exe -sSL https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.ps1 | powershell -NoProfile -ExecutionPolicy Bypass -Command -

To set up a development environment for ggshield, follow these steps:

1. Install uv.
2. Install the pre-commit framework.
3. Fork and clone the repository.
4. Install development packages and create the environment using uv:

   uv sync --all-groups
   source .venv/bin/activate

5. Install the pre-commit hooks:

   pre-commit install
   pre-commit install --hook-type commit-msg

If you are developing changes in py-gitguardian and want to test them within ggshield on your local machine, you can install your local checkout in editable mode. This only needs to be done once; subsequent changes in your py-gitguardian directory will be immediately reflected in ggshield.

1. Activate the ggshield virtual environment.
2. Run pip install -e pointing to your local py-gitguardian checkout.

pip install -e path/to/your/py-gitguardian/checkout

To use ggshield, you must authenticate against GitGuardian servers.

Option 1: Automated Login (Recommended) Use the ggshield auth login command to automatically provision a personal access token and configure it on your local workstation.

ggshield auth login

Option 2: Manual Setup Create a personal access token manually and store it in the GITGUARDIAN_API_KEY environment variable.

To run all configured linters for the project at once, use the following command:

make lint