Support

What this covers

Support notes for Vesper webhook deployment and command troubleshooting.

Required GitHub App permissions + webhook events
Slash command behavior: /analyze, /apply, /help, /merge, /squash, /rebase
Operational controls: /pause, /resume, /status
Why reviews/inline suggestions sometimes don't appear
Optional multi-line inline review comments ("comment on lines ...")
Common log patterns and how to interpret them

/apply is a privileged command. It requires authoring to be enabled and the commenter to have write or admin access on the repository.

Baseline permissions

Minimum repository permissions for review + merge + apply:

Metadata: read (required)
Pull requests: read & write
Issues: read & write
Code/Contents: read & write

Everything else: No access (Actions/Checks/Secrets/Administration/etc.).

Comment-level access is not enough for write operations. A non-collaborator may be able to comment on a PR but should still be denied for /apply and merge commands.

Webhook events

Pull request
Issue comment
Pull request review comment

The third event enables commands posted as inline comments on the "Files changed" tab.

Fixes shipped (L2 summary)

Symptom	Root cause	Resolution
`/apply` returned 500 with `pr` unbound	Code path referenced `pr` when there were no suggestions	Always fetch `repo`/`pr` before branching; added tests
`/analyze` skipped due to "analysis already exists for SHA ..."	Dedup logic applied to manual reruns	Manual `/analyze` reruns; use `/analyze --force-review` to repost inline suggestions
PR comment posted but no inline suggestions	The analysis did not produce valid suggestion blocks for changed lines	Keep the main analysis comment, and skip empty review creation to avoid noise
Inline `/analyze` comment in "Files changed" was ignored	Webhook handler only processed issue comments	Added handling for pull_request_review_comment "created" events
`/apply` said "No code suggestions found" even when diff blocks were present	Parser expected `--- a/` headers; deletions weren't supported	Support simplified diff blocks + deletion operations; apply deletes safely
`/apply` should not run for external contributors or when authoring is disabled	Write-capable command needed explicit config and permission gating	Require `enable_authoring: true` and write/admin access; treat collaborator lookup failures as deny
Wanted "comment on lines +X to +Y" style inline reviews	Inline reviews were posted as single-line comments only	Added optional range comments (multi-line) gated by `VESPER_ENABLE_RANGE_COMMENTS`
Need to temporarily stop auto reviews on a noisy PR	No per-PR control for auto triggers	Introduce `/pause` and `/resume` using the `vesper:paused` label

Tip: When triaging "ignored" events, remember the handler processes PR actions (opened, reopened, synchronize) plus comment events. Review "submitted" events are expected to be ignored.

Validation checklist

Create a PR with a small code change
Comment /analyze in Conversation (and optionally as an inline file comment)
Verify the main Vesper analysis comment updates
Use /analyze --force-review when you want inline suggestions reposted
If authoring is enabled and the commenter has write/admin access, comment /apply and confirm a bot-authored commit lands on the PR branch
Optionally test merges: /merge, /squash, /rebase
Pause auto runs: /pause; re-enable: /resume

Command replies

Vesper keeps command replies short. A normal reply may use 🙂, a blocked or unavailable state may use 😅, and a paused or no-op state may use 😴.

Vesper: Paused

😴 Auto analysis is paused for this PR.

Quota cooldown

When Gemini returns a quota or rate-limit error, Vesper posts a short notice and temporarily skips auto-analysis on new commits for a short cooldown window.

Config (Vercel → Project → Settings → Environment Variables):

VESPER_QUOTA_COOLDOWN_SECONDS=1800

Examples: 300 (5 min), 1800 (30 min, default), 0 (disable cooldown).

Multi-line inline reviews

By default, Vesper posts inline review comments anchored to a single line. If you want GitHub’s “comment on lines +X to +Y” style UI for block feedback, enable range comments.

Config (Vercel → Project → Settings → Environment Variables):

VESPER_ENABLE_RANGE_COMMENTS=1

Notes: keep this off if you only want one-line ```suggestion``` fixes. Range comments are best for block-level guidance; /apply continues to work for suggestions.

Log signals

Useful strings to filter in Vercel logs:

Processing /analyze
Error handling apply comment:
Posted ... inline suggestions as a review
Skipped review creation: no inline suggestions to post
Quota exceeded for PR
Ignored webhook event: