This tutorial leads you through how to use theGITHUB_TOKEN for authentication in GitHub Actions workflows, including examples for passing the token to actions, making API requests, and configuring permissions for secure automation.

For reference information, seeWorkflow syntax for GitHub Actions.

Using theGITHUB_TOKEN in a workflow

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

Example 1: passing theGITHUB_TOKEN as an input

This example workflow uses theGitHub CLI, which requires theGITHUB_TOKEN as the value for theGH_TOKEN input parameter:

name: Open new issueon: workflow_dispatchjobs:  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:Opennewissueon:workflow_dispatchjobs:open-issue:runs-on:ubuntu-latestpermissions:contents:readissues:writesteps:-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 theGITHUB_TOKEN to make authenticated API calls. This example workflow creates an issue using the GitHub REST API:

name:Createissueoncommiton: [push ]jobs:create_issue:runs-on:ubuntu-latestpermissions:issues:writesteps:-name:CreateissueusingRESTAPIrun:|          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 The commit hash was: _${{ github.sha }}_."            }' \          --fail

Modifying the permissions for theGITHUB_TOKEN

Use thepermissions key in your workflow file to modify permissions for theGITHUB_TOKEN for an entire workflow or for individual jobs. This allows you to configure the minimum required permissions for a workflow or job. As a good security practice, you should grant theGITHUB_TOKEN the least required access.

The two workflow examples earlier in this article show thepermissions key being used at the job level.

Granting additional permissions

If you need a token that requires permissions that aren't available in theGITHUB_TOKEN, create a GitHub App and generate an installation access token within your workflow. For more information, seeMaking authenticated API requests with a GitHub App in a 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, seeManaging your personal access tokens andUsing secrets in GitHub Actions.

Next steps

• GITHUB_TOKEN
• Workflow syntax for GitHub Actions