Authentication in a workflow

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

GitHub Actions ist verfügbar mit GitHub Free, GitHub Pro, GitHub Free für Organisationen, GitHub Team, GitHub Enterprise Cloud, und GitHub AE. GitHub Actions ist nicht verfügbar für private Repositorys, die im Besitz von Konten mit älteren Pro-Repository-Plänen sind. For more information, see "GitHub's products."

Informationen zum GITHUB_TOKEN-Geheimnis

GitHub erstellt automatisch ein GITHUB_TOKEN-Geheimnis für Deinen Workflow. Du kannst den GITHUB_TOKEN verwenden, um Dich in einem Workflow zu authentifizieren.

Wenn Du GitHub Actions aktivierst, installiert GitHub eine GitHub App in Deinem Repository. Das GITHUB_TOKEN-Geheimnis ist ein GitHub App-Token für Installations-Zugriff. 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."

Before each job begins, GitHub fetches an installation access token for the job. Das Token läuft ab, wenn der Auftrag abgeschlossen ist.

Das Token ist auch im github.token-Kontext verfügbar. Weitere Informationen findest Du unter "Kontext- und Ausdrucks-Syntax für GitHub Actions".

Das GITHUB_TOKEN in einem Workflow verwenden

You can use the GITHUB_TOKEN by using the standard syntax for referencing secrets: ${{ secrets.GITHUB_TOKEN }}. Examples of using the GITHUB_TOKEN include passing the token as an input to an action, or using it to make an authenticated GitHub API request.

Important: An action can access the GITHUB_TOKEN through the github.token context even if the workflow does not explicitly pass the GITHUB_TOKEN to the action. As a good security practice, you should always make sure that actions only have the minimum access they require by limiting the permissions granted to the GITHUB_TOKEN. Weitere Informationen findest Du unter "Berechtigungen für das GITHUB_TOKEN."

Wenn Du den GITHUB_TOKEN des Repository verwendest, um Aufgaben im Auftrag der GitHub Actions App auszuführen, werden die vom GITHUB_TOKEN ausgelösten Ereignisse keine neue Workflow-Ausführung bereitstellen. Dadurch wird verhindert, dass Du versehentlich rekursive Workflow-Ausführung erstellst. Wenn z. B. eine Workflow-Ausführung Code mit dem GITHUB_TOKEN des Repository pusht, wird kein neuer Workflow ausgeführt, auch wenn das Repository einen Workflow enthält, welcher konfiguriert ist zur Ausführung wenn push Ereignisse auftreten.

Example 1: passing the GITHUB_TOKEN as an input

Dieser Beispielworkflow verwendet die Labeler-Aktion, wofür das GITHUB_TOKEN als Wert für den Eingabeparameter repo-token benötigt wird:

name: Pull request labeler

on: [ pull_request_target ]

permissions:
  contents: read
  pull-requests: write

jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/labeler@v2
        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}

Example 2: calling the REST API

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

name: Create issue on commit

on: [ push ]

jobs:
  create_commit:
    runs-on: ubuntu-latest 
    permissions:
      issues: write 
    steps:
      - name: Create issue using REST API
        run: 
          curl --request POST \
          --url https://api.github.com/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 Der Commit-Hash lautete: _'{{ github.sha }}_."
            }' \
          --fail

Berechtigungen für das GITHUB_TOKEN

For information about the API endpoints GitHub Apps can access with each permission, see "GitHub App Permissions."

The following table shows the permissions granted to the GITHUB_TOKEN by default. People with admin permissions to an enterprise, organization, or repository can set the default permissions to be either permissive or restricted. For information on how to set the default permissions for the GITHUB_TOKEN for your enterprise, organization, or repository, see "Enforcing GitHub Actions policies in your enterprise account," "Disabling or limiting GitHub Actions for your organization," or "Disabling or limiting GitHub Actions for a repository."

ScopeDefault access
(permissive)
Default access
(restricted)
Maximum access
by forked repos
actionsLesen/SchreibennoneLesen
checks (Prüfungen)Lesen/SchreibennoneLesen
contents (Inhalte)Lesen/SchreibenLesenLesen
deploymentsLesen/SchreibennoneLesen
Issues (Lieferungen)Lesen/SchreibennoneLesen
MetadatenLesenLesenLesen
PaketeLesen/SchreibennoneLesen
pull requestsLesen/SchreibennoneLesen
repository projectsLesen/SchreibennoneLesen
security eventsLesen/SchreibennoneLesen
statuses (Statusangaben)Lesen/SchreibennoneLesen

Note: Workflow runs triggered by Dependabot pull requests run as if they are from a forked repository, and therefore use a read-only GITHUB_TOKEN. These workflow runs cannot access any secrets. See "Keeping your GitHub Actions and workflows secure: Preventing pwn requests" for strategies to keep these workflows secure.

Modifying the permissions for the GITHUB_TOKEN

You can modify the permissions for the GITHUB_TOKEN in individual workflow files. If the default permissions for the GITHUB_TOKEN are restrictive, you may have to elevate the permissions to allow some actions and commands to run successfully. If the default permissions are permissive, you can edit the workflow file to remove some permissions from the GITHUB_TOKEN. As a good security practice, you should grant the GITHUB_TOKEN the least required access.

You can see the permissions that GITHUB_TOKEN had for a specific job in the "Set up job" section of the workflow run log. For more information, see "Using workflow run logs."

You can use the permissions key in your workflow file to modify permissions for the GITHUB_TOKEN for an entire workflow or for individual jobs. This allows you to configure the minimum required permissions for a workflow or job. When the permissions key is used, all unspecified permissions are set to no access, with the exception of the metadata scope, which always gets read access.

You can use the permissions key to add and remove read permissions for forked repositories, but typically you can't grant write access. The exception to this behavior is where an admin user has selected the Send write tokens to workflows from pull requests option in the GitHub Actions settings. For more information, see "Disabling or limiting GitHub Actions for a repository."

The two workflow examples earlier in this article show the permissions key being used at the workflow level, and at the job level. In Example 1 the two permissions are specified for the entire workflow. In Example 2 write access is granted for one scope for a single job.

For full details of the permissions key, see "Workflow syntax for GitHub Actions."

How the permissions are calculated for a workflow job

The permissions for the GITHUB_TOKEN are initially set to the default setting for the enterprise, organization, or repository. If the default is set to the restricted permissions at any of these levels then this will apply to the relevant repositories. For example, if you choose the restricted default at the organization level then all repositories in that organization will use the restricted permissions as the default. The permissions are then adjusted based on any configuration within the workflow file, first at the workflow level and then at the job level. Finally, if the workflow was triggered by a pull request from a forked repository, and the Send write tokens to workflows from pull requests setting is not selected, the permissions are adjusted to change any write permissions to read only.

Granting additional permissions

Wenn Du ein Token benötigst, für das Berechtigungen erforderlich sind, die nicht im GITHUB_TOKEN-Geheimnis vorhanden sind, kannst Du ein persönliches Zugangstoken erstellen und als Geheimnis im Repository festlegen:

  1. Verwende oder erstelle ein Token mit den entsprechenden Berechtigungen für dieses Repository. Weitere Informationen finden Sie unter "Erstellen eines persönlichen Zugriffstokens."
  2. Füge das Token als Geheimnis in das Repository Deines Workflows ein, und verweise darauf mit der Syntax ${{ secrets.SECRET_NAME }}. Weitere Informationen findest Du unter "Verschlüsselte Geheimnisse erstellen und verwenden".

Did this doc help you?Privacy policy

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

Oder, learn how to contribute.