GitHub Actions

Prelude

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.

Preview

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

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.

Installation

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@v1.34.0
        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
        with:
          fetch-depth: 0 # fetch all history so multiple commits can be scanned
      - name: GitGuardian iac scan
        uses: GitGuardian/ggshield/actions/iac@v1.34.0
        with:
          args: ./terraform/ --minimum-severity CRITICAL # pass arguments to the action. If missing, will scan the current directory
        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 }}