Skip to main content

GitHub

GitGuardian integrates natively with GitHub via a GitHub app that you can install on your personal GitHub repositories and on the repositories of your GitHub organizations.

Note: the GitGuardian GitHub app only has read access to your code. You will need Owner or Manager rights in GitGuardian to set up an integration or customize your settings.

You can refer to the GitHub documentation for more information on GitHub apps.

Setup your GitHub integration#

You can install GitGuardian on your personal GitHub account to monitor your personal repositories.

To install GitGuardian on a GitHub organization you need to be an administrator of that GitHub organization.

Note: if you try to install GitGuardian on a GitHub organization for which you are not an administrator (but only a member), the integration will fail, and will therefore not be linked to your GitGuardian workspace.

  1. Navigate to Settings > Workspace > Integrations.

  2. Click on Configure for GitHub.

  3. Click on Install to start the GitHub app installation process (you will then be redirected to GitHub).

  4. Authenticate on GitHub if you are not already logged in.

  5. Choose where to install the GitHub app (either for your personal GitHub account or for the GitHub organization of which you are an admin)

    choose actor

  6. Choose your preferred installation mode: All repositories or Only select repositories.

    All repositories: GitGuardian will be installed on all existing repositories. New repositories will be integrated to GitGuardian automatically.

    Only select repositories: GitGuardian will only be installed on the repositories you select. New repositories will not automatically be integrated with GitGuardian - the installation process will need to be run again in order to integrate new repositories.

    We recommend choosing All repositories since you can then manually deselect these via the GitGuardian dashboard.

    choose repositories

  7. Follow the prompts and your chosen GitHub repositories will be added to your workspace.

GitGuardian monitored perimeter

Setup GitHub for self-hosted GitGuardian#

If you are using a self-hosted GitGuardian instance, you must first create a dedicated GitHub App so that you own the entire data stream. GitGuardian handles it for you programmatically via GitHub manifest. This will ensure that your GitHub App is created with all the appropriate rights.

  1. Navigate to Settings > Workspace > Integrations.
  2. Click on Configure for GitHub.
  3. Click on Install to start the GitHub app creation and installation process.
  4. Choose a name and validate the GitHub App creation. GHE app creation via manifest
  5. Once the GitHub app is created, you can now follow the SAAS installation steps from step 5 above and choose the GitHub organizations to integrate with GitGuardian.

WARNING: the GitHub App belongs to the user who created it. We recommend that you transfer the ownership to an organization in case the user is later deactivated.

Transfer GitHub app

IMPORTANT: GitGuardian cannot monitor repositories whose owner (user or organization) has not installed the GitHub App.

Adding new repositories#

You can add new organizations or repositories by clicking on add another on either the list of integrations page or the GitHub integration page.

You can also re-configure a previously installed personal GitHub account / GitHub organization and change the installation mode to All repositories or Only select repositories.

Automatic historical scan#

By default, GitGuardian performs a historical scan for each new GitHub repository added to your perimeter.

You can deactivate this behavior in your GitHub settings if you are a Manager of the workspace.

Autoscan settings

Customize your monitored perimeter#

Once you have set up your GitHub integration, you can configure which repositories to monitor in the GitHub settings section of your workspace.

If you unselect a repository from your monitored perimeter:

  • GitGuardian will no longer fetch the content of its commits, and therefore alerts won't be raised for this repository.
  • The GitGuardian GitHub app will remain installed on this repository, therefore you can easily turn the monitoring back on.

Check Runs#

How it works#

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

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. From the incident's details page you can find the link to the pull request under the section "01. Explore the incident".

Incidents details with pull request links

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

Checkruns status setting

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.

GitHub checkruns skip buttons

Tagged as false positive tag tooltip

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

Pull request comment

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

Pull request comment setting

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.

Customize remediation guidelines

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.

GitHub Check Runs

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