Skip to main content

Automatische Tokenauthentifizierung

GitHub stellt ein Token zur Verfügung, mit dem du dich im Namen von GitHub Actions authentifizieren kannst.

Hinweis: GitHub-gehostete Runner werden auf GitHub Enterprise Server derzeit nicht unterstützt. Weitere Informationen zur geplanten zukünftigen Unterstützung findest Du in der GitHub public roadmap.

Informationen zum GITHUB_TOKEN-Geheimnis

Zu Beginn jeder Workflowausführung erstellt GitHub automatisch ein eindeutiges GITHUB_TOKEN-Geheimnis zum Verwenden in deinem Workflow. Du kannst das GITHUB_TOKEN zum Authentifizieren in einer Workflowausführung verwenden.

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.

Wichtig: Eine Aktion kann über den github.token-Kontext auf das GITHUB_TOKEN zugreifen, auch wenn der Workflow das GITHUB_TOKEN nicht explizit für die Aktion übergibt. Als gute Sicherheitsmethode solltest du immer sicherstellen, dass Aktionen nur über den minimalen benötigten Zugriff verfügen, indem du die Berechtigungen für GITHUB_TOKEN einschränkst. Weitere Informationen findest du unter Berechtigungen für das GITHUB_TOKEN.

Wenn Sie das GITHUB_TOKEN des Repositorys zum Ausführen von Tasks verwenden, erstellen Ereignisse, die von GITHUB_TOKEN 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.

Beispiel 1: Übergeben des GITHUB_TOKEN als Eingabe

In diesem Beispielworkflow wird die Beschrifteraktion verwendet, die das GITHUB_TOKEN als Wert für den repo-token-Eingabeparameter erfordert:

YAML
name: Pull request labeler
on: [ pull_request_target ]

permissions:
  contents: read
  pull-requests: write

jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/labeler@v4
        with:
          repo-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 Berechtigungen von GitHub App.

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. Weitere Informationen zum Festlegen der Standardberechtigungen für das GITHUB_TOKEN für dein Unternehmen, deine Organisation oder dein Repository findest du unter Erzwingen von Richtlinien für GitHub Actions in deinem Unternehmen, Deaktivieren oder Einschränken von GitHub Actions für deine Organisation oder Verwalten von Einstellungen für GitHub Actions für ein Repository.

ScopeStandardzugriff
(uneingeschränkt)
Standardzugriff
(eingeschränkt)
Maximaler Zugriff für
Pull Requests von
Öffentliche geforkte Repositorys[†]
Aktionenread/write (Lesen/Schreiben)KeineLesen
checks (Überprüfungen)read/write (Lesen/Schreiben)KeineLesen
Inhaltread/write (Lesen/Schreiben)LesenLesen
deploymentsread/write (Lesen/Schreiben)KeineLesen
issuesread/write (Lesen/Schreiben)KeineLesen
metadataLesenLesenLesen
packagesread/write (Lesen/Schreiben)KeineLesen
Seitenread/write (Lesen/Schreiben)KeineLesen
pull-requestsread/write (Lesen/Schreiben)KeineLesen
repository-projectsread/write (Lesen/Schreiben)KeineLesen
security-eventsread/write (Lesen/Schreiben)KeineLesen
statusesread/write (Lesen/Schreiben)KeineLesen

[†] Private Repositorys können steuern, ob Pull Requests aus Forks Workflows ausführen können, und die Berechtigungen konfigurieren, die GITHUB_TOKEN zugewiesen sind. Weitere Informationen findest du unter 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 zuvor in diesem Artikel beschriebenen Workflowbeispiele zeigen, wie der permissions-Schlüssel auf Workflowebene und auf Auftragsebene verwendet wird. In Beispiel 1 werden die beiden Berechtigungen für den gesamten Workflow angegeben. In Beispiel 2 wird Schreibzugriff für einen Bereich eines einzelnen Auftrags gewährt.

Vollständige Informationen zum permissions-Schlüssel 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, dass Berechtigungen erfordert, die nicht im GITHUB_TOKEN verfügbar sind, kannst du ein personal access token erstellen und als Geheimnis in deinem Repository festlegen:

  1. Verwende oder erstelle ein Token mit den entsprechenden Berechtigungen für dieses Repository. Weitere Informationen findest du unter Erstellen eines personal access token.
  2. Füge das Token dem Repository deines Workflows als Geheimnis hinzu, und verweise darauf, indem du die Syntax ${{ secrets.SECRET_NAME }} verwendest. Weitere Informationen findest du unter Erstellen und Verwenden verschlüsselter Geheimnisse.

Weiterführende Themen