ggshield "Invalid API key" (GITGUARDIAN_API_KEY) in CI

By Daniel Zoghalchali·Latchkey

ggshield reads GITGUARDIAN_API_KEY to call the GitGuardian API. If the variable is unset, empty, or truncated, ggshield reports an invalid key and cannot scan.

What this error means

ggshield exits before scanning with "Error: Invalid API key" or "Auth: Invalid API key", often because the secret was not exposed to the step.

Error: Invalid API key.
Please check your instance and API key. To set your key, run:
  ggshield auth login   or   export GITGUARDIAN_API_KEY=...

Common causes

The API key secret is not exposed to the step

The workflow did not map the secret into GITGUARDIAN_API_KEY, so ggshield sees an empty value and rejects it.

A malformed or truncated key

A copy-paste error, trailing whitespace, or a wrong instance URL makes the key invalid even when present.

How to fix it

Inject the key from a CI secret

1. Store the GitGuardian API key as a repository or organization secret.
2. Map it into the GITGUARDIAN_API_KEY env for the ggshield step.
3. Re-run so ggshield authenticates.

- run: ggshield secret scan ci
  env:
    GITGUARDIAN_API_KEY: ${{ secrets.GITGUARDIAN_API_KEY }}

Verify the key and instance

Confirm the key value and the GitGuardian instance URL are correct, with no stray whitespace.

ggshield api-status

How to prevent it

• Keep the API key in CI secrets, never hardcoded.
• Map it explicitly into GITGUARDIAN_API_KEY for the step.
• Validate the key with ggshield api-status before scanning.

Frequently asked questions

Related guides

References

• GitHub Actions documentation