GITHUB_TOKEN "refusing to allow a GitHub App to create or update workflow" in CI

GITHUB_TOKEN cannot push changes to files under .github/workflows/ unless it has the workflows permission, which GITHUB_TOKEN cannot be granted. A push that touches a workflow file is refused with this message.

What this error means

A push or PR-creation step fails with "refusing to allow a GitHub App to create or update workflow .github/workflows/ci.yml without workflows permission".

Terminal

! [remote rejected] HEAD -> main (refusing to allow a GitHub App to create
or update workflow `.github/workflows/ci.yml` without `workflows` permission)

Common causes

The push modifies a workflow file

Any change under .github/workflows/ requires the workflows permission, which is not available to GITHUB_TOKEN.

An automated tool edits workflows

A formatter, codegen, or bot commits changes that include a workflow file, triggering the refusal.

How to fix it

Use a PAT or GitHub App token with workflows scope

Create a fine-grained PAT or app installation token with the Workflows write permission.
Pass it to the checkout/push step instead of GITHUB_TOKEN.
Re-run; the token with workflows scope can update the file.

.github/workflows/ci.yml

- uses: actions/checkout@v4
  with:
    token: ${{ secrets.WORKFLOW_PAT }}

Exclude workflow files from the automated change

If the edit to a workflow file is unintended, scope the tool or commit to leave .github/workflows/ untouched.

How to prevent it

Use a PAT/app token with Workflows write to change workflow files.
Avoid committing workflow edits with GITHUB_TOKEN.
Scope auto-formatters to skip .github/workflows/ when using GITHUB_TOKEN.