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

By Daniel Zoghalchali·Latchkey

A push that touches .github/workflows was rejected because the GITHUB_TOKEN or App installation lacks the workflows write permission. Retrying will not help.

What this error means

A git push from a workflow fails with a message that the App is refused permission to create or update workflow files.

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

Common causes

Token lacks workflows scope

The default GITHUB_TOKEN cannot modify workflow files; this requires the workflows permission an App may not have.

Pushing workflow changes from CI

Any automated change to files under .github/workflows is gated behind the workflows permission.

How to fix it

Use a token with the workflows permission

1. Use a PAT or App installation token that has the workflows permission.
2. Or exclude workflow file changes from automated pushes.

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

How to prevent it

• Keep automated commits out of .github/workflows when possible.
• Provision a dedicated token with the workflows permission for that use case.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions