Detect secrets in GitHub PRs

Overview

GitHub Check Runs will be triggered on GitHub pull requests on repositories monitored by GitGuardian. Secret scans in the context of GitHub Check Runs will run server-side on the VCS, at the post-receive stage.

GitGuardian secret scans run on each individual commit that makes up the pull request, and not only the final state of the code in the pull request. This deep scanning helps uncover cases where one commit A adds a secret and one commit B removes the same secret within the same pull request.

This allows the individual developer to get notified when an incident is detected by GitGuardian, directly in the GitHub interface. This is particularly useful when a developer opens a pull request to merge an individual branch into a collaborative one. The Check Run will alert the developer before the commits are merged, limiting the incident to their branch and giving them the opportunity of easier remediation. The result is secrets-free collaborative branches such as the ones used for QA, staging, and production environments.

How it looks

The details section for GitGuardian check runs in the GitHub UI presents a table with all findings and their relevant details (secret type, commit sha, filename) and also links to the GitGuardian dashboard if the user wishes to view the incident there and act on it (change status, leave notes, resolve, etc.).

Secrets incidents detected during check runs and raised in the GitGuardian dashboard also link back to the original GitHub pull request. From the incident's details page you can find the link to the pull request under the section "01. Explore the incident".

Please note that only GitHub pull requests created after February 10th, 2022 will be visible.

Behavior and status

The behavior of GitGuardian scans in the context of GitHub Check Runs depends on 2 factors:

1. The branch protection rules you have in place
2. The chosen status in your settings of the GitGuardian conclusion upon detection of secrets ("Failed" or "Neutral")

Let's go over all the possible scenarios.

Case 1 — Your branches require status checks to pass on GitHub

If you are enforcing branch protection rules on GitHub and require status checks to pass before merging:

1. Setting the GitGuardian checks behavior to "Failed" will return a failing status check if a secret is caught. This will block the pull request.

   From the GitHub UI, developers will still have an option to skip failing checks and optionally precise if the secrets detected are false positives – this allows them to move forward in their workflows without hindering their productivity. If they skip and tag the secrets as false positives, this information will be forwarded to the GitGuardian dashboard.

2. Setting the GitGuardian checks behavior to "Neutral" will force the Check Run to complete with a neutral conclusion even if a secret is caught. This setting will not block the pull request.

Case 2 — Your branches DO NOT require status checks to pass on GitHub

If you are NOT enforcing branch protection rules on GitHub and DO NOT require status checks to pass before merging, the chosen behavior of the GitGuardian checks ("Failed" or "Neutral") will not have any impact on the merging of the pull request.

⚠️ We suggest setting the GitGuardian check behavior to "Failed" in this case to make sure scans where secrets are detected do not go unnoticed.

Post a comment in the pull request timeline

To extend the visibility of checkrun results and ensure your developers do not miss it, GitGuardian posts a comment when a secret is detected.

Such behavior can be enabled or disabled in your settings by Managers:

Customize remediation guidelines

As a Manager, you can customize the remediation guidelines. These guidelines will be displayed in the GitHub interface both in the check run body and in the comment posted on the pull request timeline.

Activate or deactivate

As a Manager, you can decide to turn the GitHub Check Runs On or Off for the monitored repositories directly in your GitHub settings page or GitHub Enterprise settings page.

Note: If you have integrated both GitHub.com and GitHub Enterprise, you will have two different check runs settings.