Automatiser les installations de l'application GitHub dans toute votre entreprise

Installer l'application GitHub GitGuardian sur des centaines d'organisations une par une depuis le dashboard ne passe pas à l'échelle. Avec GitHub Enterprise Cloud, vous enregistrez une fois auprès de GitGuardian une application GitHub détenue par l'entreprise, puis vous l'utilisez pour installer l'application GitGuardian sur n'importe quelle organisation de votre entreprise depuis un script planifié. GitGuardian lie automatiquement chaque installation à votre workspace. Les scripts de chaque étape se trouvent dans le dossier ghes-installer du dépôt des outils GitGuardian.

info

Cette procédure nécessite GitHub Enterprise Cloud : l'API d'installation d'entreprise GitHub n'est disponible que pour les applications GitHub détenues par l'entreprise. Elle fonctionne avec GitGuardian SaaS et avec les instances self-hosted. Pour la configuration standard, consultez Intégrer GitHub.

Fonctionnement

Lorsque vous installez l'application GitGuardian depuis le dashboard, GitHub vous redirige vers GitGuardian à la fin de l'installation. Cette redirection est la façon dont GitGuardian sait à quel workspace appartient l'installation. Une installation effectuée par un script n'a pas de redirection, donc GitGuardian a besoin d'une autre preuve.

L'application d'installation la fournit :

1. Vous créez une application GitHub détenue par votre entreprise, avec l'autorisation d'installer des applications sur vos organisations.
2. Vous enregistrez cette application d'installation auprès de GitGuardian via l'API, une seule fois. Vous prouvez que vous la contrôlez avec un JSON Web Token (JWT) signé par sa clé privée.
3. Votre automatisation s'authentifie en tant qu'application d'installation et demande à GitHub d'installer l'application GitGuardian sur une organisation.
4. GitHub notifie GitGuardian de la nouvelle installation et identifie l'application d'installation comme l'acteur. GitGuardian reconnaît l'application d'installation enregistrée et lie l'installation à votre workspace. Les dépôts sont ensuite synchronisés et surveillés comme toute installation effectuée depuis le dashboard.

GitHub ne permet à une application d'installation d'installer des applications que sur les organisations de l'entreprise sur laquelle elle est installée, et authentifie l'acteur de chaque événement d'installation, de sorte qu'aucune organisation en dehors de votre entreprise ne peut être liée à votre workspace de cette façon.

Prérequis

• Un compte GitHub Enterprise Cloud, avec les droits de propriétaire d'entreprise pour créer des applications GitHub.
• Le rôle Owner ou Manager sur votre workspace GitGuardian.
• Une clé API GitGuardian avec le scope sources:write, nécessaire une seule fois pour l'enregistrement : un personal access token d'un Owner ou Manager du workspace, ou un compte de service avec le rôle Manager.
• Python 3.10 ou version ultérieure pour exécuter les scripts, avec les dépendances listées dans les prérequis ghes-installer.

Créer l'application d'installation dans votre entreprise

1. Dans GitHub, ouvrez les paramètres de votre entreprise. Dans la barre latérale de gauche, cliquez sur GitHub Apps, puis New GitHub App.
2. Nommez l'application, par exemple gitguardian-installer, et définissez une URL de page d'accueil quelconque. Sous Webhook, décochez Active : l'application d'installation n'a pas besoin de recevoir d'événements.
3. Sous Enterprise permissions, réglez Enterprise organization installations sur Read and write. Aucune autre autorisation n'est nécessaire.
4. Enregistrez l'application. Sur sa page de paramètres, notez le Client ID. Sous Private keys, cliquez sur Generate a private key et stockez le fichier .pem téléchargé dans votre gestionnaire de secrets.
5. Installez l'application sur votre entreprise : ouvrez Install App dans la barre latérale de gauche et installez-la sur votre compte d'entreprise, pas sur une organisation. GitGuardian refuse d'enregistrer une application d'installation qui n'est pas installée sur son entreprise.

attention

L'autorisation d'écriture Enterprise organization installations permet à l'application d'installation d'installer n'importe quelle application détenue par l'entreprise sur n'importe laquelle de vos organisations. Protégez sa clé privée comme un identifiant d'administrateur d'entreprise. La section About the private key du README des outils explique pourquoi GitHub exige cette clé et comment la garder hors de votre planificateur.

Enregistrer l'application d'installation auprès de GitGuardian

Exécutez gg_register_installer.py une seule fois, depuis n'importe quelle machine capable de lire le fichier .pem. Il prend en variables d'environnement le Client ID de l'application d'installation, la clé privée, l'URL de votre API GitGuardian et votre clé API GitGuardian, décrites dans le README ghes-installer. L'enregistrement est permanent, vous pouvez donc révoquer la clé API par la suite.

Le script signe un JWT de courte durée avec la clé privée et l'envoie à GitGuardian, qui le présente à GitHub pour valider la signature et récupérer l'identité de l'application. Votre clé privée ne quitte jamais vos systèmes. L'enregistrement est consigné dans votre audit log.

Sans le script, l'enregistrement est un unique appel POST /v1/github/installer-app-rules avec le JWT signé dans le champ app_jwt. Le README détaille les appels GitHub que GitGuardian effectue avec.

Réponse	Cause	Que faire
403 GitHub rejected the installer app JWT	Le JWT est expiré, signé avec une autre clé, ou son émetteur n'est pas le Client ID de l'application.	Vérifiez le Client ID et la clé privée, puis réexécutez le script.
403 The installer app '<slug>' has no installation: install it on your enterprise first	L'application d'installation n'est pas installée sur votre entreprise.	Installez-la, puis réessayez.
409 This installer app is already registered.	L'application d'installation est enregistrée sur ce workspace ou sur un autre.	Supprimez l'enregistrement existant, ou créez une application d'installation dédiée pour ce workspace.
403 avec un autre message	La clé API n'a pas le scope sources:write, ou son propriétaire n'est pas un Owner ou Manager du workspace.	Utilisez une clé API qui satisfait les prérequis.

Installer l'application GitGuardian sur vos organisations

Exécutez gg_enterprise_installer.py de façon planifiée. Il installe l'application GitGuardian, avec tous les dépôts sélectionnés, sur chaque organisation de votre entreprise ou sur celles que vous nommez, et ignore les organisations qui l'ont déjà. Une exécution quotidienne couvre les organisations créées depuis l'exécution précédente.

Exécutez-le en tant que workflow GitHub Actions planifié dans un dépôt privé, avec la clé privée dans les secrets Actions, comme dans l'exemple de workflow. Outre le Client ID de l'application d'installation, la clé privée et le slug de votre entreprise, le script a besoin du Client ID de l'application à installer :

• Sur GitGuardian SaaS, l'application GitHub GitGuardian a le Client ID Iv1.ec3c001966b4cc5a. Vous pouvez le vérifier à l'adresse https://api.github.com/apps/gitguardian.
• Sur une instance self-hosted, utilisez le Client ID de l'application GitHub que vous avez créée pour votre instance.

Sans le script, utilisez l'API d'installation d'entreprise GitHub avec un token d'accès d'installation de l'application d'installation.

Peu après chaque installation, GitGuardian reçoit l'événement d'installation, le lie à votre workspace, et l'organisation apparaît dans vos paramètres GitHub. Les dépôts sont synchronisés, et vos paramètres de scan historique automatique et de surveillance automatique des dépôts s'appliquent comme pour tout nouveau dépôt. Le lien est consigné dans votre audit log, avec l'application d'installation qui l'a effectué.

Application GitGuardian:write

Sur GitGuardian SaaS, si vous utilisez des fonctionnalités qui nécessitent un accès en écriture à vos dépôts, comme les tâches de déploiement de honeytokens, exécutez le script d'installation une seconde fois avec le Client ID de l'application GitGuardian:write, Iv1.c50431fd10ab9f00, sur les organisations où l'application principale est installée.

Gérer les applications d'installation enregistrées

Les applications d'installation enregistrées sur votre workspace sont accessibles via l'API GitGuardian : GET /v1/github/installer-app-rules les liste, et DELETE /v1/github/installer-app-rules/{id} en supprime une.

• Supprimer un enregistrement arrête la liaison automatique des installations futures. Les installations déjà liées restent dans votre workspace.
• Vous pouvez effectuer la rotation de la clé privée de l'application d'installation, ou la renommer, sans l'enregistrer à nouveau. GitGuardian fait correspondre les installations sur l'identité permanente de l'application, pas sur sa clé ou son nom.
• Une application d'installation ne peut être enregistrée que sur un seul workspace GitGuardian. Pour intégrer des organisations dans plusieurs workspaces, créez une application d'installation par workspace.

Dépannage

L'organisation est installée sur GitHub mais n'apparaît pas dans GitGuardian.

• L'installation n'a pas été effectuée par l'application d'installation. Les installations effectuées par une personne depuis l'interface GitHub, ou par une autre application, ne sont pas liées automatiquement. Installez plutôt depuis le dashboard, comme décrit dans Intégrer GitHub.
• L'application d'installation n'est pas enregistrée sur votre workspace, ou son enregistrement a été supprimé. Listez les enregistrements pour vérifier, enregistrez à nouveau l'application si nécessaire, puis réinstallez l'organisation.
• L'organisation n'appartient pas à l'entreprise qui détient l'application d'installation. GitHub rejette de telles installations avant qu'elles n'atteignent GitGuardian.

Le tableau de dépannage du README des outils couvre les messages affichés par les scripts.