Skip to content
You're viewing an older version of this GitHub Action. Do you want to see the latest version instead?
shield

GitHub Action

GitGuardian Shield Action

v1.21.0

GitGuardian Shield Action

shield

GitGuardian Shield Action

Scan commits for secrets and other issues

Installation

Copy and paste the following snippet into your .yml file.

              

- name: GitGuardian Shield Action

uses: GitGuardian/[email protected]

Learn more about this action in GitGuardian/ggshield-action

Choose a version


GitGuardian Shield GitHub Action

GitHub Marketplace Docker Image Version (latest semver) License GitHub stars

Find exposed credentials in your commits using GitGuardian shield.

The GitGuardian shield (ggshield) is a CLI application that runs in your local environment or in a CI environment to help you detect more than 200 types of secrets, as well as other potential security vulnerabilities or policy breaks.

GitGuardian shield uses our public API through py-gitguardian to scan your files and detect potential secrets or issues in your code. The /v1/scan endpoint of the public API is stateless. We will not store any files you are sending or any secrets we have detected.

Requirements

  • Have an account on GitGuardian. Sign up now if you haven't before!
  • Create an API key on the API Section of your dashboard.

Project secrets

  • GITGUARDIAN_API_KEY [Required]: Necessary to authenticate to GitGuardian's API. You can set the GITGUARDIAN_API_KEY value in the "Secrets" page of your repository's settings. You can create your API Key here.

Usage

Add a new job to your GitHub workflow using the GitGuardian/ggshield-action action.

name: GitGuardian scan

on: [push, pull_request]

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

Do not forget to add your GitGuardian API Key to the GITGUARDIAN_API_KEY secret in your project settings.

Adding extra options to the action

The action accepts the same extra options as the ggshield secret scan ci command. Here is the command reference.

Example:

name: GitGuardian scan

on: [push, pull_request]

jobs:
  scanning:
    name: GitGuardian scan
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # fetch all history so multiple commits can be scanned
      - name: GitGuardian scan
        uses: GitGuardian/[email protected]
        with:
          args: -v --ignore-known-secrets
        env:
          GITHUB_PUSH_BEFORE_SHA: ${{ github.event.before }}
          GITHUB_PUSH_BASE_SHA: ${{ github.event.base }}
          GITHUB_DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
          GITGUARDIAN_API_KEY: ${{ secrets.GITGUARDIAN_API_KEY }}

Examples of GitGuardian scanning

Scan output example

This a sample scan result from GitGuardian shield.

If the secret detected has been revoked and you do not wish to rewrite git history, you can use a value of the policy break (for example: the value of |_password_|) or the ignore SHA displayed in your .gitguardian.yaml under matches-ignore.

An example configuration file is available here.

Status example

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.

License

GitGuardian shield is MIT licensed.