Fix GitHub Workflow File Push Permission Errors

DEV Community

Refusing to allow a GitHub App to create or update workflow files

The message refusing to allow a GitHub App to create or update workflow files comes from GitHub's git server during a push, not from Actions, and it names a grant that is deliberately separate from repository write access. Which grant depends on what pushed: an App installation needs a repository permission, and an OAuth token needs a scope with a different name. Three identities, three names for the same privilege, and one of them cannot be granted from a workflow file at all. What this error means A push is rejected and nothing else about the branch is unusual. The same token pushed every other file in the same commit range without complaint, and the only difference in the failing change is that it touches something under .github/workflows. The rejection is printed by git, so it appears in a bot's log in the middle of a checkout or push step rather than in any Actions annotation, and the branch simply does not appear on GitHub. `Quoted from Fragment256/githatch#60, a push rejection reported verbatim ! [remote rejected] ci/fix -> ci/fix (refusing to allow a GitHub App to create or update workflow.github/workflows/ci.ymlwithoutworkflows permission)

Common causes

The App installation does not hold the Workflows permission

The commonest cause for bot pushes. An app configured for contents and pull requests can do everything else it needs and is refused on any push that touches .github/workflows, because the workflow file privilege is a separate repository permission.

A personal access token is missing the workflow scope

Classic tokens list workflow as its own checkbox, separate from repo. A token created for general automation usually does not have it, and the failure only appears the first time the automation edits a workflow rather than when the token was created.

The push is using the token the workflow run was given

That token cannot be granted this privilege at all. There is no key for it in the permissions block, so no amount of editing the workflow will help, and contents: write is not a substitute.

The grant was added but the installation was never re-approved

A new repository permission on an existing GitHub App installation has to be accepted before it takes effect. In our experience this is the version that produces the longest debugging session, because the app's settings page shows the permission the whole time.

How to fix it

Read the rejection and identify which grant it named

1. Look for the words GitHub App or OAuth App in the message.
2. A GitHub App means the workflows repository permission on the app.
3. An OAuth App means the workflow scope on the token.
4. Then confirm the grant on the credential in hand rather than on the settings page you edited.

Push with an App installation token that holds Workflows

Mint a short-lived installation token in the job and hand it to checkout, so the push is authenticated as the app rather than as the run. Keep the app's permission set minimal and add Workflows only to the installation that needs it.

```.github/workflows/sync.yml (illustrative)
- uses: actions/checkout@v7
with:
token: ${{ steps.app-token.outputs.token }}
persist-credentials: true
Re-approve the installation after changing permissions Adding a permission to an app does not update installations that already exist. Accept the new permission for the installation on the organization or account, then mint a fresh token, because a token issued before the acceptance carries the old set. Split the change when only part of it touches a workflow If a bot generates both code and workflow files, let it push the code with the credential it already has and open a pull request for the workflow change, or keep the workflow file identical to one already on another branch. The scopes reference records that an identical file at the same path on another branch may be committed without the scope, which is a narrow exemption but occasionally the cheapest rou...

Powered by Readybot.io