## 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
```text
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:
```yaml
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