Hosted visual screenshot approvals

Goal

Keep Linux screenshots canonical without making a solo developer download CI artifacts or wait for visual changes before continuing normal development.

Flow

1. GitHub Actions captures affected Storybook stories in the pinned Linux Playwright image.
2. The visual job uploads report.json and only the images needing review to a dedicated Cloudflare Worker backed by private R2.
3. CI writes a seven-day capability link to the job summary. Opening it exchanges the signed query token for a secure, run-scoped cookie and immediately removes the token from the URL.
4. apps/visual-review renders the existing baseline/latest/diff UI from the Worker.
5. Approval validates the selected story IDs and captured branch head, then uses a repository-scoped GitHub token to create one commit under tests/visual/baselines/linux/.
6. That commit triggers CI again. CI remains the authority that decides whether screenshots pass.

Normal CI runs visual checks in parallel and treats them as advisory. The release workflow retains the strict full-catalog visual gate.

Trust boundaries

• VISUAL_UPLOAD_TOKEN authenticates CI uploads and exists only in GitHub Actions and the Worker.
• VISUAL_SESSION_SECRET signs short-lived review links and exists only in the Worker.
• VISUAL_GITHUB_TOKEN is a fine-grained token limited to Contents write on this repository.
• The Worker accepts only the configured repository, Linux reports, SHA-1 commit IDs, safe branch names, and bounded report/PNG uploads. Approval fails when the branch has moved.
• Review objects expire after seven days; a daily scheduled cleanup removes older R2 objects.

Deployment

Create the private bucket once, configure Worker secrets, deploy, then add the returned Worker URL and upload token to GitHub:

yarn wrangler r2 bucket create octonode-visual-reviews
yarn wrangler secret put VISUAL_UPLOAD_TOKEN --config apps/visual-review/wrangler.jsonc
yarn wrangler secret put VISUAL_SESSION_SECRET --config apps/visual-review/wrangler.jsonc
yarn wrangler secret put VISUAL_GITHUB_TOKEN --config apps/visual-review/wrangler.jsonc
yarn workspace @octonode/visual-review deploy

gh variable set VISUAL_REVIEW_URL --body https://octonode-visual-review.<account>.workers.dev
gh secret set VISUAL_UPLOAD_TOKEN

The deploy workflow reuses the repository's existing CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN secrets. Rotate any exposed token immediately; capability links are bearer credentials until exchanged and therefore belong only in this private repository's Actions UI.