TwoDot Engineering
Release Process 2.0
From ceremonious, opaque releases to traceable, trunk-based delivery.
dev
→
staging
→
prod
Why it's changing · What's new · How it works
Why
Why are we changing?
🐢
Slow & risky
No staging. Manual deploys to dev caused prolonged integration risk and wasted time.
🎭
Ceremonious
Every release was a multi-step dance across two repos — for each environment.
🌫️
Opaque
You couldn't trace a commit to prod, or even tell what was deployed where.
Bottom line: shipping was slow, manual, and hard to reason about.
Before
Where we were
- No staging environment — nothing between dev and prod.
- Manual deploy to dev — prolonged integration risk & wasted time.
- Releases spanned two repos, repeated per environment.
- An agent hid the complexity — but the complexity was still there.
Hiding complexity is a smell, not a fix.
Before
Releasing was a 5-step ritual
2
Raise a PR with the desired version infra repo
3
Ensure 1× approval + branch up to date infra repo
5
Branch is deployed, then merged to main infra repo
Two repos, several manual gates — repeated for every environment. Traditional, ceremonious releases.
Before
Flying blind
- Couldn't trace a single commit from the mono repo all the way to production.
- Hard to determine what's currently deployed in a given environment.
- No way to see what changes are included in a given release.
- No way to diff the Kubernetes YAML as part of a release.
Without traceability, every release carried hidden risk.
What — the new model
Now: dev → staging → prod
dev
auto-deploys on merge
staging
promote a known-good commit
prod
promote a known-good commit
- A real staging environment in the middle to catch issues before prod.
- Auto-deploy to dev on merge — instant feedback, no manual step.
- Move forward by promoting commits, not re-cutting releases.
What — the new release
Releasing is now one step
Promote the desired commit to staging.
That's it.
- dev is instant on merge — nothing to do.
- staging / prod = a single promotion action.
- No second repo. No version PR. No ceremony.
Was: 5 steps across 2 repos → Now: 1 promotion.
Before vs After
The shift at a glance
| Before | After |
|---|
| Environments | dev → prod (no staging) | dev → staging → prod |
| Dev deploys | Manual | Automatic on merge |
| Release steps | 5 steps, per environment | 1 promotion |
| Repos touched | Two (mono + infra) | One (from GitHub) |
| Traceability | Commit → prod not traceable | Commit traced end-to-end |
| What's deployed? | Hard to tell | Visible per env in GitHub |
| Release notes | None | Change set on every PR / run |
| K8s diff | Not available | Shown per PR / workflow run |
What you gain
Trace one commit, end to end
commit a1b2c3d
→
✓dev
→
✓staging
→
◷prod
- Follow any change from commit → dev → staging → prod.
- See what's deployed to each environment directly from GitHub.
- Know exactly what's included before you promote.
What you gain
Every change is legible
📝
Release notes on every PR & run
A change set is generated automatically — no more guessing what shipped.
🔍
See the delta
Shows everything that would go out when deployed to a given env — great for risk.
☸️
Kubernetes diff
See exactly what changes in Kubernetes for any PR or workflow run.
✅
Fewer surprises
Better risk management — you review the impact before it lands.
How — the mechanics
How it works under the hood
- Trunk-based development — commit to main regularly.
- Auto-deploy to dev on merge — the trunk is always live in dev.
- Promotion-based delivery for staging & prod, driven from GitHub.
- Helm for templating only — not for distribution.
- Diffs generated per PR / run — release notes and the Kubernetes change set.
How — the pipelines
Two pipelines: CI and CI/CD
🧪
CI runs on branches
Validates your work — build, test, checks — on every branch / PR before it reaches main.
🚀
CI/CD runs on main only
One workflow capable of taking a change all the way from dev → staging → prod.
What changed today: CI/CD used to run on branches too (with dev→staging→prod blocked). That caused workflows to get cancelled — and was redundant — so branch runs of CI/CD have been removed.
How — release management
Infra changes are in transition
TwoDotAi/infra
today — separate infra repo
mono repo · /infra
destination — alongside app code
- Infra changes still happen via TwoDotAi/infra for now.
- It's being moved into an ./infra directory inside the mono repo.
- For the time being: use the same process for infra changes.
Consolidating infra alongside app code — same workflow today, one repo tomorrow.
How — the mindset shift
The biggest change is how you think
Old mindset
"We're going to cut a release" — a deliberate, batched event you prepare for.
New mindset
Every change is a potential release candidate. We promote release candidates — we don't "cut releases".
- Treat every commit as releasable — it could be promoted to prod next.
- Avoid long-running branches; small, frequent commits to main.
- Not ready? Toggle it off (feature flag or a conditional in code).
How — operational jobs
Housekeeping & safety nets
🧹
Delete Workflow Runs
Manual, on-demand. Cleans up workflow runs from branches that pollute the Actions view — keeps the run history readable.
🗄️
Restore Postgres Database WIP
Runs on a schedule. Continuously verifies our database restore process actually works — so we find out before we ever need it.
Small jobs that keep the pipeline clean and our recovery trustworthy.
How — reading the views
What the colours mean
⚙️ Workflow view (Actions)
✕Failed — the run failed.
✓Tick — it went all the way to prod.
●Yellow circle — waiting for promotion.
🚢 Deployments view
✕Failed — the deploy failed.
✓Green tick — successful, current deploy.
✓Grey tick — a past deployment, no longer latest.
●Yellow circle — has things available for promotion.
About the times: the timestamps on the workflow & deployments views are when the commit was merged to main — not when it was released. To see a release's actual time (and who approved & deployed it), open the workflow run and scroll to the bottom.
▶ LIVE DEMO
Let's see it in action
Tip: each card is a clickable link — open them as you talk through the colours above.
Recap
The TL;DR
Before
Manual, ceremonious, opaque — no staging, two repos, no traceability.
Now
dev → staging → prod. Auto-dev, one-step promotion, full traceability and diffs.
The win
Faster, safer releases. See what's deployed, what's changing, and the K8s diff — every time.
Your part
Trunk-based, short-lived branches, toggle unfinished work, promote commits forward.
Troubleshooting
When something doesn't deploy
⚠️ "I made a change, merged to dev, and it's not being picked up in a release."
Check the path triggers in ci-cd.yaml. If your changed files don't match a trigger path, the CI/CD workflow won't run for that change.
More gotchas will live here as we learn them — shout if you hit one.
Discussion · if time allows
Open questions — let's decide together
That's the change. A few things still need a team decision — not blockers, just choices about how we want to use the new setup.
1 · Staging as a demo environment
2 · Where do PoCs live?
3 · Who can do deploys?
Discussion · 1 of 3
❓ Staging as a pseudo-demo environment
Who owns staging?
- Staging is currently doubling as a demo environment.
- Proposal: Jackson owns it until he has a dedicated demo env.
- Anything in PoC gets tested in staging.
→ Are we OK with this trade-off (demo stability vs. testing throughput)?
Discussion · 2 of 3
❓ Where do PoCs live?
PoCs: staging, or prod behind a toggle?
Option A — In staging
PoCs are tested in staging (current direction). Safer, but competes with demo use and is less production-realistic.
Option B — In prod, behind a toggle
PoCs live in prod, gated by a feature flag. Maximally realistic, but more risk and toggle discipline required.
→ Which do we want — and does it depend on the PoC?
Discussion · 3 of 3
❓ Who can do deploys?
Who can deploy — and who reviews?
- Today, anyone can do deploys — no restriction on who promotes to staging or prod.
- We currently allow self-reviews — you can approve your own change.
→ Do we want guardrails — restricted deployers, required peer review, or extra gates for prod?
TwoDot Engineering
Questions?
dev
→
staging
→
prod
Traceable. Trunk-based. One-step promotion.