Automatisieren von App-Installationen in den Unternehmen

Einleitung

Um einen Prozess sicher zu automatisieren, können Sie ein GitHub App erstellen, das einem Unternehmenskonto gehört, und dann die App im Unternehmen oder in der Organisation installieren, in dem die Automatisierung stattfindet.

GitHub Apps stellen Token bereit, mit denen Sie API-Aufrufe an GitHub in Skripts und Workflows authentifizieren können. Diese Token eignen sich für Unternehmen mit spezifischen Sicherheits- und Überwachungsanforderungen, da sie:

• Temporäre Prozeduren
• Beschränkt auf bestimmte Konten und Berechtigungen
• Zugeordnet mit der Identität der App anstelle eines Benutzerkontos

Ein häufiges Bedürfnis für große Unternehmen besteht darin, eine Automatisierung konsistent und auf dem neuesten Stand in vielen Organisationen zu halten. Dazu können Sie eine App programmgesteuert installieren. Wenn Sie beispielsweise alle Organisationen mit bestimmten Richtlinien und Einstellungen konfigurieren müssen, können Sie ein GitHub App für diese Aufgabe in jeder Organisation installieren.

In diesem Handbuch werden die Schritte veranschaulicht, die zum programmgesteuerten Installieren eines unternehmenseigenen GitHub App in einer Organisation erforderlich sind. Nachdem die App installiert wurde, verwenden Sie sie, um ein neues Repository zu erstellen.

Übersicht über den Prozess

In diesem Leitfaden verwenden Sie die GitHub CLI, um die API-Aufrufe zu tätigen, die zum Anfordern von Zugriffstoken erforderlich sind, und eine App in einer Organisation zu installieren. In Wirklichkeit wäre dieser Prozess Teil eines benutzerdefinierten Skripts, das auf die Anforderungen Ihres Unternehmens zugeschnitten ist.

Sie lernen Folgendes:

1. Erstellen Sie zwei Apps, die Ihrem Unternehmenskonto gehören.
   • Einer verfügt über die Berechtigung zum Installieren von Apps in Organisationen.
   • Die andere verfügt über die Berechtigung zum Automatisieren eines Prozesses in einer Organisation (in diesem Fall das Erstellen eines Repositorys).
2. Authentifizieren Sie die erste App, um ein unternehmensweites Zugriffstoken abzurufen.
3. Verwenden Sie das unternehmensweite Token, um eine API aufzurufen, die die Automatisierungs-App in einer Organisation installiert.
4. Authentifizieren Sie die von der Organisation installierte App, um ein organisationsweites Zugriffstoken abzurufen.
5. Verwenden Sie das token mit Organisationsbereich, um eine API aufzurufen, die ein Repository in der Organisation erstellt.

In jeder Phase verwenden Sie ein Token, das nur über die Berechtigung zum Ausführen bestimmter Aktionen in einem bestimmten Konto verfügt. Aus Sicherheits- und Prüfungsperspektive ist dieser Ansatz überlegen im Vergleich dazu, sich auf ein einziges Token mit der Berechtigung zu verlassen, um Aktionen in Ihrem gesamten Unternehmen und in Ihren Organisationen auszuführen.

Voraussetzungen

Um diesem Leitfaden auf Ihrem eigenen Gerät zu folgen, müssen Sie:

• Ein Unternehmensbesitzer sein.
• Werden Sie Eigentümer einer Unternehmensorganisation, in der Sie die Automatisierung implementieren.
• Stellen Sie sicher, dass GitHub CLI installiert ist, um API-Aufrufe zu tätigen. Siehe Installation im Repository GitHub CLI.
• Um ein JSON-Webtoken (JWT) zu generieren, installieren Sie openssl. Auf vielen Geräten ist OpenSSL standardmäßig installiert. Sie können überprüfen, indem Sie ausführen openssl -v, was eine Versionsnummer zurückgibt, wenn sie installiert ist.
• Verwenden Sie eine Unix-Shell wie Bash, ZSH oder Git Bash.

1. Vorbereiten der Erstellung eines JWT

Um ein Zugriffstoken aus einer App anzufordern, benötigen Sie ein JSON-Webtoken (JWT), das aus der Client-ID und dem privaten Schlüssel der App generiert wurde. Viele Programmiersprachen verfügen über integrierte Methoden zum Generieren eines JWT. In diesem Lernprogramm verwenden Sie ein Bash-Skript, um ein JWT von der Befehlszeile aus mit openssl zu generieren.

1. Kopieren Sie den Inhalt des Bash-Skripts zum Generieren eines JWT aus Generieren eines JSON-Webtokens (JWT) für eine GitHub App.

2. Speichern Sie den Inhalt in einer neuen Datei in Ihrem Startverzeichnis, die gen-jwt.sh genannt wird.

3. Erstellen Sie die ausführbare Datei des Skripts.

   Shell

   chmod +x ~/gen-jwt.sh
   

2. Erstellen von zwei Unternehmens-Apps

GitHub Apps kann nur Token mit den von Ihnen zugelassenen differenzierten Berechtigungen und Kontobereichen generieren. In diesem Schritt erstellen Sie zwei unternehmenseigene Apps: eine mit der Berechtigung auf Unternehmensebene zum Installieren von Apps und eine andere mit der Berechtigung auf Organisationsebene zum Erstellen eines Repositorys.

a) Erstellen der Installationsprogramm-App

Die "Installer-App" wird auf dem Unternehmenskonto installiert und verfügt über die Berechtigung zum Installieren der anderen App in einer Organisation.

1. Erstellen Sie eine neue App unter Ihrem Unternehmenskonto.

   1. Wechseln Sie zu ihren Unternehmenskontoeinstellungen.
   2. Klicke auf der linken Randleiste auf GitHub Apps .
   3. Klicken Sie auf Neue GitHub App .

2. Sie können die meisten Werte als Standardwerte belassen, außer:

   • Rufen Sie die App YOUR-HANDLE-installer-app auf, und ersetzen Sie YOUR-HANDLE durch Ihren GitHub Benutzernamen.
   • Legen Sie die "Homepage-URL" auf https://github.com.
   • Deaktivieren Sie Ablauf von Benutzerautorisierungs-Token und deaktivieren Sie im Bereich "Webhook" die Option Aktiv.
   • Geben Sie unter "Unternehmensberechtigungen" der App Lese- und Schreibberechtigungen für Unternehmensorganisationsinstallationen.

3. Kopieren Sie nach dem Erstellen der App die Client-ID , und speichern Sie sie als Variable namens INSTALLER_APP_CLIENT_ID. Beispiel: In der Befehlszeile:

   Shell

   export INSTALLER_APP_CLIENT_ID='abcde12345'
   

4. Scrollen Sie auf der App-Seite nach unten, und klicken Sie auf " Privaten Schlüssel generieren". Die Datei des privaten Schlüssels wird heruntergeladen.

5. Notieren Sie sich den Dateipfad, der ungefähr so aussieht wie ~/YOUR-HANDLE-installer-app.DOWNLOAD-DATE.private-key.pem.

6. Klicken Sie auf der linken Randleiste der App-Seite auf " App installieren", und installieren Sie dann die neue App im Unternehmenskonto. Durch die Installation einer App erhält die App die Berechtigung zum Ausführen von Aktionen im Konto.

7. Sehen Sie sich die URL in Ihrem Browser an, um die Installations-ID der App zu finden. Dies ist eine Zeichenfolge von Zahlen am Ende der /enterprises/ENTERPRISE/settings/installations/ID URL. Speichern Sie dies als INSTALLER_APP_INSTALL_ID Variable.

   Shell

   export INSTALLER_APP_INSTALL_ID='12345678'
   

8. Speichern Sie den Namen des Unternehmens, in dem die App als Variable installiert ist.

   Shell

   export ENTERPRISE='octo-enterprise'
   

b. Erstellen der Automatisierungs-App

Die "Automatisierungs-App" wird in einer Organisation installiert und verfügt über die Berechtigung zum Erstellen von Repositorys in dieser Organisation. In wirklichkeit würden Sie dieser App die erforderlichen Berechtigungen erteilen, um einen Prozess in Ihren Organisationen zu automatisieren.

1. Erstellen Sie eine neue App unter Ihrem Unternehmenskonto.

   • Rufen Sie die App YOUR-HANDLE-automation-app auf, und ersetzen Sie YOUR-HANDLE durch Ihren GitHub Benutzernamen.
   • Legen Sie die "Homepage-URL" auf https://github.com.
   • Deaktivieren Sie Ablauf von Benutzerautorisierungs-Token und deaktivieren Sie im Bereich "Webhook" die Option Aktiv.
   • Unter „Repository-Berechtigungen“ erteilen Sie der App Lese- und Schreibberechtigungen für Administration.

2. Kopieren Sie nach dem Erstellen der App die Client-ID , und speichern Sie sie als AUTOMATION_APP_CLIENT_ID Variable.

   Shell

   export AUTOMATION_APP_CLIENT_ID='abcde12345'
   

3. Scrollen Sie nach unten, und klicken Sie auf "Privaten Schlüssel generieren". Die Datei des privaten Schlüssels wird heruntergeladen.

4. Notieren Sie sich den Dateipfad, der ungefähr so aussieht wie ~/YOUR-HANDLE-automation-app.DOWNLOAD-DATE.private-key.pem.

5. Speichern Sie den Namen der Organisation, in der die App als Variable installiert wird.

   Shell

   export ORG='octo-org'
   

3. Authentifizieren der Installationsprogramm-App

Durch die Authentifizierung einer App können Sie ein Token mit dem Bereich und den Berechtigungen abrufen, den Sie beim Registrieren der App definiert haben. In diesem Fall erhalten Sie ein Token für die Installer-App, das Ihnen die Berechtigung zum Installieren der Automatisierungs-App in einer Organisation erteilt.

1. Generieren Sie ein JWT mithilfe des gespeicherten Bash-Skripts. Beispiel:

   Shell

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

2. Kopieren Sie das JWT (die lange Zeichenfolge nach JWT= ) und speichern Sie sie als Variable.

   Shell

   export INSTALL_JWT='abcde12345'
   

3. Verwenden Sie das JWT, um eine Anforderung für ein Installationszugriffstoken zu authentifizieren. Dieser Schritt verwendet das Erstellen eines Installationszugriffstokens für einen App-API-Endpunkt und erfordert die Installations-ID der App.

   Shell

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

4. Es sollte ein JSON-Objekt mit einer token Eigenschaft angezeigt werden. Kopieren Sie das Zugriffstoken (den Wert der token Eigenschaft, ohne Anführungszeichen), und speichern Sie es als INSTALLER_APP_INSTALL_TOKEN Variable.

   Shell

   export INSTALLER_APP_INSTALL_TOKEN='abcde12345'
   

4. Installieren der Automatisierungs-App

Das soeben empfangene Installationszugriffstoken gewährt Ihnen die Berechtigung, die API zum Installieren von Apps in einer Organisation aufzurufen. Hier verwenden wir das Token, um die Automatisierungs-App (die zweite app, die Sie erstellt haben) in einer bestimmten Organisation zu installieren. In Wirklichkeit könnten Sie diese API mehrmals aufrufen, um eine App in mehreren Organisationen zu installieren.

1. Führen Sie den folgenden Befehl aus. Wir verwenden den API-Endpunkt Installiere eine GitHub-App in einer unternehmensgeführten Organisation, authentifizieren uns mit dem gerade angeforderten Installationstoken und übergeben die Client-ID der Automatisierungs-App, die wir installieren möchten.

   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. Bei erfolgreicher Ausführung sollte eine große Anzahl zurückgegebener Eigenschaften angezeigt werden, beginnend mit der Installations-ID der App.

   Um zu überprüfen, ob die App erfolgreich installiert wurde, gehen Sie zu https://github.com/organizations/ORG/settings/installations, indem Sie ORG durch den Namen der Organisation ersetzen. Die neu installierte App sollte auf der Seite angezeigt werden.

3. Suchen Sie die Installations-ID der neuen Installation, und speichern Sie sie unter AUTOMATION_APP_INSTALL_ID. Um die ID zu finden, können Sie entweder die erste id-Eigenschaft kopieren, die von der API zurückgegeben wird, oder auf "Konfigurieren" neben der App-Installation in der Benutzeroberfläche klicken und die ID aus der URL kopieren.

   Shell

   export AUTOMATION_APP_INSTALL_ID='12345678'
   

5. Authentifizieren der Automatisierungs-App

Genau wie Sie die Installationsprogramm-App zum Abrufen eines Unternehmenstokens authentifiziert haben, müssen Sie jetzt denselben Prozess für die Automatisierungs-App ausführen. Dadurch erhalten Sie ein organisationsgebundenes Token mit der Berechtigung zum Erstellen von Repositorys.

1. Generieren Sie ein JWT mit der Client-ID und dem privaten Schlüssel der Automatisierungs-App. Beispiel:

   Shell

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

2. Kopieren Sie das JWT (die lange Zeichenfolge nach JWT= ) und speichern Sie sie als Variable.

   Shell

   export AUTO_JWT='abcde12345'
   

3. Verwenden Sie das JWT, um eine Anforderung für ein Installationszugriffstoken zu authentifizieren, indem Sie diesmal die Installations-ID und das JWT für die neu installierte Automatisierungsanwendung übergeben.

   Shell

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

4. Kopieren Sie das neue Installationszugriffstoken, und speichern Sie es als AUTOMATION_APP_INSTALL_TOKEN Variable.

   Shell

   export AUTOMATION_APP_INSTALL_TOKEN='abcde12345'
   

6. Automatisieren eines Prozesses

Das soeben empfangene Installationstoken gewährt Ihnen die Berechtigung, ein Repository in der Organisation zu erstellen, in der die App installiert ist.

1. Führen Sie den folgenden Befehl aus. Beachten Sie, dass wir mit dem soeben abgerufenen Installationstoken authentifizieren.

   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. Um zu überprüfen, ob das Repository erfolgreich erstellt wurde, wechseln Sie zu https://github.com/orgs/ORG/repositories, und ersetzen Sie "ORG" durch den Namen Ihrer Organisation.

          <a href="https://docs.github.io/success-test/yes.html" target="_blank" class="btn btn-outline mt-3 mr-3 no-underline">
          <span>Ja</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>Nein</span></a>

7. Deinstallieren Sie die Apps.

Deinstallieren Sie aus Sicherheitsgründen die Apps aus dem Unternehmen und der Organisation. Dadurch werden alle Token widerrufen, die den Apps zugeordnet sind. Anweisungen findest du unter Überprüfen und Ändern der installierten GitHub Apps.

Nächste Schritte

Sie haben gesehen, wie Sie eine App programmgesteuert in Organisationen installieren und eine Automatisierung ausführen. Jetzt sollten Sie bereit sein, einen echten Prozess in mehreren Organisationen zu automatisieren. Weitere Informationen dazu, was Apps tun können, finden Sie unter Informationen zum Erstellen von GitHub Apps.