Repository navigation
Share the explanation page on the PR - #26
Merged
Merged
Conversation
Member
Author
|
🌷 Tulip explanation of this PR (as of Download the raw file and open it in a browser: the changes grouped by concern, most important first, with diagrams. GitHub's "not on any branch" warning is expected: previews live on hidden refs. |
stivens
marked this pull request as ready for review
October 19, 2026 16:08
Every run writes a signed run manifest next to the single-file page (ADR 0030). Three ways to share the page: - --attach-preview-as-comment: share as soon as the run ends - tulip share <run dir>: share an earlier run, after reading it or to retry - a "Share on PR" button in --serve mode The run dir's index.html is always the static page; --serve serves its own page, with the review boxes and Share button, from memory. Sharing stores the page as an orphan commit under a hidden ref (refs/tulip/previews/pr-<n>/<commit>) in the PR's repo, or the user's fork without push access, and posts or updates a PR comment linking it. GitHub only. Design and trade-offs: docs/adr/0029-preview-comment.md. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
When a fork created in the last ten minutes isn't ready for writes (404/409), the share now fails at once asking to retry in a minute, instead of retrying for up to five minutes.
Closing the server waits for an in-flight POST /api/share, so stopping the share only after serveForReview resolved let it keep running after Ctrl+C.
The PR URL, head commit, render time and HMAC now live in meta tags at the start of index.html's head, so the page alone can be shared with tulip share.
Write the key to a temp file and link it into place, so no run reads a partial key and an existing key is never replaced.
An earlier-preview link must equal the URL storePreviewFile builds for this PR and the entry's commit, in the PR or store repo. Replaces the looser prefix and URL-shape checks.
One Origin check for all POSTs, one errorMessage helper for the new code, and shared helpers for the page's POSTs, CLI argument errors and the commit SHA pattern.
GitHub serves the page as text and may not show a multi-MB file, so the comment now gives a command that downloads the current preview via the contents API.
Private forks get only the repo's team permissions, so people with individual access can't open the preview.
adamw
force-pushed
the
feat/share-preview-on-pr
branch
from
November 17, 2026 09:56
2af6393 to
bb77a55
Compare
Checked on github.com that refs/tulip/* refs start no on: push workflow and aren't cloned.
0029 was already taken by the context-dirs ADR on master.
A user's comment that only quotes the marker was edited or minimized. Now the comment must start with Tulip's header and end with the marker, whose state is read from the end.
No Share button, no tulip share hint, and --attach-preview-as-comment skips the share and exits 1.
Define the signature length once, reuse errorMessage in run.ts, and check the preview file name for shell safety instead of re-encoding its format.
Within a run, build the preview from the signed page render returns instead of reading it back from disk; tulip share still verifies the file.
Drop the fork-age check: it only picked between two messages. Keep GitHub's error and add the retry hint.
Tests for others' comments, a PR closed before publish, fork-stored links, the latest comment, the history cap and a failed Share request.
The Share button, serve shutdown and retry tests now wait for the state they need.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a way to share Tulip's explanation page on the PR itself, so other reviewers can read it without running Tulip (and paying for the LLM passes) themselves.
Important
This is a nice-to-have feature, and hosting the page is the troublesome part because of GitHub's limitations, so maybe we want some other approach. GitHub has no API for attaching a file to a comment (and
.htmlisn't an accepted attachment type anyway), so this PR stores the page in the repo on hidden refs and links it from a comment. That works, but it has real downsides, listed under Limitations.What it does
The page is already a single self-contained
index.html(ADR 0030). Each run now also signs it:<meta>tags in its<head>record the PR URL, the head commit, the render time and an HMAC signature. There are three ways to share it:Sharing does three things:
refs/tulip/previews/pr-<n>/<commit>. The ref goes in the PR's repo if you can push to it, otherwise in your fork, which is created if needed.gh apicommand that downloads it.Example comment:
Limitations of this approach
Other approaches we could take instead:
Security notes
tulip shareonly publishes a page signed with your key: HMAC-SHA256, per user, created atomically next to Tulip's settings with permissions 0600. The signature sits in the page itself; it is computed with a placeholder in its place, and only the leading<head>Tulip writes is read. A page someone hands you, or one edited since, can't be posted under your name. If the page can't be signed (e.g. a read-only home), sharing is turned off for that run and the reason is logged.<and>are escaped.POST /api/sharekeeps serve mode's Host and Origin guards and also requires a JSON content type.Testing
pnpm lint,tscandpnpm testall pass (1122 tests).git push, start no unfilteredon: pushworkflow and aren't fetched by a default clone;tulip sharefor the same commit edits the comment;Reviewing
docs/adr/0032-preview-comment.md.tulip-*meta tags and the Share button;render.tssignsindex.html, and renders serve mode's page separately; the server now serves that page from memory, soindex.htmlis always the static page that gets shared;run.tswires sharing in;server.tsgets the new route, with one Origin check for all POSTs;🤖 Generated with Claude Code