Skip to main content

GitHub Actions


GitGuardian CI/CD integration with GitHub comes in the form of GitHub Actions and is performed through our CLI application: ggshield. ggshield is a wrapper around the GitGuardian API for secrets detection, an API key is required for authentication.

ggshield actions are found in the actions directory of the GitHub repository.

Note: If you want to ensure full coverage of your GitHub repositories as well as full git history scans and reporting, you may be interested in using GitGuardian's GitHub integration.


GitHub Actions output

If there are secret leaks or other security issues in your commit, your workflow will be marked as failed.

GitHub Actions checks list

Be sure to add GitGuardian scan to your required status checks in your repository settings to stop pull requests with security issues from being merged.


Service accounts are recommended to run this integration.

Please note that service accounts are only available for workspaces under our Business plan, and their administration is restricted to Managers. If your workspace is under the Free plan, you can still use a personal access token to run this integration.

  1. Create a service account from the API section of your GitGuardian workspace (or a personal access token if you are on the Free plan).
  2. Add this API key to the GITGUARDIAN_API_KEY environment variable in your project settings. You can set the GITGUARDIAN_API_KEY value in the "Secrets" page of your repository's settings.
  3. Add a new job to your GitHub workflow using the GitGuardian/ggshield-action action .github/workflows/gitguardian.

Template for secret scanning#

name: GitGuardian scan
on: [push, pull_request]
jobs:  scanning:    name: GitGuardian scan    runs-on: ubuntu-latest    steps:      - name: Checkout        uses: actions/checkout@v3        with:          fetch-depth: 0 # fetch all history so multiple commits can be scanned      - name: GitGuardian scan        uses: GitGuardian/ggshield/actions/secret@main        env:          GITHUB_PUSH_BEFORE_SHA: ${{ github.event.before }}          GITHUB_PUSH_BASE_SHA: ${{ github.event.base }}          GITHUB_PULL_BASE_SHA: ${{ github.event.pull_request.base.sha }}          GITHUB_DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}          GITGUARDIAN_API_KEY: ${{ secrets.GITGUARDIAN_API_KEY }}

Template for IaC scanning#

name: GitGuardian iac scan
on: [push, pull_request]
jobs:  scanning:    name: GitGuardian iac scan    runs-on: ubuntu-latest    steps:      - name: Checkout        uses: actions/checkout@v3      - name: GitGuardian iac scan        uses: GitGuardian/ggshield/actions/iac@main        with:          args: ./terraform/ --minimum-severity CRITICAL # pass arguments to the action. If missing, will scan the current directory        env:          GITGUARDIAN_API_KEY: ${{ secrets.GITGUARDIAN_API_KEY }}