Automatische Tokenauthentifizierung

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

Wenn du Actions aktivierst, installiert eine App in deinem Repository. Das _TOKEN-Geheimnis ist ein Installationszugriffstoken der App. Du kannst das Installationszugriffs-Token verwenden, um Dich im Namen der auf deinem Repository installierten 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 _TOKEN.

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

Das Token ist auch im .token-Kontext verfügbar. Weitere Informationen finden Sie unter Zugreifen auf kontextbezogene Informationen zu Workflowausführungen.

Du kannst das _TOKEN mit der Standardsyntax zum Verweisen auf Geheimnisse verwenden: ${{ secrets._TOKEN }}. Zu den Beispielen für die Verwendung von _TOKEN zählt das Übergeben des Tokens als Eingabe an eine Aktion oder dessen Verwendung, um eine authentifizierte -API-Anforderung zu erstellen.

Wenn du Tasks mithilfe des _TOKEN-Geheimnisses des Repositorys ausführst, wird durch keines der durch das _TOKEN-Geheimnis ausgelösten Ereignisse, außer workflow_dis und repository_dis, eine neue Workflowausführung erstellt. Dadurch wird verhindert, dass du versehentlich rekursive Workflow-Ausführung erstellst. Wenn beispielsweise eine Workflowausführung Code über das _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 Actions-Workflow gepusht werden, der das _TOKEN verwendet, lösen keinen Pages-Build aus.

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

name: Open new issue
on: workflow_dis

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

name: Open new issue
on: workflow_dis

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

Du kannst das _TOKEN für authentifizierte API-Aufrufe verwenden. Dieser Beispiel-Workflow erzeugt eine Lieferung („issue“) mittels der -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 https://api..com/repos/${{ .repository }}/issues \
          --header 'authorization: Bearer ${{ secrets._TOKEN }}' \
          --header 'content-type: application/json' \
          --data '{
            "title": "Automated issue for commit: ${{ .sha }}",
            "body": "This issue was automatically created by the  Action workflow **${{ .workflow }}**. \n\n The commit hash was: _${{ .sha }}_."
            }' \
          --fail

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

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

Du kannst die Berechtigungen für das _TOKEN in einzelnen Workflowdateien ändern. Wenn die Standardberechtigungen für das _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 _TOKEN zu entfernen. Als bewährte Sicherheitsmethode solltest du dem _TOKEN nur den geringsten erforderlichen Zugriff gewähren.

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

Du kannst den permissions-Schlüssel in deiner Workflowdatei verwenden, um Berechtigungen für das _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.

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 Actions-Einstellungen ausgewählt hat. Weitere Informationen finden Sie unter Verwalten von 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 Actions.

Die Berechtigungen für das _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.

Wenn du ein Token benötigst, das Berechtigungen erfordert, die im _TOKEN nicht verfügbar sind, kannst du eine App erstellen und ein Installationszugriffstoken in deinem Workflow generieren. Weitere Informationen finden Sie unter Authentifizierte API-Anforderungen mit einer -App in einem 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 findest du unter Verwalten deiner persönlichen Zugriffstoken und Verwenden von Geheimnissen in -Aktionen.

• Ratenbegrenzungen für die REST-API