GitHub Actions "refusing to allow a GitHub App to create or update workflow"
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)Diagnose it: print the context before you change anything
Most workflow-expression bugs are not syntax errors, they are an expression reading something that is empty. GitHub resolves a missing property to an empty string instead of failing the run, so a wrong reference looks like a logic bug rather than a mistake. Dump the contexts first and you will usually see the answer immediately.
- name: Dump contexts
run: |
echo '--- github ---' ; echo '${{ toJSON(github) }}'
echo '--- needs ---' ; echo '${{ toJSON(needs) }}'
echo '--- steps ---' ; echo '${{ toJSON(steps) }}'
echo '--- matrix ---' ; echo '${{ toJSON(matrix) }}'
echo '--- inputs ---' ; echo '${{ toJSON(inputs) }}'Check the context is allowed where you used it
Contexts are not available everywhere. The same expression can be valid in a step if and invalid in a job if, which is why an expression that works in one workflow fails when moved.
| Where you wrote it | Contexts available there |
|---|---|
run-name | github, inputs, vars |
concurrency | github, inputs, vars |
Top-level env | github, secrets, inputs, vars |
jobs.<id>.if | github, needs, vars, inputs |
jobs.<id>.steps.if | github, needs, strategy, matrix, job, runner, env, vars, steps, inputs |
jobs.<id>.outputs | Full access, including secrets |
Reusable workflow outputs | github, jobs, vars, inputs |
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
- For a PAT, include the workflow scope.
- For a GitHub App, grant the Workflows write permission and re-install.
- Use that token for the checkout/push that edits workflow files.
- uses: actions/checkout@v4
with:
token: ${{ secrets.WORKFLOW_PAT }} # PAT with 'workflow' scopeCatch it before it reaches CI
Every failure in this cluster is statically detectable. actionlint parses workflow expressions, checks context availability against the same rules above, and validates needs references, so these bugs never need to cost you a run.
# one-off
docker run --rm -v "$(pwd):/repo" --workdir /repo rhysd/actionlint:latest -color
# as a job, before anything expensive runs
- uses: actions/checkout@v4
- run: |
bash <(curl -s https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)
./actionlint -colorHow 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.