Skip to main content

Integrate a new GitHub source

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 owner of that GitHub organization.

Note: if you try to install GitGuardian on a GitHub organization for which you are not an owner (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 has not installed the GitHub App. If the repo is owned by a GitHub organization, the owner of the organization must install 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.