Repository navigation
Description
Summary
Let people show a /dev/null commit on their own site (a blog, docs, a Notion page) as a card that looks and reads like /dev/null: the commit, optionally the rest of its author's thread, and its replies, down to several levels. The card is an iframe served by /dev/null, so it always shows the commit's current state. An oEmbed endpoint lets blogging platforms build the card from a link.

Motivation
Quoting a thread in a blog post, a newsletter or docs today means taking a screenshot. A screenshot loses the links, the code, the polls and the conversation, and it stays up after the author deletes the commit. A card served by /dev/null stays live, leaves the author in control, and sends readers back to the thread.
Goals and non-goals
Goals:
- Embed a single commit, a thread, or replies to replies, as chosen by whoever creates the embed.
- Render everything a commit can hold the way /dev/null does: formatting, code, emoji, mentions, hashtags, links, quoted commits, color swatches, images, link cards, players and polls. Draw it on the same graph rail.
- Respect deletion, moderation and the author's choice on every page that shows the card.
Non-goals:
- Interacting from the card. Starring, voting, replying and translating stay on /dev/null.
- Measuring embeds. There are no view counts, no referrers and no tracking.
- Embedding anything other than commits, such as profiles, logs or Remotes.
Product
Who can embed what
- Only signed-in members can create an embed, for any approved, public commit. Readers of the page that shows it don't need an account.
- This is enforced, not just hidden: every embed URL is signed by /dev/null (see Signed URLs), so a guest can't build one by hand.
- Embeds are on by default. Authors can turn them off in Settings → Profile. For commits posted as an organization, the organization's setting applies, and only its admins can change it.
- Turning embeds off also affects cards that already exist, since the card is served live: they then read
[unavailable].
| User | Organization |
|---|---|
![]() |
![]() |
Entry point
Embed commit sits in the commit's "…" menu, right after Send in Remotes. Guests don't see it. It is also hidden when the commit can't be embedded: when it isn't approved, when it is deleted, or when its author or organization turned embeds off.

The dialog
It is a regular /dev/null dialog, widened to fit a live preview of the card. The preview sits next to the settings, or under them on phones. The settings follow the conventions of the Settings pages:
| Setting | Control | Default | Shown when |
|---|---|---|---|
| The rest of the thread | Switch | On | The commit starts a self-thread |
| Replies | Switch | On | The commit has replies |
| Per level | 1, 3, 5, 10 | 3 | Replies is on |
| Levels | 1, 2, 3, All | 3 | Replies is on |
| Max height | 480px, 640px, 800px, None | 640px | Always |
| Theme | Light, Dark, Auto | Auto | Always |
On a reply, a note replaces the thread switch: the card always starts from the root commit.
The footer has three tabs. Each one shows its code in the same CodeBlock as commits:
- HTML: the iframe and the resize script, for any site that accepts HTML.
- Markdown: the commit's preview image linked to the commit. Markdown renderers, like GitHub READMEs, strip frames, so this is the best they can show.
- Link: the commit link, with the settings and their signature as parameters, for sites that support oEmbed.
Copying prints a toast in the voice of the commit toast, [embed 9f3c2a1] copied. A failed copy prints fatal: could not copy embed code for 9f3c2a1.

What the card shows
The card reads like the commit's page and is drawn with the same components.
- A top-level commit: the commit, then the rest of its self-thread when enabled (
1/3,2/3…), then its replies. - A reply: the whole chain from the root commit down to the reply, then the reply's own replies.
- Replies: the first N direct replies at each level, down to the chosen depth.
- When a level holds more replies than the card shows, it ends with Show the last N, like on /dev/null.
- Replies below the last level show up as
› N repliesin the actions row. - Both link to the commit on /dev/null.
- Each commit: the same header as on /dev/null (name, handle, date, thread badge, and the hash on the right), the same body, and the commit it quotes. Dates are absolute (
Nov 6), because relative times age badly in an article. - The embedded commit is drawn like the focused commit on its page, with a larger body and the full date line.
- Actions: /dev/null's actions row, read-only. The star count and
› N repliesopen the commit on /dev/null. - Polls: while a poll is open, its options link to /dev/null to vote, and no results are shown. Once it is closed, the card shows the final results.
- Text: always in its original language, with no Translate control.
- Players: they work like on /dev/null, and load only once the reader presses play.
- Footer: the /dev/null logo and View on /dev/null →.
- Max height: past it, the thread scrolls inside the card, and the footer stays in view.
| A reply, from the root | A single commit | A narrow page |
|---|---|---|
![]() |
![]() |
![]() |
Tombstones
A commit that can't be shown keeps its place in the card, without author or body, so the rest of the thread still reads. This applies to the embedded commit itself too.
| Tombstone | When |
|---|---|
[deleted] |
The commit was deleted |
[unavailable] |
The commit is pending or rejected, or its author or organization turned embeds off |
Opting out reads [unavailable] on purpose: a card shouldn't tell the world who turned embeds off.
![An embedded commit that is still pending, shown as [unavailable]](https://raw.githubusercontent.com/jubianchi/dev-null.sh/ebbae80d5b9baa1389979d7ac5483ca364290553/09-tombstone-unavailable-light.png)
The card always renders what a guest sees on /dev/null. There is no session, so there are no mutes or blocks to apply.
Naming
I went with embed, both in the UI (Embed commit) and in code (/embed, allows_embeds). PRODUCT.md stops the git metaphor at commit and log outside Remotes, and asks for labels anyone understands. The git voice lives in the copy instead, as in the [embed 9f3c2a1] copied toast.
Cherry-pick would be the git-flavored alternative, as in Cherry-pick commit, /cherry-pick/{commit} and allows_cherry_picks. It has three problems:
PRODUCT.mdwould need a second exception, next to the one for Remotes.- It says less than "embed" to someone who doesn't use git.
- In git, a cherry-pick is a copy that no longer follows its source. A card does follow its source, so the word promises the opposite of what the feature guarantees.
Technical design
Overview
sequenceDiagram
autonumber
participant Author as Embed author
participant App as dev-null.sh
participant Site as Third-party page
participant Reader as Reader's browser
Author->>App: "…" → Embed commit, pick settings
App-->>Author: Signed iframe + embed.js, or signed commit link
Author->>Site: Paste code or link
alt Link on an oEmbed consumer
Site->>App: GET /oembed?url=…
App-->>Site: rich oEmbed JSON with the iframe
end
Reader->>Site: Open the page
Reader->>App: GET /embed/{uuid}?…&signature=…
App-->>Reader: Server-rendered card, framable, no cookies
Reader->>Reader: Card posts its height, embed.js sizes the iframe
Routes
| Method | Path | Purpose |
|---|---|---|
GET |
/embed/{commit} |
The card: signed, framable, sessionless |
GET |
/embed.js |
The resize script, static and long-cached |
GET |
/oembed |
The oEmbed provider, JSON only |
GET |
/commits/{commit}/embed-link |
Members only: signs the card's URL and returns the HTML, Markdown and Link code |
PUT |
/settings/embeds |
The user's setting |
PUT |
/organizations/{organization}/settings/embeds |
The organization's setting, admins only |
When the commit page is opened from a signed embed link, it gets an oEmbed discovery <link> in its <head>.
Parameters
/embed/{commit} and the Link tab's commit URL share the same parameters:
| Parameter | Values | Default |
|---|---|---|
thread |
1 |
Off |
replies |
1, 3, 5, 10 |
Off |
depth |
1, 2, 3, all |
3 with replies |
theme |
light, dark |
Auto |
max_height |
480, 640, 800, none |
640 |
Unknown or out-of-range values fall back to their default. The commit is always addressed by its UUID, never by its short hash.
Signed URLs
Every embed URL carries a signature: an HMAC of the path and the normalized query, keyed with the application key. This uses Laravel's relative signed routes, URL::signedRoute(absolute: false) and signed:relative, without expiry.
- Only the dialog's endpoint, which needs a signed-in member, produces signatures. Without a valid signature,
/embedanswers403and/oembedanswers401, so consumers fall back to a plain link. - A bare commit link pasted into an oEmbed consumer therefore gives no card. Only the Link tab's signed link does.
- The signature covers the commit and the settings, and nothing else. Nothing is stored, and nothing ties an embed to the member who created it.
- Because the settings are signed, nobody can derive other cards from an existing one. That also rules out cache-busting variants.
- The signature leaves out the scheme and host, so cards keep working behind a proxy that terminates TLS, or on another domain of the app. With absolute signatures, every card answered
403through a tunnel. - Rotating the application key invalidates every existing embed. That is acceptable for a key rotation, but worth a line in the runbook.
The embed page
-
Middleware: it runs outside the session and CSRF handling of the
webgroup, so it sets no cookie and always renders the guest view. -
Framing: it is the only page excluded from
PreventFraming. It sendsContent-Security-Policy: frame-ancestors *and noX-Frame-Options. -
Query: it builds the tree once from the embedded commit, made of the ancestors up to the root, the self-thread, and N replies per level down to the depth. Each node is marked visible, or with its tombstone. Visibility follows the guest rules (approved, not deleted) plus the embed setting of the author or organization.
-
Bundle: the card has its own client entry point,
resources/js/embed.tsx. It loads the card's page only, without the app's live updates, analytics or service worker. On the server, the card renders through the app's SSR bundle. -
Rendering: an Inertia page with a bare layout, built from the commit page's components:
CommitHeader,GraphRail,ReplyBranch,CommitBody,QuotedCommit;CommitPoll,LinkPreview,TombstoneLine.
Read-only props turn off every control that writes. Links in the body are plain links, so hovering a mention fetches nothing from /dev/null.
Without JavaScript
Two scripts are involved, and a card missing either one still reads:
| Missing | When | What the reader gets |
|---|---|---|
embed.js, on the host page |
The site strips <script> but keeps frames (many CMSs) |
The card at the height written in the code: max_height plus the footer, 685px by default |
| The card's own JS | JavaScript is off, or the frame is sandboxed without allow-scripts |
The whole card as rendered by the server: text, highlighted code, images, links, the rail, tombstones |
- Links open outside the frame through
<base target="_blank">. - Only a few things need JavaScript: the copy and Wrap lines controls of code blocks, the players, and the height message.
- An explicit Light or Dark theme holds without JavaScript. Auto stays light, since only the browser knows the reader's preference.
- A site that strips
<iframe>as well gets nothing from the HTML tab. The Markdown tab and oEmbed exist for that case.

Resize protocol
The card posts its height to the host page whenever it changes:
parent.postMessage({ type: 'devnull:embed:resize', id, height }, '*')embed.js only accepts this message from the origin it was loaded from. It resizes the one frame that sent it, and listens only once even when a page includes it several times. With a max height, the card caps itself and scrolls inside, so the frame never grows past max_height plus the footer.
oEmbed
GET /oembed?url=…&maxwidth=…&format=json returns a rich response whose html holds the iframe and the script:
{
"version": "1.0",
"type": "rich",
"provider_name": "/dev/null",
"author_name": "Mira Okafor",
"html": "<iframe src=\"https://dev-null.sh/embed/…\" …></iframe><script async src=\"https://dev-null.sh/embed.js\"></script>",
"width": 550,
"height": 685,
"cache_age": 3600
}- The embed parameters on
urlcarry over to the iframe. The width followsmaxwidth, up to 550px. - The endpoint answers
404for an unknown commit. It answers401when the link isn't signed or the commit can't be embedded, and501forformat=xml. - For an organization's commit,
author_nameis the organization's name. The member who posted it is never revealed. - Platforms with an allowlist, such as WordPress core, need /dev/null registered with them. The oEmbed providers registry is the first step.
Data
| Table | Column | Default | Who sees it | Deleted |
|---|---|---|---|---|
users |
allows_embeds |
true |
The user | With the account |
organizations |
allows_embeds |
true |
The org's admins | With the organization |
The column is included in the export. Nothing else is stored: no embed records, no referrers, no counters.
Load and abuse
Every reader of an article loads the card anonymously. That makes /embed and /oembed the cheapest way to make /dev/null work without an account, so they have to cost an attacker more than they cost the server.
- Rate limits, next to the existing limiters:
embedsallows 120 requests per minute per IP and commit, so a page with several cards still loads, and 600 per minute per IP, so one address can't walk every commit.oembedallows 60 requests per minute per IP, since consumers fetch a link once and cache the result.
- Bounded work:
- The signature is checked before any query, so a forged URL costs one HMAC.
- Parameters are a closed set, so a commit has a few dozen possible cards at most.
- A card holds at most 40 commits, whatever depth is asked for.
depth=allnever walks an unbounded thread. - The route constraint rejects a malformed UUID before any query.
- No writes: serving a card never writes to the database or the session.
- Static script:
embed.jsis a static file with a long cache.
Planned, but not built yet in #1522:
- A 30-second cache of the rendered tree, per commit and settings. It would be forgotten as soon as a commit in the thread is deleted or moderated, or its author changes their setting, so a card is never staler than /dev/null.
- A readable fallback with a link to the commit when a card is throttled (
429), instead of Laravel's error page. - A constant number of queries to build the tree, whatever its size. feat: let members embed commits on other sites #1522 queries each node's replies.
Security and privacy
- The card is the only framable page. Everything else keeps
PreventFraming. - The card sets no cookie, so there is no session to ride on, no clickjacking of signed-in actions, and nothing written from the card.
- The resize message only carries a height, and
embed.jschecks its origin before acting on it. - The card shows only what a guest sees. Pending, rejected and opted-out content never leaves /dev/null, and an organization's commit never reveals who posted it.
- Third-party players load only after the reader presses play, as they do today.
Rollout
#1522 implements everything in one draft, so the design can be tried out. It can be split into separate pull requests:
- The setting: migration, the user and organization settings, the export.
- The card: the route, middleware and tree query, and the read-only page.
embed.js: the resize script.- oEmbed: the endpoint and the discovery link.
- The dialog: the menu entry, the signing endpoint, the dialog.
- Docs:
KNOWLEDGE_BASE.md,DESIGN.md(a Commit Embed component, and an exception to the No Cards Rule) andPRODUCT.md.
Open questions
- The name: embed or cherry-pick (see Naming).
- The rollout: should this ship as one PR, or split as above?
- The edge: do
/embedand/oembeddeserve a dedicated rule in front of the app?






Activity
feat: let members embed commits on other sites