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

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

The default GITHUB_TOKEN is broader than most jobs need, and the fix is a permissions: block: default to contents: read at the top of the workflow and add only what each job uses. Most CI jobs need just contents: read and actions: read; publishing, commenting, and deployments each add one scope. Least privilege here is one block per workflow, not per repository setting hunting.

Error / query

GITHUB_TOKEN permissions: the minimal set for CI

Use this skill when

• Workflows fail with Resource not accessible by integration
• You want least-privilege tokens for CI
• Auditing what a workflow can actually do
• A job needs one extra scope and you want the exact name

Not for this skill when

• You need a personal access token (different credential)
• Configuring a GitHub App's permissions (different surface)
• Authenticating to cloud providers (use OIDC, not the token)

Steps

Step 1: Set restrictive defaults at the workflow top level

permissions:
  contents: read

Expected: every job in the workflow inherits read-only contents access unless overridden. This is the baseline; jobs that need nothing else are done here.

Step 2: Add per-job scopes only where needed

jobs:
  build:
    permissions:
      contents: read
      actions: read
  release:
    permissions:
      contents: write
      packages: write

Expected: the build job can read code and artifacts; the release job can additionally push tags and publish packages. Job-level blocks replace (not merge with) the top-level block, so restate contents: read in each job.

Step 3: Map common CI tasks to their scopes

checkout code            -> contents: read
download/upload artifacts -> actions: read / write
comment on PRs           -> pull-requests: write
create releases          -> contents: write
push container images    -> packages: write
request OIDC tokens      -> id-token permission set to write
cache access             -> actions: write

Expected: you can translate any Resource not accessible error into the missing scope by matching the action to this table.

Step 4: Verify by running and reading the error

gh run view [run-id] --log-failed | grep -i "resource not accessible" | head -3

Expected: if a scope is still missing, the error names the resource. Add exactly that scope to the job, re-run, and confirm green. Iterate until the minimal set passes.

Variant phrasings

"github token resource not accessible by integration"

A missing scope. Step 3 maps the failing action to the permission to add.

"least privilege github actions token"

Steps 1-2: restrictive top-level defaults plus per-job additions.

Why it happens

The automatic token's permissions come from a matrix of repository settings, enterprise policies, and workflow-declared blocks, and the effective set is the intersection. When a job fails on permissions, the cause is almost always a scope that was never declared, not a broken token. Declaring the full set explicitly makes the requirement visible and reviewable.

Edge cases and pitfalls

• Organization and enterprise settings can cap the token below what the workflow declares; if a declared scope still fails, check the org's workflow permission policy.
• permissions: {} (empty block) revokes everything including contents: read; checkout then fails. Always include at least contents: read.
• Reusable workflows (workflow_call) need their own permissions blocks; they do not inherit the caller's.
• Third-party actions may need scopes beyond your job's own (e.g. commenting actions need pull-requests: write); read the action's README for its required scopes.

Provenance

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

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

Thread query: GITHUB_TOKEN permissions: the minimal set for CI

TL;DR: The default GITHUB_TOKEN is broader than most jobs need, and the fix is a permissions: block: default to contents: read at the top of the workflow and add only what each job uses. Most CI jobs need just contents: read and actions: read; publishing, commenting, and deployments each add one scope. Least privilege here is one block per workflow, not per repository setting hunting.