Verwenden von GITHUB_TOKEN für die Authentifizierung in Workflows

Erfahre, wie du das GITHUB_TOKEN für die Authentifizierung im Auftrag von GitHub Actions verwendest.

In diesem Artikel

Dieses Tutorial führt dich durch die Verwendung von GITHUB_TOKEN für die Authentifizierung in GitHub Actions-Workflows, einschließlich Beispielen zum Übergeben des Tokens an Aktionen, zum Erstellen von API-Anforderungen und zum Konfigurieren von Berechtigungen für die sichere Automatisierung.

Referenzinformationen findest du unter Workflowsyntax für GitHub Actions.

Verwenden des GITHUB_TOKEN in einem Workflow

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

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 finden Sie unter Workflowsyntax für GitHub Actions.

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:

YAML
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

Ändern der Berechtigungen für das GITHUB_TOKEN

Verwende den permissions-Schlüssel in deiner Workflowdatei, 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. Als bewährte Sicherheitsmethode sollten Sie dem GITHUB_TOKEN nur den geringsten erforderlichen Zugriff gewähren.

Eine Liste der verfügbaren Berechtigungen und deren parametrisierte Namen findest du unter Verwalten deiner persönlichen Zugriffstoken.

Die beiden zuvor in diesem Artikel beschriebenen Workflowbeispiele zeigen, wie der permissions-Schlüssel auf Auftragsebene verwendet wird.

Erteilen zusätzlicher Berechtigungen

Wenn du ein Token benötigst, das Berechtigungen erfordert, die im GITHUB_TOKEN nicht verfügbar sind, erstelle eine GitHub App und generiere ein Installationszugriffstoken in deinem Workflow. Weitere Informationen finden Sie 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 findest du unter Verwalten deiner persönlichen Zugriffstoken und Verwenden von Geheimnissen in GitHub-Aktionen.

Nächste Schritte