skip to content

In a nightly GitHub Actions workflow that runs the GitHub CLI to open issues across an organisation, how does gh get its token and what bounds it?

level: seniorimportance: should knowfreq 22%

answer

  1. a runner has no stored login
  2. the env line gh itself suggests
  3. permissions bound only that token
  4. one repository's reach
  5. no clone, no placeholders

basics

~20 s

gh on a runner has no login, so the step sets GH_TOKEN, usually from github.token. The workflow's permissions block bounds that token, and it only reaches the workflow's own repository, so organisation-wide writes need a different token.

solid answer

~50 s

A runner has no stored gh login, and gh does not read the Actions token by itself; when it finds no credentials inside Actions it says so and suggests `GH_TOKEN: ${{ github.token }}` in the step's `env`. That token is the job's `GITHUB_TOKEN`: the workflow's `permissions` block (for example `contents: read`, `issues: write`) sets what gh can change, and the token's permissions are limited to the repository that contains the workflow. So a nightly job that walks the whole organisation sees only what that token can see (other private repositories are missing from listings or return 404), and opening issues elsewhere is refused. For organisation-wide work the step passes a token with that reach, typically a GitHub App installation token, in `GH_TOKEN`; the `permissions` block does not bound that one. Without `actions/checkout` there is no local repository either, so `{owner}`/`{repo}` need `GH_REPO` or explicit paths.

code

bash · 14 lines
bash
# Workflow step script; the step's env sets GH_TOKEN (an org-wide token) and GH_REPO
set -euo pipefail
gh api --paginate orgs/acme/repos --jq '.[] | select(.archived | not) | .name' |
while read -r repo; do
  rulesets=$(gh api "repos/acme/$repo/rulesets" --jq 'length')
  if [ "$rulesets" -eq 0 ]; then
    open=$(gh api -X GET "repos/acme/$repo/issues" \
      -f labels=governance -f state=open --jq 'length')
    if [ "$open" -eq 0 ]; then
      gh api "repos/acme/$repo/issues" --silent \
        -f title='No branch ruleset' -f 'labels[]=governance'
    fi
  fi
done

go deeper

for a junior

Recall that gh in a workflow needs GH_TOKEN in the step's environment, normally set from github.token.

for a middle

Explain that the permissions block bounds what that token can change and that GH_REPO replaces the missing checkout for placeholders.

for a senior

Show the cross-repository trap: github.token reaches only its own repository, so org-wide listings shrink silently and writes elsewhere fail, which calls for an organisation-wide token plus idempotent writes.

for a principal

Decide where org-wide automation should live and which identity it runs as, balancing a dedicated app's reach against the blast radius of one nightly script.

## The scenario A platform engineer schedules a workflow that, every night, lists every repository in the `acme` organisation, finds the ones with no ruleset and opens an issue in each, without opening a duplicate the next night. The script is a handful of `gh api` calls. The interesting part is not the jq, it is **which token gh uses and what that token may do**. ## How gh authenticates on a runner - A hosted runner starts clean: there is no `gh auth login` state on it. - gh reads a token from its environment variables (the precedence rules between `GH_TOKEN` and `GITHUB_TOKEN` belong to the material on gh authentication). The Actions token is not exported into a step's environment automatically. - When a command needs authentication inside Actions and finds none, gh prints: "To use GitHub CLI in a GitHub Actions workflow, set the GH_TOKEN environment variable", with the example `GH_TOKEN: ${{ github.token }}`, and exits with status 4. So the step's `env` carries `GH_TOKEN: ${{ github.token }}` and, when no checkout happens, `GH_REPO: ${{ github.repository }}`. ## What bounds that token The token behind `github.token` is the job's `GITHUB_TOKEN`, an installation token of the GitHub App that Actions installs on the repository. Two limits apply to everything gh does with it: 1. **The `permissions` block.** Listing `contents: read` and `issues: write` gives gh exactly those; once any permission is listed, the unlisted ones are not granted. How the block works in detail belongs to the material on Actions secrets and permissions. 2. **One repository.** GitHub's documentation is explicit that the token's permissions are limited to the repository that contains the workflow. | What the nightly job does | With `github.token` | With an organisation-wide token | |---|---|---| | List `orgs/acme/repos` | Only repositories the token can see; other private ones are silently missing | Every repository the token was granted | | Read another repository's rulesets | Fails with 404 for private ones | Works | | Open an issue in another repository | Refused | Works if granted issue write access | | Bounded by the workflow's `permissions` | Yes | No; bounded by the token's own grant | The first row is the dangerous one: the report **succeeds with a shorter list**, and nobody notices that half the organisation was never checked. The fix is a token with organisation reach, usually a GitHub App installation token minted in an earlier step and stored only in that step's `GH_TOKEN`; which token type to choose belongs to the material on GitHub tokens. ## Repository context without a checkout A job that never runs `actions/checkout` has no Git remote to infer from. Paths using `{owner}` or `{repo}`, and subcommands that operate on "the current repository", need `GH_REPO` set or explicit `acme/name` paths. The `{branch}` placeholder cannot be used at all while `GH_REPO` is set; gh refuses to guess it. ## Reading the failures | Symptom in the job log | Likely cause | Fix | |---|---|---| | gh asks to set the `GH_TOKEN` environment variable and exits with status 4 | No token in the step's environment | Add `GH_TOKEN` to the step's `env` | | `HTTP 404` reading another private repository | The token cannot see that repository | Use a token with organisation reach | | `HTTP 403` creating an issue | The token lacks issue write access on that repository | Grant it in `permissions` (own repository) or in the other token's grant | | "unable to determine an appropriate value for the 'branch' placeholder" | `{branch}` used while `GH_REPO` is set | Write the branch name explicitly | | A report that is green but short | Listing with a token that sees only part of the organisation | Same as the 404 row; also print the total for a sanity check | ## Making the nightly run safe to repeat - **Idempotency.** Before creating an issue, look for an open one with the report's label; otherwise every night adds another. - **Failing loudly.** gh exits 1 when the API returns an error, so a script with `set -euo pipefail` stops at the failing call instead of reporting a partial result as complete. - **Rate limits.** gh does not pause and resend a refused request, so a script that makes one call per repository should keep calls few (GraphQL can fetch counts for 100 repositories at once) and handle back-off itself; the limits belong to the material on the GitHub API. - **Quiet output.** `--silent` drops the response body of write calls so the log shows only what the script prints.

  • The nightly report ran green but lists far fewer repositories than the organisation has. Why?
    gh was using the job's `GITHUB_TOKEN`, whose permissions are limited to the workflow's own repository. Listing the organisation returns only what that token can see, without an error. Give the step an organisation-wide token, such as a GitHub App installation token, in `GH_TOKEN`.
  • Why does gh api repos/{owner}/{repo}/issues fail in a job with no checkout step?
    The placeholders come from the local repository's remotes, and without a checkout there is none. Set `GH_REPO: ${{ github.repository }}` in the step's environment or write the owner and name into the path.
  • How do you stop the nightly job from opening a duplicate issue every night?
    Make the write conditional: before creating, query open issues with the report's label, for example `gh api -X GET repos/acme/NAME/issues -f labels=governance -f state=open --jq length`, and create only when it returns 0.

  • gh picks up the Actions token automatically on a runner
  • github.token can open issues in any repository of the organisation
  • The permissions block also limits a GitHub App token passed in GH_TOKEN
  • A shorter organisation listing would make the gh step fail
  • {owner} and {repo} work in a job without a checkout or GH_REPO