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

In the GitHub UI, a GitGuardian check run presents a table with all findings and their relevant details:

the id of the corresponding secret incident on GitGuardian
the status of the corresponding secret incident on GitGuardian
Keep in mind that if secret incidents are closed on the GitGuardian dashboard, they will no longer be raised by GitHub checkruns.
the secret type
the commit sha
the 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.).

Checkruns conclusion in GitHub UI

Checkruns details in GitHub UI

Secrets incidents detected during check runs and raised in the GitGuardian dashboard also link back to the original GitHub pull request.

Incidents details with pull request links

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

Manage your GitHub check runs

Activate or deactivate the GitGuardian check runs

As a workspace 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.

GitHub Check Runs

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

Choose the conclusion of check runs when secrets are detected

You also have the option to determine the conclusion of the GitHub check runs when secrets are detected. You can choose between two options:

either Failed
This conclusion will prevent your developers from merging the pull request if you have protected branches in place, ensuring that your secrets do not make it to production.
To prevent full blockages, GitGuardian provides skip action buttons for developers to bypass blocking check runs. More details can be found below.
or Neutral
This conclusion does not block pull requests.
Developers will be notified of secret presence, especially if you enable GitGuardian to post a comment to enhance visibility of detected secrets in the pull request. Refer to the section below for more information.

Checkruns status setting

Enable or disable skip actions

When the conclusion of the checkruns if secrets are detected is "Failed", pull requests are unable to be merged. However, since the detection of secrets is probabilistic, GitGuardian offers skip action buttons to prevent complete hindrance to developers.
These skip actions mirror the ignore reasons available on the dashboard, with the understanding that skipping a checkrun containing a secret is akin to ignoring the associated incident. The available skip actions include:

Skip: false positive
Skip: test credential
Skip: low risk

GitHub checkruns skip buttons

When a skip action is taken, the corresponding secret incident is tagged to inform dashboard users that a developer intentionally skipped the checkrun after encountering the secret alert. The tags for skipped incidents include:

Skipped in check run as false positive
Skipped in check run as test credential
Skipped in check run as low risk

Skip actions tags

As a workspace manager, you have the option to disable the ability to skip check runs entirely in your settings.

Skip actions setting

Customize remediation guidelines

As a workspace 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.

Customize remediation guidelines

Dependencies

GitHub branch protection rule "Require status checks to pass before merging"

When you set up the Require status checks to pass before merging branch protection rule on GitHub and require GitGuardian security checks to pass, there are important things you should know:

Branch protection rule

Your repository must be actively monitored by GitGuardian.
If it is not, GitHub will be waiting for a check run from GitGuardian that will never be provided, causing a perpetual pending check run.
If the check run conclusion is Failed, GitHub will display a specific warning.
The Neutral conclusion is considered the same as a successful check run.

Working with forked repositories

In a fork process, there are two repositories:

Forked repository: Your personal copy of the upstream repo, marked as fork = true on GitHub.
Upstream repository: The original repository.

Forked repositories

By default, GitGuardian does not generate check runs on monitored forked repositories to prevent rate limiting errors.

This issue arises because many forked repositories automatically generate numerous pull requests to stay up-to-date with their upstream repositories, which often have high activity levels. These automated pull requests are resource-intensive and can lead to rate limiting errors during GitGuardian check runs.

However, managers of workspaces under the Business plan have the option to enable GitGuardian check runs on their monitored forked repositories.

Check runs on monitored forked repositories setting

Upstream repositories

Check runs are created on monitored upstream repositories.
However, when a pull request originating from a forked repository contains secrets, GitGuardian cannot propose the usual "Skip" actions buttons. In this scenario, GitGuardian provides a simple Skip button to avoid blocking the developer.

Forked repositories PR

Going further: customizing check runs on a per-repository basis

GitGuardian offers you the ability to customize the behavior of GitGuardian check runs at the repository level by utilizing GitHub's native features to override the configuration set on the GitGuardian dashboard.

Using GitHub custom properties

GitHub custom properties allow you to customize check runs both at the organisation level and the repository level:

whether the checkrun is present or not
specifying the conclusion as either Failed or Neutral when secrets are detected.
whether the skip actions are available or not.

custom properties to override check run settings

It is crucial to use the exact names of the custom properties given below to ensure the feature functions properly.

Overriding check runs presence

GitGuardian global configuration	Custom property `gitguardian-check-runs-enabled`
	`true`	`false`	`null`
Check runs are activated ✅	check runs will be present ✅	check runs won’t be present 🚫	check runs will be present ✅
Check runs are deactivated 🚫	check runs will be present ✅	check runs won’t be present 🚫	check runs won’t be present 🚫

Overriding check runs conclusion

GitGuardian global configuration	Custom property `gitguardian-check-runs-secrets-conclusion`
	`neutral`	`failed`	`null` or other
Check runs conclusion if secrets is Neutral ⬛	check runs conclusion if secrets will be Neutral ⬛	check runs conclusion if secrets will be Failed ❌ (blocking the PR)	check runs conclusion if secrets will be Neutral ⬛
Check runs conclusion if secrets is Failure ❌	check runs conclusion if secrets will be Neutral ⬛	check runs conclusion if secret will be Failed ❌ (blocking the PR)	check runs conclusion if secret will be Failed ❌ (blocking the PR)

Overriding check runs skip actions presence when the conclusion is Failed

GitGuardian global configuration	Custom property `gitguardian-check-runs-actions-enabled`
	`true`	`false`	`null`
Skip action buttons are enabled ✅	skip action buttons will be present ✅	skip action buttons won’t be present 🚫	skip action buttons will be present ✅
Skip action buttons are disabled 🚫	skip action buttons will be present ✅	skip action buttons won’t be present 🚫	skip action buttons won’t be present 🚫

Using GitHub labels for GitHub Enterprise Server < 3.13

info

Custom properties are available starting from GitHub Enterprise Server version 3.13.
If you are using a GitHub Enterprise Server version earlier than 3.13, you will need to use GitHub labels to customize your check runs.

Please get in touch with your account manager to have this feature activated.

On GitHub Enterprise Server < 3.13, GitHub labels allow you to customize check runs at the repository level:

whether the check run is present or not.
specifying the conclusion as either Failed or Neutral when secrets are detected.
whether the skip actions are available or not.

Repo label to override check run settings

You are free to customize the label's description and color, but it is essential that the label name remains exact.