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.
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.
The behavior of GitGuardian scans in the context of GitHub Check Runs depends on 2 factors:
- The branch protection rules you have in place
- 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.
If you are enforcing branch protection rules on GitHub and require status checks to pass before merging:
Setting the GitGuardian checks behavior to "Failed" will return a
failingstatus 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.
- Setting the GitGuardian checks behavior to "Neutral" will force the Check Run to complete with a
neutralconclusion even if a secret is caught. This setting will not block the pull request.
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.
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:
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.
Note: If you have integrated both GitHub.com and GitHub Enterprise, you will have two different check runs settings.