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.

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

Setup your GitHub integration

Scan for incidents with the GitGuardian GitHub app

info

The GitGuardian GitHub app has only read access to your code.
Optionally, it is possible to grant GitGuardian write access to benefit from specific business features. See dedicated section for more detail.
You will need Owner or Manager rights in GitGuardian to set up an integration or customize your settings.

You can install GitGuardian on:

• your personal GitHub account to monitor your personal repositories,
• a GitHub organization that you own.

1. Navigate to Settings > Integrations > Sources.
2. Click on Install 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)
   
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.
     
7. Follow the prompts and your chosen GitHub repositories will be added to your workspace.
   

info

If you attempt to install GitGuardian on a GitHub organization where you are only a member, and not the owner, GitHub will prompt you to use a "Request installation" flow.
We highly recommend inviting the owner to your GitGuardian workspace to perform the integration, thus attaching the GitHub organization to your workspace.

Grant code write permissions with the GitGuardian:write GitHub app

info

Some business features require write permissions to your repositories in order to open pull requests.
Currently, this concerns the Honeytoken Deployment jobs feature.
Granting write permissions to GitGuardian is done through the installation of a second GitHub app “GitGuardian:write”.

1. Navigate to GitHub settings section where your integration is already configured with the main app.
2. Click on Manage sources > Configure write permissions.
3. Choose on which organization you want to install the GitHub app, then choose your preferred installation mode (all organization or selected repositories). Note that you must install it on repositories where the main GitHub is already installed if you want to see them in the GitGuardian dashboard.

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.

info

By default, the GitGuardian GitHub app has only read access to your code.

Optionally, it is possible to grant GitGuardian write access to benefit from specific business features (more detail in this dedicated section).
You will need Owner or Manager rights in GitGuardian to set up an integration or customize your settings.

1. Navigate to Settings > Integrations > Sources.
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.
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.

caution

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.

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.

Grant GitGuardian code write permissions

info

Some business features require write permissions to your repositories in order to open pull requests.
Currently, this concerns the Honeytoken Deployment jobs feature.

To allow GitGuardian to open pull requests on the repositories of your instance, go to the app settings page in GitHub, in the tab "Permissions & events". Under the "Repository permissions" section, change permissions on Contents to "Read and write":

This change then needs to be propagated to the organizations where this app is installed, by accepting the permission update request:

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 newly created Github repository added to your perimeter.

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

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.