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

By Daniel Zoghalchali·Latchkey

Pushing changes to files under .github/workflows requires the workflows permission. The default GITHUB_TOKEN and many app/PAT scopes cannot create or update workflow files without it.

What this error means

A push that touches a workflow file is rejected with a message about refusing to allow a GitHub App (or token without workflow scope) to update workflows.

! [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 permission

GITHUB_TOKEN and many tokens cannot modify workflow files by default.

PAT missing the workflow scope

A classic PAT needs the workflow scope to push workflow changes.

How to fix it

Use a token with workflow permission

1. For a PAT, include the workflow scope.
2. For a GitHub App, grant the Workflows write permission and re-install.
3. Use that token for the checkout/push that edits workflow files.

- uses: actions/checkout@v4
  with:
    token: ${{ secrets.WORKFLOW_PAT }}   # PAT with 'workflow' scope

How to prevent it

• Use a workflow-scoped token specifically for automation that edits workflows.
• Keep app permissions least-privilege but include Workflows write where required.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions