Authentifizierte API-Anforderungen mit einer GitHub-App in einem GitHub Actions-Workflow

Informationen zur GitHub Actions-Authentifizierung

Wenn du authentifizierte API-Anforderungen in einem GitHub Actions-Workflow tätigen oder eine benutzerdefinierte Aktion ausführen musst, für die ein Token benötigt wird, solltest du nach Möglichkeit das integrierte GITHUB_TOKEN verwenden. Das GITHUB_TOKEN kann jedoch nur auf die Ressourcen im Repository des Workflows zugreifen. Wenn du Zugriff auf zusätzliche Ressourcen benötigst, zum Beispiel Ressourcen in einer Organisation oder in einem anderen Repository, kannst du eine GitHub App verwenden. Weitere Informationen dazu, unter welchen Umständen du eine GitHub App anstelle eines personal access token verwenden solltest, findest du unter Informationen zum Erstellen von GitHub-Apps.

Authentifizieren mit einer GitHub App

Um authentifizierte API-Anforderungen mithilfe einer GitHub App zu tätigen, musst du eine GitHub App registrieren, die Anmeldeinformationen deiner App speichern und deine App installieren. Anschließend kannst du deine App verwenden, um ein Installationszugriffstoken zu erstellen, das zum Tätigen authentifizierter API-Anforderungen in einem GitHub Actions-Workflow verwendet werden kann. Du kannst das Installationszugriffstoken auch an eine benutzerdefinierte Aktion übergeben, für die ein Token benötigt wird.

1. Registriere eine GitHub App. Erteile deiner GitHub App-Registrierung die erforderlichen Berechtigungen für den Zugriff auf die gewünschten Ressourcen. Weitere Informationen findest du unter Registrieren einer GitHub-App und Auswählen von Berechtigungen für eine GitHub-App.

2. Die App-ID der GitHub App muss als GitHub Actions-Konfigurationsvariable gespeichert werden. Du findest die App-ID auf der Einstellungsseite deiner App. Die App-ID unterscheidet sich von der Client-ID. Weitere Informationen zum Navigieren zur Einstellungsseite deiner GitHub App findest du unter Ändern einer GitHub-App-Registrierung. Weitere Informationen zum Speichern von Konfigurationsvariablen findest du unter Speichern von Informationen in Variablen.

3. Generiere einen privaten Schlüssel für deine App. Speichere den Inhalt der resultierenden Datei als Geheimnis. Speichere den gesamten Inhalt der Datei, einschließlich -----BEGIN RSA PRIVATE KEY----- und -----END RSA PRIVATE KEY-----. Weitere Informationen findest du unter Verwalten privater Schlüssel für GitHub-Apps. Weitere Informationen zum Speichern von Geheimnissen findest du unter Verwenden von Geheimnissen in GitHub-Aktionen.

4. Installiere die GitHub App in deinem Benutzerkonto oder deiner Organisation, und erteile ihr Zugriff auf alle Repositorys, auf die dein Workflow zugreifen soll. Weitere Informationen finden Sie unter Installieren einer eigenen GitHub-App.

5. Erstelle in deinem GitHub Actions-Workflow ein Installationszugriffstoken, das für API-Anforderungen verwendet werden kann.

   Dafür kannst du eine Aktion von GitHub verwenden, wie im folgenden Beispiel gezeigt. Wenn Sie diese Aktion nicht verwenden möchten, können Sie die actions/create-github-app-token Aktion forken und bearbeiten oder ein Skript schreiben, damit Ihrr Workflow manuell ein Installationstoken erstellt. Weitere Informationen findest du unter Authentifizierung als GitHub-App-Installation.

   Der folgende Beispielworkflow verwendet die actions/create-github-app-token-Aktion, um ein Installationszugriffstoken zu generieren. Anschließend verwendet der Workflow das Token, um eine API-Anforderung über GitHub CLI zu tätigen.

   Im folgenden Workflow muss APP_ID durch den Namen der Konfigurationsvariable ersetzt werden, in der die App-ID gespeichert ist. Ersetze APP_PRIVATE_KEY durch den Namen des Geheimnisses, in dem der private Schlüssel der App gespeichert ist.

on:
  workflow_dispatch:
jobs:
  demo_app_authentication:
    runs-on: ubuntu-latest
    steps:
      - name: Generate a token
        id: generate-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ vars.APP_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}

      - name: Use the token
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
        run: |
          gh api octocat

on:
  workflow_dispatch:
jobs:
  demo_app_authentication:
    runs-on: ubuntu-latest
    steps:
      - name: Generate a token
        id: generate-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ vars.APP_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}

      - name: Use the token
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
        run: |
          gh api octocat