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
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.
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
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.
Scope | Standardzugriff (uneingeschränkt) | Standardzugriff (eingeschränkt) | Maximaler Zugriff für Pull Requests von Öffentliche geforkte Repositorys |
---|---|---|---|
Aktionen | read/write (Lesen/Schreiben) | none | Lesen |
checks (Überprüfungen) | read/write (Lesen/Schreiben) | none | Lesen |
Inhalt | read/write (Lesen/Schreiben) | Lesen | Lesen |
deployments | read/write (Lesen/Schreiben) | none | Lesen |
issues | read/write (Lesen/Schreiben) | none | Lesen |
metadata | Lesen | Lesen | Lesen |
packages | read/write (Lesen/Schreiben) | read | Lesen |
Seiten | read/write (Lesen/Schreiben) | none | Lesen |
pull-requests | read/write (Lesen/Schreiben) | none | Lesen |
repository-projects | read/write (Lesen/Schreiben) | none | Lesen |
security-events | read/write (Lesen/Schreiben) | none | Lesen |
statuses | read/write (Lesen/Schreiben) | none | Lesen |
Hinweise:
- Wenn ein Workflow durch das
pull_request_target
-Ereignis ausgelöst wird, wird demGITHUB_TOKEN
die Berechtigung zum Lesen/Schreiben des Repositorys erteilt, auch wenn es von einem öffentlichen Fork ausgelöst wird. Weitere Informationen findest du unter Ereignisse zum Auslösen von Workflows. - 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. - Die Ausführung von Workflows, die von Dependabot-Pull Requests ausgelöst werden, erfolgt wie bei einem geforkten Repository und nutzt dementsprechend ein schreibgeschütztes
GITHUB_TOKEN
. Diese Workflowausführungen können nicht auf Geheimnisse zugreifen. Informationen zu Strategien zum Schützen dieser Workflows findest du unter „Sicherheitshärtung für GitHub Actions“.
Ä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.
Hinweis: Organization-Besitzer*innen können verhindern, dass Ihnen Schreibzugriff auf die GITHUB_TOKEN
auf Repositoryebene gewährt wird. Weitere Informationen finden Sie unter „GitHub Actions für deine Organisation Deaktivieren oder Einschränken.“
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.