GitHub Actions "refusing to allow a GitHub App to create or update workflow"

A GitHub App token (including the default GITHUB_TOKEN) tried to push a change under .github/workflows, but it lacks the dedicated workflows permission, so GitHub blocks the push to protect against self-modifying CI.

What this error means

A git push from a job fails with "refusing to allow a GitHub App ... to create or update workflow .github/workflows/x.yml without workflows permission", even though other file pushes succeed.

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

Common causes

GITHUB_TOKEN cannot edit workflow files

The built-in token deliberately cannot create or modify files under .github/workflows. This prevents a workflow from rewriting its own CI.

App installation missing the workflows permission

A GitHub App token can push workflow changes only if the App was granted the Workflows write permission. Without it, the push is rejected.

How to fix it

Use a token with the workflows permission

Push workflow-file changes with a PAT or GitHub App token that has the Workflows write permission, not the default GITHUB_TOKEN.

- uses: actions/checkout@v4
  with:
    token: ${{ secrets.WORKFLOWS_PAT }}   # PAT with workflow scope
- run: |
    git add .github/workflows
    git commit -m "update ci" && git push

Grant the App the right permission

1. For a GitHub App, add the Workflows: Read and write permission and re-approve the installation.
2. For a classic PAT, include the workflow scope.
3. Avoid pushing workflow changes from CI unless you genuinely need self-updating workflows.

How to prevent it

• Do not rely on GITHUB_TOKEN to modify .github/workflows.
• Use a scoped PAT or App token with the workflows permission for those pushes.
• Keep workflow edits in human PRs where possible.

Related guides