Review PR screenshots on one page with GitHub sign-in (works on private repos)

[pftg]

Problem

When a pull request changes screenshots, accepting the new pixels today means checking out the branch, re-running the suite and committing baselines by hand. Three lighter approaches were built on feat/review-page (#313) and judged too hard to use:

1. a static review page on GitHub Pages that needs a pasted personal access token on every visit;
2. copying a /snap-diff accept … command from the report into a PR comment;
3. a report button that opens a prefilled GitHub issue to submit.

Reviewers should approve or reject screenshots from one page, without handling tokens or commands, and it must work for private repositories.

Appetite

Small batch, 2 weeks. The review page, diffing and safe commit already exist and were proven end to end on #314 (committed bytes identical to the CI artifact, CI re-ran on its own, failing tests went from 11 to 5 after accepting 3). New work: GitHub sign-in, a tiny Worker, and a setup command.

Solution — reviewer

The PR comment links to one page. Sign in with GitHub once (8 hours), land on the first changed screenshot, hold Space to flip baseline/new, A accept / R reject, J/K move, then Commit N screenshots to <branch>.

• Accept: the exact CI bytes are committed in one commit under the reviewer's name; CI re-runs.
• Reject: noted on the PR, nothing committed; the test keeps failing until the code is fixed.
• Undecided: nothing happens.

+----------------------------------------------------------------------------+
| snap_diff   acme/shop #314 · feature/login @a1b2c3d              @reviewer ▾  |
+-----------------+----------------------------------------------------------+
| ● login     ✓   |  login · changed · 12%          [Side|Toggle|Diff|Heat]  |
| ● signup    ✗   |                                                          |
| ○ header   new  |     BASELINE (main)        |      NEW (this run)          |
| ◌ index earlier |   +-------------------+    |    +-------------------+     |
| ● index         |   |                   |    |    |                   |     |
|   …             |   +-------------------+    |    +-------------------+     |
|                 |          hold SPACE to flip · J/K next/prev              |
|                 |             [ Reject  R ]        [ Accept  A ]           |
+-----------------+----------------------------------------------------------+
| 1 accepted · 1 rejected · 8 to go    [Accept remaining 8]   [Undo U]       |
|                               [ Commit 1 screenshot to feature/login ⌘↵ ]  |
+----------------------------------------------------------------------------+
   Accept → committed (CI re-runs) · Reject → noted on PR, nothing committed

Guards carried over from the proven page: the link's run, artifact and PR are checked against each other; files are bound to their SHA-256; only PNG/WebP bytes at screenshot paths are written; the branch update never forces (a moved branch is refused); only the last capture of a file can be decided; an expired artifact says so.

Solution — setup, empty project to working (≈10 minutes, 3 clicks)

Prerequisites: a GitHub repository you administer, a free Cloudflare account, Node (for npx).

 bundle add snap_diff-capybara      bundle exec snap_diff setup            git push
 + 2 test-helper lines          ──▶ ┌────────────────────────────────┐ ──▶ next failing PR
                                    │ writes screenshots.yml          │     comment shows
                                    │ Cloudflare: [Log in]          ●1 │     "Review 12
                                    │ GitHub:  [Create GitHub App] ●2 │     screenshots →"
                                    │ GitHub:  [Install on repo]    ●3 │
                                    │ writes review-url into workflow │
                                    └────────────────────────────────┘
                                     (re-run after a gem upgrade: redeploys)

Each project runs its own GitHub App and Worker, so nobody outside the project touches private code. The Worker serves the page and does the one thing a browser cannot: exchange the sign-in code using the App's secret.

Rabbit holes

A one-day spike gates the build. With a GitHub App user token on a private repository in an organisation with SAML:

• download an Actions artifact;
• push a commit to a PR branch and see CI start (fallback: dispatch CI after the push);
• sign in under SAML;
• the App manifest flow redirects back to the local setup command.

No-gos

A shared hosted instance, signed review links, fork PRs, GitHub Enterprise Server, mobile layouts, and the comment/issue bot currently on #313 (to be removed).

Decisions

Proposed in #315 (links work once it is merged):

• Review PR screenshots on a sign-in review page backed by a self-hosted GitHub App and Worker (proposed)
• Ship review setup as a gem executable (proposed)

Done when

• Spike passes (results recorded in the first ADR); both ADRs accepted.
• The review page signs in with GitHub and commits accepted screenshots; rejected ones are noted on the PR.
• bundle exec snap_diff setup takes an empty sample app to a working review link in about 10 minutes with 3 clicks.
• End to end on a private repository: committed files' SHA-256 equal the CI artifact's, CI re-runs, rejections are listed on the PR.
• The comment/issue bot and the report's review controls are removed; docs describe the new flow.