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.

   Hierfür können Sie – wie im folgenden Beispiel veranschaulicht – eine vorgefertigte Aktion verwenden. Wenn du keine Drittanbieteraktion verwenden möchtest, kannst du die tibdex/github-app-token-Aktion forken und bearbeiten oder ein Skript schreiben, damit dein Workflow manuell ein Installationstoken erstellt. Weitere Informationen findest du unter Authentifizierung als GitHub-App-Installation.

   Der folgende Beispielworkflow verwendet die tibdex/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.

# Dieser Workflow verwendet Aktionen, die nicht von GitHub zertifiziert sind.
# Sie werden von einem Drittanbieter bereitgestellt und unterliegen
# separaten Nutzungsbedingungen, Datenschutzbestimmungen und Support
# Onlinedokumentation.

# GitHub empfiehlt, Aktionen an einen Commit-SHA anzuheften.
# Um eine neuere Version zu erhalten, musst du den SHA aktualisieren.
# Du kannst auch auf ein Tag oder einen Branch verweisen, aber die Aktion kann sich ohne Vorwarnung ändern.

on:
  workflow_dispatch:
jobs:
  demo_app_authentication:
    runs-on: ubuntu-latest
    steps:
      - name: Generate a token
        id: generate-token
        uses: tibdex/github-app-token@32691ba7c9e7063bd457bd8f2a5703138591fa58 # v1.9.0
        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

# Dieser Workflow verwendet Aktionen, die nicht von GitHub zertifiziert sind.
# Sie werden von einem Drittanbieter bereitgestellt und unterliegen
# separaten Nutzungsbedingungen, Datenschutzbestimmungen und Support
# Onlinedokumentation.

# GitHub empfiehlt, Aktionen an einen Commit-SHA anzuheften.
# Um eine neuere Version zu erhalten, musst du den SHA aktualisieren.
# Du kannst auch auf ein Tag oder einen Branch verweisen, aber die Aktion kann sich ohne Vorwarnung ändern.

on:
  workflow_dispatch:
jobs:
  demo_app_authentication:
    runs-on: ubuntu-latest
    steps:
      - name: Generate a token
        id: generate-token
        uses: tibdex/github-app-token@32691ba7c9e7063bd457bd8f2a5703138591fa58 # v1.9.0
        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