Automatisation des installations d’applications dans les organisations de votre entreprise

Présentation

Pour automatiser un processus en toute sécurité, vous pouvez créer un GitHub App appartenant à un compte d’entreprise, puis installer l’application dans l’entreprise ou l’organisation où l’automatisation aura lieu.

GitHub Apps fournit des jetons que vous pouvez utiliser pour authentifier les appels d’API à GitHub pour les scripts et les flux de travail. Ces jetons conviennent aux entreprises avec des exigences de sécurité et d’audit spécifiques, car ils sont :

• Temporaire
• Limité à des comptes et autorisations spécifiques
• Associé à l’identité de l’application plutôt qu’à un compte d’utilisateur

Un besoin courant pour les grandes entreprises est de maintenir une automatisation cohérente et up-to-date dans de nombreuses organisations. Pour ce faire, installez une application par programmation. Par exemple, si vous devez configurer toutes les organisations avec certaines stratégies et paramètres, vous pouvez installer un GitHub App pour cette tâche dans chaque organisation.

Ce guide montre les étapes requises pour installer de manière programmatique une application GitHub appartenant à l'entreprise dans une organisation. Une fois l’application installée, vous l’utiliserez pour créer un référentiel.

Vue d’ensemble du processus

Dans ce guide, vous allez utiliser le GitHub CLI pour effectuer les appels d’API requis pour demander des jetons d’accès et installer une application dans une organisation. En réalité, ce processus fait partie d’un script personnalisé adapté aux besoins de votre entreprise.

Vous allez :

1. Créez deux applications appartenant à votre compte d’entreprise.
   • L’un d’eux aura l’autorisation d’installer des applications dans des organisations.
   • L’autre aura l’autorisation d’automatiser un processus dans une organisation (dans ce cas, en créant un référentiel).
2. Authentifiez la première application afin d’obtenir un jeton d’accès délimité au niveau de l’entreprise.
3. Utilisez le jeton délimité au niveau de l’entreprise pour appeler une API qui installe l’application d’automatisation dans une organisation.
4. Authentifiez l’application installée par l’organisation pour obtenir un jeton d’accès limité à l’organisation.
5. Utilisez le jeton délimité au niveau de l’organisation pour appeler une API qui crée un dépôt dans l’organisation.

À chaque étape, vous allez utiliser un jeton qui n’est autorisé qu’à effectuer des actions spécifiques dans un compte spécifique. Du point de vue de la sécurité et de l’audit, cette approche est supérieure à celle d’un jeton unique avec l’autorisation d’effectuer des actions au sein de votre entreprise et de vos organisations.

Prerequisites

Pour suivre ce guide sur votre propre appareil, vous devez :

• Être propriétaire d’entreprise.
• Être propriétaire d’une organisation appartenant à l’entreprise dans laquelle vous effectuerez l’automatisation.
• Assurez-vous que GitHub CLI est installé pour réaliser des appels API. Consultez Installation dans le référentiel GitHub CLI.
• Avoir openssl installé pour générer un jeton web JSON (JWT). De nombreux appareils ont installé OpenSSL par défaut. Vous pouvez vérifier en exécutant openssl -v, qui retourne un numéro de version s’il est installé.
• Utilisez un interpréteur de commandes Unix tel que Bash, ZSH ou Git Bash.

1. Préparer la génération d’un JWT

Pour demander un jeton d’accès à partir d’une application, vous avez besoin d’un jeton web JSON (JWT) généré à partir de l’ID client et de la clé privée de l’application. De nombreux langages de programmation ont des méthodes intégrées pour générer un JWT. Dans ce tutoriel, vous allez utiliser un script Bash pour générer un JWT à partir de la ligne de commande à l’aide opensslde .

1. Copiez le contenu du script Bash pour générer un JWT à partir d’AUTOTITLE.

2. Enregistrez le contenu dans un nouveau fichier dans votre répertoire de base, appelé gen-jwt.sh.

3. Rendre le script exécutable.

   Shell

   chmod +x ~/gen-jwt.sh
   

2. Créer deux applications d’entreprise

Les GitHub Apps ne peuvent générer des jetons qu’avec les autorisations détaillées et les portées de compte que vous autorisez. Dans cette étape, vous allez créer deux applications appartenant à l’entreprise : une avec l’autorisation d’installation des applications au niveau de l’entreprise et une autre avec l’autorisation au niveau de l’organisation pour créer un référentiel.

a. Créer l'installateur

L’application « programme d’installation » est installée sur le compte d’entreprise et aura l’autorisation d’installer l’autre application dans une organisation.

1. Créez une application sous votre compte d’entreprise.

   1. Accédez aux paramètres de votre compte d’entreprise.
   2. Dans la barre latérale à gauche, cliquez sur GitHub Apps .
   3. Cliquez sur Nouvelle GitHub App.

2. Vous pouvez conserver la plupart des valeurs par défaut, sauf :

   • Appelez l’application YOUR-HANDLE-installer-app, en remplaçant YOUR-HANDLE par votre nom d’utilisateur GitHub.
   • Définissez l’URL de la page d’accueil sur https://github.com.
   • Désélectionnez Expirer les jetons d’autorisation utilisateur et, sous « Webhook », désélectionnez Active.
   • Sous « Autorisations d’entreprise », accordez à l’application des autorisations de lecture et d’écriture pour les installations de l’organisation Entreprise.

3. Après avoir créé l’application, copiez l’ID client et enregistrez-le sous la forme d’une variable appelée INSTALLER_APP_CLIENT_ID. Par exemple, sur la ligne de commande :

   Shell

   export INSTALLER_APP_CLIENT_ID='abcde12345'
   

4. Dans la page de l’application, faites défiler vers le bas et cliquez sur Générer une clé privée. Le fichier de clé privée sera téléchargé.

5. Notez le chemin d’accès du fichier, qui ressemblera à ~/YOUR-HANDLE-installer-app.DOWNLOAD-DATE.private-key.pem.

6. Dans la barre latérale gauche de la page de l’application, cliquez sur Installer l’application, puis installez la nouvelle application sur le compte d’entreprise. L’installation d’une application autorise l’application à effectuer des actions dans le compte.

7. Examinez l’URL dans votre navigateur pour rechercher l’ID d’installation de l’application. Il s’agit d’une chaîne de nombres à la fin de l’URL /enterprises/ENTERPRISE/settings/installations/ID . Enregistrez-le sous la forme de la INSTALLER_APP_INSTALL_ID variable.

   Shell

   export INSTALLER_APP_INSTALL_ID='12345678'
   

8. Enregistrez le nom de l’entreprise où l’application est installée en tant que variable.

   Shell

   export ENTERPRISE='octo-enterprise'
   

b. Créer l’application d’automatisation

L'« application automation » sera installée dans une organisation et aura l’autorisation de créer des dépôts dans cette organisation. En réalité, vous donneriez à cette application les autorisations requises pour automatiser un processus dans vos organisations.

1. Créez une application sous votre compte d’entreprise.

   • Appelez l’application YOUR-HANDLE-automation-app, en remplaçant YOUR-HANDLE par votre nom d’utilisateur GitHub.
   • Définissez l’URL de la page d’accueil sur https://github.com.
   • Désélectionnez Expirer les jetons d’autorisation utilisateur et, sous « Webhook », désélectionnez Active.
   • Sous « Autorisations de référentiel », accordez aux applications des autorisations de lecture et d’écriture pour l’administration.

2. Après avoir créé l’application, copiez l’ID client et enregistrez-le AUTOMATION_APP_CLIENT_ID en tant que variable.

   Shell

   export AUTOMATION_APP_CLIENT_ID='abcde12345'
   

3. Faites défiler vers le bas et cliquez sur Générer une clé privée. Le fichier de clé privée sera téléchargé.

4. Notez le chemin d’accès du fichier, qui ressemblera à ~/YOUR-HANDLE-automation-app.DOWNLOAD-DATE.private-key.pem.

5. Enregistrez le nom de l’organisation où l’application sera installée en tant que variable.

   Shell

   export ORG='octo-org'
   

3. Authentifier l’application installateur

L’authentification d’une application vous permet d’obtenir un jeton avec l’étendue et les autorisations que vous avez définies lors de l’inscription de l’application. Dans ce cas, vous obtiendrez un jeton pour l’application d’installation, ce qui vous donnera l’autorisation d’installer l’application Automation dans une organisation.

1. Générez un JWT à l’aide du script Bash que vous avez enregistré. Par exemple:

   Shell

   ~/gen-jwt.sh $INSTALLER_APP_CLIENT_ID ~/YOUR-HANDLE-installer-app.DOWNLOAD-DATE.private-key.pem
   

2. Copiez le JWT (la longue chaîne après JWT= ) et enregistrez-le sous forme de variable.

   Shell

   export INSTALL_JWT='abcde12345'
   

3. Utilisez le JWT pour authentifier une demande de jeton d’accès d’installation. Cette étape utilise le point de terminaison de l'API Créer un jeton d’accès d’installation pour une application et nécessite l'ID d'installation de l'application.

   Shell

   gh api --method POST "/app/installations/$INSTALLER_APP_INSTALL_ID/access_tokens" --header "Authorization: Bearer $INSTALL_JWT"
   

4. Vous devez voir un objet JSON contenant une token propriété. Copiez le jeton d’accès (valeur de la token propriété, sans guillemets) et enregistrez-le INSTALLER_APP_INSTALL_TOKEN en tant que variable.

   Shell

   export INSTALLER_APP_INSTALL_TOKEN='abcde12345'
   

4. Installer l’application Automation

Le jeton d’accès d’installation que vous venez de recevoir vous donne l’autorisation d’appeler l’API pour installer des applications dans une organisation. Ici, nous allons utiliser le jeton pour installer l’application Automation (la deuxième application que vous avez créée) dans une organisation spécifique. En réalité, vous pouvez appeler cette API plusieurs fois pour installer une application dans plusieurs organisations.

1. Exécutez la commande suivante. Nous utilisons le point de terminaison de l'API Installer une application GitHub sur une organisation appartenant à l'entreprise, en nous authentifiant avec le jeton d'installation que vous venez de demander et en transmettant l'ID client de l'application d'automatisation que nous souhaitons installer.

   Shell

   gh api --method POST \
     "/enterprises/$ENTERPRISE/apps/organizations/$ORG/installations" \
     --header "Authorization: Bearer $INSTALLER_APP_INSTALL_TOKEN" \
     --header "Accept: application/vnd.github+json" \
     --header "X-GitHub-Api-Version: 2022-11-28" \
     --field "client_id=$AUTOMATION_APP_CLIENT_ID" \
     --field "repository_selection=all"
   

2. Si elle réussit, vous devez voir un grand nombre de propriétés retournées, en commençant par l’ID d’installation de l’application.

   Pour vérifier que l’application a été correctement installée, accédez à https://github.com/organizations/ORG/settings/installations, en remplaçant ORG par le nom de l'organisation. Vous devez voir l’application nouvellement installée sur la page.

3. Recherchez l’ID d’installation de la nouvelle installation et enregistrez-le sous AUTOMATION_APP_INSTALL_ID. Pour trouver l’ID, vous pouvez copier la première propriété d’ID retournée par l’API, ou cliquer sur Configurer en regard de l’installation de l’application dans l’interface utilisateur et copier l’ID à partir de l’URL.

   Shell

   export AUTOMATION_APP_INSTALL_ID='12345678'
   

5. Authentifier l'application d'automatisation

Tout comme vous avez authentifié l’application d’installation pour obtenir un jeton délimité au niveau de l’entreprise, vous devez maintenant effectuer le même processus pour l’application d’automatisation. Cela vous donnera un jeton à portée organisationnelle avec l'autorisation de créer des dépôts.

1. Générez un JWT avec l’ID client et la clé privée de l’application Automation. Par exemple:

   Shell

   ~/gen-jwt.sh $AUTOMATION_APP_CLIENT_ID ~/octocat-automation-app.2025-10-08.private-key.pem
   

2. Copiez le JWT (la longue chaîne après JWT= ) et enregistrez-le sous forme de variable.

   Shell

   export AUTO_JWT='abcde12345'
   

3. Utilisez le JWT pour authentifier une demande de jeton d’accès d’installation, cette fois en passant l’ID d’installation et JWT pour l’application Automation nouvellement installée.

   Shell

   gh api --method POST "/app/installations/$AUTOMATION_APP_INSTALL_ID/access_tokens" --header "Authorization: Bearer $AUTO_JWT"
   

4. Copiez le nouveau jeton d’accès d’installation et enregistrez-le AUTOMATION_APP_INSTALL_TOKEN en tant que variable.

   Shell

   export AUTOMATION_APP_INSTALL_TOKEN='abcde12345'
   

6. Automatiser un processus

Le jeton d’installation que vous venez de recevoir vous donne l’autorisation de créer un référentiel dans l’organisation où l’application est installée.

1. Exécutez la commande suivante. Notez que nous nous authentifions avec le jeton d’installation que nous venons d’obtenir.

   Shell

   gh api --method POST \
     "/orgs/$ORG/repos" \
     --header "Authorization: Bearer $AUTOMATION_APP_INSTALL_TOKEN" \
     --header "Accept: application/vnd.github+json" \
     --header "X-GitHub-Api-Version: 2022-11-28" \
     --field "name=automatic-repo" \
     --field "description=Repository created automatically using GitHub App automation" \
     --field "private=false" \
     --field "auto_init=true"
   

2. Pour vérifier que le référentiel a été créé avec succès, accédez à https://github.com/orgs/ORG/repositories, en remplaçant ORG par le nom de votre organisation.

          <a href="https://docs.github.io/success-test/yes.html" target="_blank" class="btn btn-outline mt-3 mr-3 no-underline">
          <span>Oui</span></a><a href="https://docs.github.io/success-test/no.html" target="_blank" class="btn btn-outline mt-3 mr-3 no-underline"><span>Non</span></a>

7. Désinstaller les applications

Pour la sécurité, désinstallez les applications de l’entreprise et de l’organisation. Cela révoque tous les jetons associés aux applications. Pour les instructions, consultez Révision et modification des applications GitHub installées.

Étapes suivantes

Vous avez vu comment installer une application par programmation dans les organisations et exécuter une automatisation. Vous devez maintenant être prêt à automatiser un processus réel dans plusieurs organisations. Pour plus d’informations sur ce que les applications peuvent faire, consultez À propos de la création d’applications GitHub.