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.).

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

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.

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.

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

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

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

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 workspace Managers:

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.

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:

• 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.
  

Forked repositories

In a fork process, there are two repositories:

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

GitGuardian does not create check runs on monitored forked 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.

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.

info

This feature is currently in beta testing. If you're interested in trying it out, kindly get in touch with your account manager.

Using GitHub labels for GitHub Enterprise repositories

On GitHub Enterprise, 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.

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

Overriding check runs presence

GitGuardian global configuration	GitHub Enterprise repository labels
	gitguardian:check-runs-enabled	gitguardian:check-runs-disabled	No labels	Both labels present
Check runs are activated ✅	check runs will be present ✅	check runs won’t be present 🚫	check runs will 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 🚫	check runs will be present ✅

Overriding check runs conclusion

GitGuardian global configuration	GitHub Enterprise repository labels
	gitguardian:check-runs-secrets-conclusion-neutral	gitguardian:check-runs-secrets-conclusion-failed	No labels	Both labels present
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 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)	check runs conclusion if secrets will be Neutral ⬛

Overriding check runs skip actions presence when the conclusion is Failed

GitGuardian global configuration	GitHub Enterprise repository labels
	gitguardian:check-runs-actions-enabled	gitguardian:check-runs-actions-disabled	No labels	Both labels present
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 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 🚫	skip action buttons will be present ✅

Was this page helpful?