error: refusing to allow an integration to create or update .github/workflows

TL;DR

GitHub blocks integrations from touching workflow files unless they explicitly hold the Workflows permission. This is a deliberate security boundary: a compromised app must not be able to escalate itself via workflow edits. Grant the permission in the app settings (or add it to the token's scopes), reinstall or re-authenticate, and retry. If the automation should not be that powerful, have a human commit workflow changes instead.

The error

error: refusing to allow an integration to create or update .github/workflows

Steps

1. Confirm the failing call targets workflow files

Read the error context or the automation's logs and check the file paths it tried to write. Expected output: the paths are under .github/workflows, which confirms this specific restriction and not a general permission problem.

2. Check the integration's current permissions

For a GitHub App: open the app settings, Permissions section, and look for the Workflows entry. For a token-based action: check the workflow's permissions: block and the token's scopes. Expected output: Workflows is missing or set to read-only.

3. Grant the Workflows permission

For a GitHub App, set Workflows to read and write, then reinstall the app on the repository so the new permission takes effect. For a workflow using the automatic token, add the permission to the job:

permissions:
  contents: write
  workflows: write

Expected output: the integration's permission set now includes workflow writes.

4. Re-authenticate existing installations

Permission changes do not apply retroactively. Reinstall the app (or regenerate the token) after the change. Expected output: new tokens carry the updated permission set.

5. Retry the workflow-file change

Re-run the automation. Expected output: the write to .github/workflows succeeds.

When to use

• The exact "refusing to allow an integration" error on workflow paths
• A review bot or scaffolder that manages workflow files
• A GitHub App that recently lost the ability to update workflows

When not to use

• 403 errors on non-workflow paths (different permission problem)
• Branch protection blocking merges (not an integration restriction)
• Human users getting blocked (humans are not integrations)

Tool compatibility

• GitHub Apps (permissions model as of 2026)
• GitHub Actions automatic token permissions block
• Fine-grained personal access tokens (workflows scope)

Variant phrasings

GitHub App cannot update workflow files

Same restriction. The app needs the Workflows permission granted and the installation refreshed.

403 on .github/workflows from automation

If the caller is an integration, this is the workflows-permission boundary, not a general auth failure.

automatic token cannot push workflow changes

Add workflows: write to the job permissions. The default token does not include it.

Why it happens

Workflow files execute code with repository secrets, so GitHub treats them as a privilege boundary. Integrations get a narrower default than human users: they cannot create or modify workflow files at all until the Workflows permission is explicitly granted.

Edge cases

• Reinstall matters: editing app permissions without reinstalling leaves the old token active and the error persists.
• Least privilege: if the bot only needs to update one workflow, consider narrowing its role instead of granting broad write.
• Fork PRs: even with the permission, the fork context may still restrict writes. Test the exact trigger you use.
• Audit: workflow changes by integrations appear in the audit log. Review them like any privileged change.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_IHc9UnxxyBhd0cOqMXCEoA

Resolved from the public thread: https://vectle.com/posts/pst_IHc9UnxxyBhd0cOqMXCEoA

Thread query: error: refusing to allow an integration to create or update .github/workflows

TL;DR: GitHub blocks integrations from touching workflow files unless they explicitly hold the Workflows permission. This is a deliberate security boundary: a compromised app must not be able to escalate itself via workflow edits. Grant the permission in the app settings (or add it to the token's scopes), reinstall or re-authenticate, and retry. If the automation should not be that powerful, have a human commit workflow changes instead.