Automatische Tokenauthentifizierung

Informationen zum GITHUB_TOKEN-Geheimnis

Bei jedem Start eines Workflowauftrags erstellt GitHub automatisch ein eindeutiges GITHUB_TOKEN-Geheimnis, das in deinem Workflow verwendet wird. Du kannst das GITHUB_TOKEN verwenden, um dich im Workflowauftrag zu authentifizieren.

Wenn du GitHub Actions aktivierst, installiert GitHub eine GitHub App in deinem Repository. Das GITHUB_TOKEN-Geheimnis ist ein Installationszugriffstoken der GitHub App. Du kannst das Installationszugriffs-Token verwenden, um Dich im Namen der auf deinem Repository installierten GitHub App zu authentifizieren. Die Berechtigungen des Tokens sind auf das Repository beschränkt, in dem sich der Workflow befindet. Weitere Informationen findest du unter Berechtigungen für das GITHUB_TOKEN.

Vor Beginn jedes Auftrags ruft GitHub ein Installationszugriffstoken für den Auftrag ab. GITHUB_TOKEN läuft ab, wenn ein Auftrag beendet wird bzw. spätestens nach 24 Stunden.

Das Token ist auch im github.token-Kontext verfügbar. Weitere Informationen findest du unter Kontexte.

Verwenden des GITHUB_TOKEN in einem Workflow

Du kannst das GITHUB_TOKEN mit der Standardsyntax zum Verweisen auf Geheimnisse verwenden: ${{ secrets.GITHUB_TOKEN }}. Beispiele zum Verwenden des GITHUB_TOKEN sind das Übergeben des Tokens als Eingabe für eine Aktion oder das Verwenden für eine authentifizierte API-Anforderung für GitHub Enterprise Server.

Wenn Sie das GITHUB_TOKEN des Repositorys zum Ausführen von Tasks verwenden, erstellen Ereignisse, die von GITHUB_TOKEN ausgelöst werden, mit Ausnahme von workflow_dispatch und repository_dispatch keine neue Workflowausführung. Dadurch wird verhindert, dass du versehentlich rekursive Workflow-Ausführung erstellst. Wenn beispielsweise eine Workflowausführung Code über das GITHUB_TOKEN des Repositorys pusht, wird ein neuer Workflow auch dann nicht ausgeführt, wenn das Repository einen Workflow enthält, der für die Ausführung beim Auftreten von push-Ereignissen konfiguriert wurde.

Commits, die von einem GitHub Actions-Workflow gepusht werden, der das GITHUB_TOKEN verwendet, lösen keinen GitHub Pages-Build aus.

Beispiel 1: Übergeben des GITHUB_TOKEN als Eingabe

In diesem Beispielworkflow wird die GitHub CLI verwendet, die das GITHUB_TOKEN als Wert für den GH_TOKEN-Eingabeparameter erfordert:

name: Open new issue
on: workflow_dispatch

jobs:
  open-issue:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
    steps:
      - run: |
          gh issue --repo ${{ github.repository }} \
            create --title "Issue title" --body "Issue body"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

name: Open new issue
on: workflow_dispatch

jobs:
  open-issue:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
    steps:
      - run: |
          gh issue --repo ${{ github.repository }} \
            create --title "Issue title" --body "Issue body"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Beispiel 2: Aufrufen der REST-API

Du kannst das GITHUB_TOKEN für authentifizierte API-Aufrufe verwenden. Dieser Beispiel-Workflow erzeugt eine Lieferung („issue“) mittels der GitHub-REST-API:

name: Create issue on commit

on: [ push ]

jobs:
  create_issue:
    runs-on: ubuntu-latest
    permissions:
      issues: write
    steps:
      - name: Create issue using REST API
        run: |
          curl --request POST \
          --url http(s)://HOSTNAME/api/v3/repos/${{ github.repository }}/issues \
          --header 'authorization: Bearer ${{ secrets.GITHUB_TOKEN }}' \
          --header 'content-type: application/json' \
          --data '{
            "title": "Automated issue for commit: ${{ github.sha }}",
            "body": "This issue was automatically created by the GitHub Action workflow **${{ github.workflow }}**. \n\n The commit hash was: _${{ github.sha }}_."
            }' \
          --fail

Berechtigungen für das GITHUB_TOKEN

Weitere Informationen zu den API-Endpunkten, auf die GitHub Apps mit den jeweiligen Berechtigungen zugreifen können, findest du unter Für GitHub-Apps erforderliche Berechtigungen.

In der folgenden Tabelle findest du die standardmäßig für das GITHUB_TOKEN erteilten Berechtigungen. Personen mit Administratorberechtigungen für ein eine Organisation oder ein Repository können die Standardberechtigungen entweder auf uneingeschränkt oder eingeschränkt festlegen. Informationen zum Festlegen der Standardberechtigungen für GITHUB_TOKEN für dein Unternehmen, deine Organisation oder dein Repository findest du unter Erzwingen von Richtlinien für GitHub Actions in deinem Unternehmen, GitHub Actions für deine Organisation Deaktivieren oder Einschränken oder Verwalten von GitHub Actions-Einstellungen für ein Repository.

Ändern der Berechtigungen für das GITHUB_TOKEN

Du kannst die Berechtigungen für das GITHUB_TOKEN in einzelnen Workflowdateien ändern. Wenn die Standardberechtigungen für das GITHUB_TOKEN restriktiv sind, musst du die Berechtigungen eventuell erhöhen, damit manche Aktionen und Befehle erfolgreich ausgeführt werden können. Wenn die Standardberechtigungen nicht restriktiv sind, kannst du die Workflowdatei bearbeiten, um einige Berechtigungen aus dem GITHUB_TOKEN zu entfernen. Als bewährte Sicherheitsmethode solltest du dem GITHUB_TOKEN nur den geringsten erforderlichen Zugriff gewähren.

Du kannst die Berechtigungen von GITHUB_TOKEN für einen bestimmten Auftrag im Abschnitt „Auftrag einrichten“ des Workflowausführungsprotokolls anzeigen. Weitere Informationen findest du unter Verwenden von Workflowausführungsprotokollen.

Du kannst den permissions-Schlüssel in deiner Workflowdatei verwenden, um Berechtigungen für das GITHUB_TOKEN für einen gesamten Workflow oder für einzelne Aufträge zu ändern. So kannst du die erforderlichen Mindestberechtigungen für einen Workflow oder Auftrag konfigurieren. Wenn der permissions-Schlüssel verwendet wird, werden alle nicht angegebenen Berechtigungen mit Ausnahme des Bereichs metadata, der immer Lesezugriff erhält, auf „Kein Zugriff“ festgelegt.

Darüber hinaus kannst du den permissions-Schlüssel verwenden, um Leseberechtigungen für geforkte Repositorys hinzuzufügen oder zu entfernen, aber in der Regel kannst du keinen Schreibzugriff gewähren. Eine Ausnahme für dieses Verhalten besteht dann, wenn ein Administratorbenutzer die Option Schreibtoken an Workflows aus Pull Requests senden in den GitHub Actions-Einstellungen ausgewählt hat. Weitere Informationen findest du unter Verwalten von GitHub Actions-Einstellungen für ein Repository.

Die beiden Workflowbeispiele weiter oben in diesem Artikel zeigen die Verwendung des permissions-Schlüssels auf Auftragsebene, da die Begrenzung des Umfangs der Berechtigungen eine bewährte Methode ist.

Ausführliche Informationen zum Schlüssel permissions findest du unter Workflowsyntax für GitHub Actions.

Berechnen der Berechtigungen für einen Workflowauftrag

Die Berechtigungen für das GITHUB_TOKEN werden zunächst auf die Standardeinstellung für das Unternehmen, die Organisation oder das Repository festgelegt. Wenn die Standardeinstellung auf einer dieser Ebenen auf eingeschränkte Berechtigungen festgelegt ist, gilt dies für die relevanten Repositorys. Wenn du beispielsweise den eingeschränkten Standard auf Organisationsebene auswählst, verwenden alle Repositorys in dieser Organisation standardmäßig die eingeschränkten Berechtigungen. Die Berechtigungen werden dann zuerst auf Workflowebene und schließlich auf Auftragsebene basierend auf den Konfigurationen in der Workflowdatei angepasst. Wenn der Workflow schließlich von einem Pull Request aus einem geforkten Repository ausgelöst wurde und die Einstellung Schreibtoken aus Pull Requests an Workflows senden nicht ausgewählt ist, werden die Berechtigungen so angepasst, dass Schreibberechtigungen in schreibgeschützt geändert werden.

Erteilen zusätzlicher Berechtigungen

Wenn du ein Token benötigst, das Berechtigungen erfordert, die im GITHUB_TOKEN nicht verfügbar sind, kannst du eine GitHub App erstellen und ein Installationszugriffstoken in deinem Workflow generieren. Weitere Informationen findest du unter Authentifizierte API-Anforderungen mit einer GitHub-App in einem GitHub Actions-Workflow. Alternativ kannst du ein personal access token erstellen, als Geheimnis in deinem Repository speichern und das Token in deinem Workflow mit der Syntax ${{ secrets.SECRET_NAME }} verwenden. Weitere Informationen finden Sie unter Verwalten deiner persönlichen Zugriffstoken und unter Verwenden von Geheimnissen in GitHub-Aktionen.

Weiterführende Themen

• Ratenbegrenzungen für die REST-API