The draft-to-beta-to-main workflow

activeStarted May 15, 2026

Every change to this site — every post, every resource page, every code change to the templates — moves through the same pipe. Branch off main. Open a PR with base: beta. The change deploys to beta.builddaily.io. You see it. You open a second PR — base: main, head: beta. That ships it. Two PRs, one preview, no surprises.

This page is the canonical write-up of how that works and why it's shaped this way.

The pipe

The workflow · 5 stepsSame shape for posts, resources, and code.

01
Branch off main
Every change starts as a feature branch from main. Posts, resource pages, components, infra — same first step. Branch lives only as long as the PR.
02
PR with base: beta
The first PR targets beta, not main. Being on a non-main branch is what keeps the change off prod — the branch is the gate, not a frontmatter flag.
03
Beta deploys; review on beta.builddaily.io
Merging the PR to beta triggers a GitHub Action that builds the site and deploys to beta.builddaily.io — the same CloudFront + S3 path as prod, with noindex so it stays out of search. Real cache headers, real fonts, real CDN behavior. If a typo, a layout regression, or a broken link is going to show up anywhere, it shows up here.
04
Promotion PR — base: main, head: beta
A second PR takes everything currently sitting on beta and promotes it to main. The diff is the diff between the two branches; multiple feature PRs can ride one promotion if they're ready together.
05
Prod deploys; live on builddaily.io
Merging the promotion PR triggers the prod deploy — same shape as the beta workflow, different bucket and distribution. The change is now live. The branch that started the chain is deleted; beta sits at the same SHA as main until the next feature PR opens.

How it got here

The first design split the flow. Code and design changes (anything that affects the build artifact — components, styles, schemas, infra) went through the branch path above. Content changes (markdown only — posts, logs, projects, resources) merged straight to main with draft: true in the frontmatter, and a build flag on the beta deploy made the draft visible on beta but invisible on prod.

The split made sense in theory. Two different concerns, two different shapes, no two-PR tax on a typo fix.

In practice the draft flag turned out to be one frontmatter typo away from publishing. A post is supposed to land on main with draft: true; if I forget the flag, or set it to the wrong value, or someone mistakenly flips it during editing — the post is live on prod the second the merge completes. The whole "draft" concept rested on a single boolean in a YAML header. That was the wrong load-bearing surface.

Amended 2026-05-24. Content now goes through the same branch path as code. The branch is the gate. The draft: true flag is retained but downgraded — useful for scheduled or backdated posts that you want on main but invisible until a specific date, not the primary control. A frontmatter typo can no longer publish.

The amendment moved through the workflow it was changing. So did the post that announced the agent that's about to draft in my voice. So is this page.

Trade-offs

The two-PR rhythm has a real cost. Every typo fix is two clicks, not one. Every batch of resource pages is two merges. For a one-author publication shipping on the order of a post or two a day, that cost is small and the catch-rate on regressions is high. For a publication shipping fifty posts a day, the trade would flip.

Beta can drift behind main if a feature PR stalls. The promotion PR collapses the drift; the hotfix path collapses it under pressure. Worth knowing about, not worth solving until it bites.

The draft: true flag still exists. It's the right tool for scheduled posts — write the post, land it on main, flip the flag closer to the announce date. Most of the time, the branch is sufficient and the flag stays off.

Why this matters

Most single-author blogs ship from one branch with no preview. The author hits "publish," sees the live URL, and notices the typo at the same time the readers do. That's fine for a hobby blog. For a publication that's supposed to demonstrate engineering judgment to a hiring manager or a client, it's not.

The workflow above is what publication-grade looks like for a one-person operation. No collaborators required; no expensive preview infra (the beta stack is the prod stack pointed at a second bucket); no abandoning a tool because it doesn't scale. Just the discipline of a second pair of eyes — your own, on a different URL, before the rest of the world gets a chance to see anything.

The output pipe for an agent that drafts posts in my voice is this workflow. The drafter writes; I edit; the PR goes to beta; I review again on the deployed preview; the promotion PR ships it. The agent doesn't get to skip the second pair of eyes either.