PreferGitHubToken

Prefer github.token instead of secrets.GITHUB_TOKEN.

Defined by PreferGitHubTokenRule which supports workflows, actions in the "Default" ruleset.

Description

Mixing built-in GITHUB_TOKEN with repository/org-level secrets is confusing.

Whenever the secrets context is used, the reference is expected to be defined in Settings > Security > Secrets and variables > Actions; except, when it's about GITHUB_TOKEN.

GITHUB_TOKEN is very special in several aspects, a few more examples:

• It's passed to forked workflow runs.
• It's accessible in actions, even when not passed in.
• Actions don't have access to the secrets context, but they can access github.token.

To clarify this special case to the reader, it's recommended to use github.token instead of secrets.GITHUB_TOKEN everywhere.

This will make the usages of github.token consistent across workflows and actions, resulting in better maintainability due to easier copy-paste-ability between them.

In case of gh CLI, this preference will also help disambiguate between

• GH_TOKEN environment variable and GITHUB_TOKEN secret.
• GITHUB_TOKEN environment variable and GITHUB_TOKEN secret.

See gh environment for more details.

Compliant example

github.token is used.

example.yml

on: push
jobs:
  example:
    runs-on: ubuntu-latest
    steps:
      - run: gh pr view
        env:
          GH_TOKEN: ${{ github.token }}

Non-compliant example

secrets.GITHUB_TOKEN is used.

example.yml

on: push
jobs:
  example:
    runs-on: ubuntu-latest
    steps:
      - run: gh pr view
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

• Line 6: GH_TOKEN environment variable in Step[#0] in Job[example] should use github.token in ${{ secrets.GITHUB_TOKEN }}.