Authenticating with the GITHUB_TOKEN

GitHub provides a token that you can use to authenticate on behalf of GitHub Actions.

GitHub Actions is available with GitHub Free, GitHub Pro, GitHub Team, and GitHub Enterprise Cloud. For more information, see "GitHub's products."

Anyone with write access to a repository can create, read, and use secrets.

In this article

About the GITHUB_TOKEN secret

GitHub automatically creates a GITHUB_TOKEN secret to use in your workflow. You can use the GITHUB_TOKEN to authenticate in a workflow run.

When you enable GitHub Actions, GitHub installs a GitHub App on your repository. The GITHUB_TOKEN secret is a GitHub App installation access token. You can use the installation access token to authenticate on behalf of the GitHub App installed on your repository. The token's permissions are limited to the repository that contains your workflow. For more information, see "Permissions for the GITHUB_TOKEN."

The installation access token expires after 60 minutes. GitHub fetches a token for each job, before the job begins.

Note: When a workflow run or its jobs are queued for more than one hour, the token may expire before the job starts.

Using the GITHUB_TOKEN in a workflow

To use the GITHUB_TOKEN secret, you must add it to your workflow file. Using a token might include passing the token as an input to an action that requires it, or making authenticated GitHub API calls.

Example passing GITHUB_TOKEN as an input

This example workflow uses the labeler action, which requires the GITHUB_TOKEN as the value for the repo-token input parameter:

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

Example 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_commit:
    runs-on: ubuntu-latest
    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 The commit hash was: _${{ github.sha }}_."
          }'

Permissions for the GITHUB_TOKEN

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

Permission Access type Access by forked repos
checks read/write read
contents read/write read
deployments read/write read
issues read/write read
metadata read read
packages read/write read
pull requests read/write read
repository projects read/write read
statuses read/write read

If you need a token that requires permissions that aren't available in the GITHUB_TOKEN, you can create a personal access token and set it as a secret in your repository:

  1. Use or create a token with the appropriate permissions for that repository. For more information, see "Creating a personal access token for the command line."
  2. Add the token as a secret in your workflow's repository, and refer to it using the ${{ secrets.SECRET_NAME }} syntax. For more information, see "Creating and using encrypted secrets."

Ask a human

Can't find what you're looking for?

Contact us