ncipollo/release-action "missing token" / 401 on release create

By Kaveh Alemi·Latchkey

ncipollo/release-action needs a token to call the releases API. When none is passed and the environment has none, the action errors before contacting GitHub.

What this error means

A release step using ncipollo/release-action fails with "missing token" or a 401 from the API.

Error: missing token
##[error]Error: missing token

Diagnose it: what token do you actually have?

Permission failures in Actions are almost never about your repository settings alone. Three things combine: the default GITHUB_TOKEN permission set for the repo or organization, the permissions: block in the workflow, and whether the event is a fork pull request, which downgrades the token to read-only regardless of everything else.

- name: Show the token scopes actually granted
  run: |
    curl -sI -H "Authorization: Bearer $GITHUB_TOKEN" \
      https://api.github.com/ | grep -i "^x-oauth-scopes\|^x-accepted"
    echo "event: ${{ github.event_name }}"
    echo "fork PR: ${{ github.event.pull_request.head.repo.fork }}"
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Common causes

No token input and no env token

The action could not find a token via the token input or GITHUB_TOKEN in the environment.

Token expired on a long job

A custom PAT expired before the release step ran, surfacing as an auth failure.

How to fix it

Pass the GITHUB_TOKEN to the action

1. Set the token input to secrets.GITHUB_TOKEN.
2. Grant contents: write so the token can create releases.
3. Re-run the workflow.

permissions:
  contents: write
steps:
  - uses: ncipollo/release-action@v1
    with:
      token: ${{ secrets.GITHUB_TOKEN }}
      tag: ${{ github.ref_name }}

Grant the narrowest permission that works

Declaring a permissions: block switches the job from the repository default to exactly what you list, so an incomplete block is a common cause of a new failure right after someone tightened security. List every scope the job needs, not just the one that failed.

permissions:
  contents: read        # checkout
  packages: write       # push to GHCR
  id-token: write       # OIDC to a cloud provider
  pull-requests: write  # comment on or label a PR
  checks: write         # publish check runs

How to prevent it

• Always pass token explicitly to release actions; defaults vary by action version.
• Use GITHUB_TOKEN over a PAT unless cross-repo release is required.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions