https://github.com/GitGuardian/ggshield-action
GitGuardian Shield GitHub Action - Find exposed credentials in your commits
https://github.com/GitGuardian/ggshield-action
ci devops devsecops gitguardian github-actions secrets-detection security-tools
Last synced: 2 days ago
JSON representation
GitGuardian Shield GitHub Action - Find exposed credentials in your commits
- Host: GitHub
- URL: https://github.com/GitGuardian/ggshield-action
- Owner: GitGuardian
- License: mit
- Created: 2020-06-15T09:46:35.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2025-03-27T15:59:01.000Z (18 days ago)
- Last Synced: 2025-04-07T17:04:41.749Z (7 days ago)
- Topics: ci, devops, devsecops, gitguardian, github-actions, secrets-detection, security-tools
- Homepage:
- Size: 205 KB
- Stars: 338
- Watchers: 19
- Forks: 23
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
- awesome - GitGuardian/ggshield-action - GitGuardian Shield GitHub Action - Find exposed credentials in your commits (Others)
README
---
# [GitGuardian Shield](https://github.com/GitGuardian/ggshield) GitHub Action
[](https://github.com/marketplace/actions/gitguardian-shield-action)
[](https://hub.docker.com/r/gitguardian/ggshield)
[](LICENSE)
Find exposed credentials in your commits using [**GitGuardian shield**](https://github.com/GitGuardian/ggshield).
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 400 types of secrets, as well as other potential security vulnerabilities or policy breaks.
**GitGuardian shield** uses our [public API](https://api.gitguardian.com/doc) through [py-gitguardian](https://github.com/GitGuardian/py-gitguardian) to scan your files and detect potential secrets or issues in your code. **The `/v1/scan` endpoint of the [public API](https://api.gitguardian.com/doc) is stateless. We will not store any files you are sending or any secrets we have detected**.
## Requirements
- A GitGuardian account. [**Sign up now**](https://dashboard.gitguardian.com/api/v1/auth/user/github_login/authorize?utm_source=github&utm_medium=gg_shield&utm_campaign=shield1) if you haven't before!
- A GitGuardian API Key. You can create your API Key [**here**](https://dashboard.gitguardian.com/api/v1/auth/user/github_login/authorize?utm_source=github&utm_medium=gg_shield&utm_campaign=shield1). The only required scope is `scan`.
## Usage
Add a new job to your GitHub workflow using the `GitGuardian/ggshield-action` action.
```yaml
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/ggshield-action@v1
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 }}
```
Add your [GitGuardian API Key](https://dashboard.gitguardian.com/api/v1/auth/user/github_login/authorize?utm_source=github&utm_medium=gg_shield&utm_campaign=shield1) 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](https://docs.gitguardian.com/ggshield-docs/reference/secret/scan/ci).
Example:
```yaml
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/ggshield-action@v1
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
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](https://github.com/GitGuardian/ggshield/blob/main/.gitguardian.example.yml).
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.