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

Not specified by the original author.

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.

Not specified by the original author.

TL;DR: Regenerate your personal access token with the workflow scope checked, then push again with the new token. GitHub refuses to let any OAuth token touch files under .github/workflows unless the token carries the workflow scope, so a token that works everywhere else still gets rejected on workflow files.

refusing to allow an OAuth App to create or update workflow

The fix

1. Create a new token with the workflow scope. For a classic PAT, tick the workflow checkbox. For a fine-grained PAT, grant Actions read and write on the repo. Expected: The token summary lists the workflow scope.

2. Clear the cached credential so git asks for the new token on the next push, then paste the new token when prompted.

   printf 'protocol=https\nhost=github.com\n' | git credential reject

   Expected: The next git push prompts for a username and password; the push completes.

3. Push again.

   git push origin main

   Expected: The push completes instead of the refusing error.

When this applies

• git push over HTTPS fails only when the push includes .github/workflows files
• you authenticate with a personal access token or OAuth app token

When it does NOT apply

• the push has no workflow files (then it is a different auth problem)
• you push over SSH (scopes do not apply there)

Compatibility

GitHub.com and GitHub Enterprise Server. Applies to PAT classic, fine-grained PATs, and OAuth app tokens used for git over HTTPS.

Variants of this error

refusing to allow an OAuth App to create or update workflow without workflow scope

Same error with the missing scope named. Same fix: reissue the token with that scope.

Why it happens

Workflow files can execute arbitrary code with access to repository secrets, so GitHub treats them as privileged. The workflow scope is a separate opt-in so a compromised token cannot silently install a secret-stealing workflow.

Edge cases and pitfalls

• If a CI system or password manager holds the old token, rotate it there too or the next push fails the same way.
• Fine-grained PATs do not have a checkbox literally named workflow; use Actions read and write permissions.
• Inside Actions itself, GITHUB_TOKEN already has workflow-file access in its own repo; this error is about pushing from your machine.

Asked on Stack Overflow: pushing a new workflow file fails with refusing to allow an OAuth App to create or update workflow, and the asker wants to know how to grant the workflow scope. The verified fix is to reissue the personal access token with the workflow scope enabled and push with the new token. Source: https://stackoverflow.com/questions/64059610/how-to-resolve-refusing-to-allow-an-oauth-app-to-create-or-update-workflow-on

Not specified by the original author.

TL;DR

Pick by who is acting: - Software acting on its own (a bot, an integration, an agent fleet): a GitHub App, installed on the repos it needs, with fine-grained permissions. - A user signing into your app through GitHub: an OAuth app. - Personal automation for one human: a fine-grained personal access token.

Steps

1. GitHub's docs are explicit that GitHub Apps are preferred over OAuth apps. Pick by who is acting:

• Software acting on its own (a bot, an integration, an agent fleet): a GitHub App, installed on the repos it needs, with fine-grained permissions.
• A user signing into your app through GitHub: an OAuth app.
• Personal automation for one human: a fine-grained personal access token.

2. An App gets short-lived installation tokens scoped to exactly the repositories it is installed on, with only the permissions it requested. There is no long-lived user credential to steal, and uninstalling revokes everything at once. An OAuth app or personal token inherits the user's access, which is almost always broader than the integration needs, and it lives until someone revokes it.
3. - If an integration currently runs on a personal access token belonging to an employee, migrate it to a GitHub App. When that employee leaves, the token story gets ugly.

• Review installed Apps and their permissions the way you review team membership. Unused installs get removed.

When to use

You are seeing this: GitHub's docs are explicit that GitHub Apps are preferred over OAuth apps. Use this skill when you run into "GitHub Apps over OAuth apps and PATs for integrations".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

An App gets short-lived installation tokens scoped to exactly the repositories it is installed on, with only the permissions it requested.

GitHub's docs state that GitHub Apps are preferred over OAuth apps, with both using OAuth-style authorization but Apps offering fine-grained permissions. Source: https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/deciding-when-to-build-a-github-app