Automate GitHub App installations across your enterprise

Installing the GitGuardian GitHub App on hundreds of organizations one by one from the dashboard does not scale. With GitHub Enterprise Cloud, you register an enterprise-owned GitHub App with GitGuardian once, then use it to install the GitGuardian app on any organization of your enterprise from a scheduled script. GitGuardian links each installation to your workspace automatically. The scripts for each step live in the ghes-installer folder of the GitGuardian tools repository.

info

This procedure requires GitHub Enterprise Cloud: the GitHub enterprise installation API is available to enterprise-owned GitHub Apps only. It works with GitGuardian SaaS and with self-hosted instances. For the standard setup, see Integrate GitHub.

How it works

When you install the GitGuardian app from the dashboard, GitHub redirects you back to GitGuardian at the end of the installation. This redirect is how GitGuardian knows which workspace the installation belongs to. An installation performed by a script has no redirect, so GitGuardian needs another proof.

The installer app provides it:

1. You create a GitHub App owned by your enterprise, with permission to install apps on your organizations.
2. You register this installer app with GitGuardian through the API, once. You prove that you control it with a JSON Web Token (JWT) signed by its private key.
3. Your automation authenticates as the installer app and asks GitHub to install the GitGuardian app on an organization.
4. GitHub notifies GitGuardian of the new installation and identifies the installer app as the actor. GitGuardian recognizes the registered installer app and links the installation to your workspace. Repositories are then synchronized and monitored like any installation made from the dashboard.

GitHub only lets an installer app install apps on organizations of the enterprise it is installed on, and authenticates the actor of each installation event, so no organization outside your enterprise can be linked to your workspace this way.

Prerequisites

• A GitHub Enterprise Cloud account, with enterprise owner rights to create GitHub Apps.
• The Owner or Manager role on your GitGuardian workspace.
• A GitGuardian API key with the sources:write scope, needed once for the registration: a personal access token of a workspace Owner or Manager, or a service account with the Manager role.
• Python 3.10 or later to run the scripts, with the dependencies listed in the ghes-installer requirements.

Create the installer app in your enterprise

1. In GitHub, open your enterprise settings. In the left sidebar, click GitHub Apps, then New GitHub App.
2. Name the app, for example gitguardian-installer, and set any homepage URL. Under Webhook, uncheck Active: the installer app does not need to receive events.
3. Under Enterprise permissions, set Enterprise organization installations to Read and write. No other permission is needed.
4. Register the app. On its settings page, note the Client ID. Under Private keys, click Generate a private key and store the downloaded .pem file in your secrets manager.
5. Install the app on your enterprise: open Install App in the left sidebar and install it on your enterprise account, not on an organization. GitGuardian refuses to register an installer app that is not installed on its enterprise.

attention

The Enterprise organization installations write permission lets the installer app install any enterprise-owned app on any of your organizations. Protect its private key like an enterprise administrator credential. The About the private key section of the tools README explains why GitHub requires this key and how to keep it out of your scheduler.

Register the installer app with GitGuardian

Run gg_register_installer.py once, from any machine that can read the .pem file. It takes the installer app Client ID, the private key, your GitGuardian API URL, and your GitGuardian API key as environment variables, described in the ghes-installer README. The registration is permanent, so you can revoke the API key afterwards.

The script signs a short-lived JWT with the private key and sends it to GitGuardian, which presents it to GitHub to validate the signature and retrieve the identity of the app. Your private key never leaves your systems. The registration is recorded in your audit log.

Without the script, the registration is a single POST /v1/github/installer-app-rules call with the signed JWT in the app_jwt field. The README details the GitHub calls GitGuardian performs with it.

Response	Cause	What to do
403 GitHub rejected the installer app JWT	The JWT is expired, signed with another key, or its issuer is not the app's Client ID.	Check the Client ID and the private key, then run the script again.
403 The installer app '<slug>' has no installation: install it on your enterprise first	The installer app is not installed on your enterprise.	Install it, then retry.
409 This installer app is already registered.	The installer app is registered on this workspace or on another one.	Remove the existing registration, or create a dedicated installer app for this workspace.
403 with another message	The API key lacks the sources:write scope, or its owner is not a workspace Owner or Manager.	Use an API key that meets the prerequisites.

Install the GitGuardian app on your organizations

Run gg_enterprise_installer.py on a schedule. It installs the GitGuardian app, with all repositories selected, on every organization of your enterprise or on the ones you name, and skips organizations that already have it. A daily run covers organizations created since the previous run.

Run it as a scheduled GitHub Actions workflow in a private repository, with the private key in Actions secrets, as in the example workflow. Besides the installer app Client ID, the private key, and your enterprise slug, the script needs the Client ID of the app to install:

• On GitGuardian SaaS, the GitGuardian GitHub App has the Client ID Iv1.ec3c001966b4cc5a. You can verify it at https://api.github.com/apps/gitguardian.
• On a self-hosted instance, use the Client ID of the GitHub App you created for your instance.

Without the script, use the GitHub enterprise installation API with an installation access token of the installer app.

Shortly after each installation, GitGuardian receives the installation event, links it to your workspace, and the organization appears in your GitHub settings. Repositories are synchronized, and your automatic historical scan and automatic repository monitoring settings apply as for any new repository. The link is recorded in your audit log, with the installer app that performed it.

GitGuardian:write app

On GitGuardian SaaS, if you use features that need write access to your repositories, such as honeytoken deployment jobs, run the install script a second time with the Client ID of the GitGuardian:write app, Iv1.c50431fd10ab9f00, on organizations where the main app is installed.

Manage registered installer apps

The installer apps registered on your workspace are available through the GitGuardian API: GET /v1/github/installer-app-rules lists them, and DELETE /v1/github/installer-app-rules/{id} removes one.

• Removing a registration stops the automatic linking of future installations. Installations already linked stay in your workspace.
• You can rotate the private key of the installer app, or rename it, without registering it again. GitGuardian matches installations on the permanent identity of the app, not on its key or name.
• An installer app can be registered on a single GitGuardian workspace. To onboard organizations into several workspaces, create one installer app per workspace.

Troubleshooting

The organization is installed on GitHub but does not appear in GitGuardian.

• The installation was not performed by the installer app. Installations made by a person from the GitHub interface, or by another app, are not linked automatically. Install from the dashboard instead, as described in Integrate GitHub.
• The installer app is not registered on your workspace, or its registration was removed. List the registrations to check, register the app again if needed, then reinstall the organization.
• The organization does not belong to the enterprise that owns the installer app. GitHub rejects such installations before they reach GitGuardian.

The troubleshooting table of the tools README covers the messages printed by the scripts.