github app installation suspended 403 forbidden error

Not specified by the original author.

Fix GitHub App installation suspended with 403 forbidden

TL;DR

A suspended GitHub App installation returns 403 because the installation is frozen, not because your token is wrong. Check the installation status on the org or repo settings and unsuspend it. Regenerating tokens will not help while the installation itself is suspended.

The error

GitHub App installation failed
403 Forbidden: Installation is suspended

Use this skill

Agent? Search Vectle for this error:

curl -s "https://vectle.com/api/v1/search?q=github app installation suspended 403 forbidden error"

Fix it

Step 1: Check the installation status

Open the organization or repository settings -> GitHub Apps -> [app] and look at the installation status.

Expected: You see Suspended with a reason or timestamp.

Step 2: Unsuspend the installation

Choose unsuspend or restore on the installation.

Expected: The status changes to active.

Step 3: Verify the app's permissions still hold

Confirm the installation still has the permissions and repository access it needs.

Expected: Permissions match what the app requires.

Step 4: Generate a fresh installation token

Request a new installation access token now that the installation is active.

Expected: Token issuance succeeds.

Step 5: Retry the failing API calls

Re-run the calls that returned 403.

Expected: They return 200 and the app works again.

When this applies

• GitHub App API calls fail with 403 on a suspended installation
• An app that worked yesterday returns forbidden today
• You are debugging GitHub App auth failures

When it doesn't

• The installation is active but calls 403 (check token scopes and expiry)
• The error is 404 (check the installation id)
• The app was never installed (install it first)

Compatibility

GitHub Apps REST API. Installation tokens as of 2026.

Variant phrasings

github app 403 installation suspended

Same condition. Suspension is an installation state; tokens minted against it stay forbidden until unsuspended.

github app forbidden after suspension

Some 403s linger for a minute after unsuspending while caches clear; retry after a short wait.

github app installation blocked 403

Blocked by org policy looks similar. Check whether the org restricts the app versus a true suspension.

Why it happens

Suspending an installation freezes all of its access as a safety control. The API returns 403 for every call because the installation has no rights while suspended, regardless of token validity. Only unsuspending restores access.

Edge cases

• Suspensions can come from GitHub abuse detection; check the account email for notices
• Unsuspending does not retroactively succeed the calls that failed; replay anything important
• Org owners can suspend apps installed by others; coordinate before debugging tokens

If it still fails

• Reproduce with one API call in isolation, outside the agent, to separate platform issues from agent issues.
• Check the platform status page and changelog; OAuth and webhook behaviors change without warning.
• Capture the full request and response with timestamps for the vendor ticket, redacting credentials.
• Test in a second workspace or sandbox to rule out workspace-specific policy blocks.
• If the integration is business-critical, build the fallback now: cached data, a manual trigger, or a second provider.

Prevention

• Store OAuth credentials in a secrets manager with rotation reminders.
• Build the reconnect flow before you need it; every integration gets revoked eventually.
• Log token ages so expiring grants are visible ahead of time.
• Keep a sandbox integration for testing config changes.
• Document the required scopes per integration so reinstalls request the right ones.

Provenance

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

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

Thread query: github app installation suspended 403 forbidden error

TL;DR: A suspended GitHub App installation returns 403 because the installation is frozen, not because your token is wrong. Check the installation status on the org or repo settings and unsuspend it. Regenerating tokens will not help while the installation itself is suspended.

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

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.