Use GITHUB_TOKEN in workflows

Using the `GITHUB_TOKEN` in a workflow

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.

Wichtig

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. For more information, see GITHUB_TOKEN reference.

Example 1: passing the `GITHUB_TOKEN` as an input

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 }}

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 }}

Example 2: calling the REST API

You can use the GITHUB_TOKEN to make authenticated API calls. This example workflow creates an issue using the 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://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 The commit hash was: _${{ github.sha }}_."
            }' \
          --fail

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 Verwenden von Workflowausführungsprotokollen.

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.

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 finden Sie unter Verwalten von GitHub Actions-Einstellungen für ein Repository.

The two workflow examples earlier in this article show the permissions key being used at the job level, as it is best practice to limit the permissions' scope.

For full details of the permissions key, see Workflowsyntax für GitHub Actions.

Hinweis

Organization and enterprise owners can prevent you from granting write access to the GITHUB_TOKEN at the repository level. For more information, see GitHub Actions für deine Organisation Deaktivieren oder Einschränken and Erzwingen von Richtlinien für GitHub Actions in deinem Unternehmen.

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.

Granting additional permissions

If you need a token that requires permissions that aren't available in the GITHUB_TOKEN, you can create a GitHub App and generate an installation access token within your workflow. For more information, see Authentifizierte API-Anforderungen mit einer GitHub-App in einem GitHub Actions-Workflow. Alternatively, you can create a personal access token, store it as a secret in your repository, and use the token in your workflow with the ${{ secrets.SECRET_NAME }} syntax. For more information, see Verwalten deiner persönlichen Zugriffstoken and Verwenden von Geheimnissen in GitHub-Aktionen.

Configuring `GITHUB_TOKEN` permissions with private repositories

Private repositories can control whether pull requests from forks can run workflows, and can configure the permissions assigned to GITHUB_TOKEN. For more information, see Verwalten von GitHub Actions-Einstellungen für ein Repository.

In diesem Artikel