agent read-only token forced reviews into plain comments

TL;DR

The agent's token lacks pull-request write scope, so it posts findings as plain comments instead of reviews. Grant the token write access (or document the limitation) - plain comments cannot request changes or block merges.

Error

Agent log: review submission 403  -  resource not accessible; falling back to plain issue comments.

Steps

1. Confirm the scope gap: the 403 is on the review endpoint while comment posting works. Expected: a permissions issue, not a code bug.
2. Request the right scope: the token/app needs pull-request write (or the reviews:write equivalent). Expected: the token can submit reviews.
3. If the org will not grant write scope, document the limitation: the agent's output is advisory comments only, and a human must translate findings into a review. Expected: no one mistakes comments for blocking reviews.
4. Re-test the review submission. Expected: formal reviews post with inline anchors.

When to use

• The agent posts findings as plain comments because review submission 403s.
• The token is read-only or narrowly scoped.

When not to use

• The agent has write scope but still posts comments - that is a code bug, not permissions.
• Plain comments are the intended output; then nothing is broken.

Tool compatibility

• GitHub Apps / tokens with restricted scopes.
• Any review agent.

Variant phrasings

GitHub App missing a single permission

Apps need explicit permission grants - check the app's permission list, not just the token.

Org blocks third-party write access

Run the agent under a first-party identity or accept advisory-only mode explicitly.

Why it happens

Formal reviews (approve/request-changes, inline anchors, blocking status) require write scope; plain comments do not. A read-only token silently degrades the agent from a reviewer to a commenter, and the team loses the blocking power of reviews.

Edge cases

• Advisory-only mode is legitimate if the team chooses it - but it must be a choice, not an accident.
• Audit what the agent can do after a scope change; write scope also enables merges and dismissals.

Provenance

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

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

Thread query: agent read-only token forced reviews into plain comments

TL;DR: The agent's token lacks pull-request write scope, so it posts findings as plain comments instead of reviews. Grant the token write access (or document the limitation) - plain comments cannot request changes or block merges.