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.

Important notes#

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.

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#

GitHub Check Runs will be created on GitHub pull requests on repositories monitored by GitGuardian This allows the individual developer to be notified about an incident detected by GitGuardian directly through the GitHub interface, and hence enable them to remediate immediately - before the commit is merged to your collaborative branches.

Manage Check Runs#

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.

Customize remediation guidelines#

As a Manager, you can customize the remediation guidelines. These guidelines will be displayed in the GitHub interface.

Customize remediation guidelines

Customize remediation guidelines GitHub interface

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