Skip to content

MissingGhToken

GH_TOKEN is required for using the gh CLI tool.

Defined by MissingGhTokenRule which supports workflows, actions in the "Default" ruleset along with MissingGhHost.

Description

Using the gh CLI tool requires a GitHub token to be set.

GitHub CLI is preinstalled on all GitHub-hosted runners. For each step that uses GitHub CLI, you must set an environment variable called GH_TOKEN to a token with the required scopes. -- Using GitHub CLI in workflows

Usually this token will be: 

env:
  GH_TOKEN: ${{ github.token }}
and the "required scopes" can be defined in the permissions: field of the job.

Note: for GitHub Enterprise users, the token is named GH_ENTERPRISE_TOKEN, and it also requires GH_HOST to be set at the same time, see MissingGhHost.

References:

Note: it's possible to set both GH_TOKEN and GITHUB_TOKEN as environment variables, but to reduce confusion between

  • GITHUB_TOKEN environment variables used by gh CLI
  • GITHUB_TOKEN secret automatically defined by GitHub Actions

it's recommended to always use GH_TOKEN and ${{ github.token }}, see PreferGitHubToken.

Using the GH_ prefix also helps to understand that the variable is for the gh CLI.

Compliant examples

Compliant example #1

GH_TOKEN is defined.

example.yml 

on: push
jobs:
  example:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: gh pr list
        env:
          GH_TOKEN: ${{ github.token }}

Compliant example #2

GH_ENTERPRISE_TOKEN is defined.

example.yml 

on: push
jobs:
  example:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: gh pr list
        env:
          GH_ENTERPRISE_TOKEN: ${{ github.token }}
          GH_HOST: github.example.com

Compliant example #3

GH_TOKEN is defined.

action.yml 

name: Test
description: Test
inputs:
  token:
    description: 'GitHub token to authenticate to GitHub APIs.'
    default: ${{ github.token }}
runs:
  using: composite
  steps:
    - run: gh pr list
      shell: bash
      env:
        GH_TOKEN: ${{ inputs.token }}

Non-compliant example

GH_TOKEN is not defined, command will fail with: 

gh: To use GitHub CLI in a GitHub Actions workflow, set the GH_TOKEN environment variable. Example:
  env:
    GH_TOKEN: ${{ github.token }}
Error: Process completed with exit code 4.

example.yml 

on: push
jobs:
  example:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: gh pr list

  • Line 7: Step[#1] in Job[example] should see GH_TOKEN environment variable.