Architecture and Release Workflow on Pantheon Next.js
- Development
- Strategy
(01)The Old Architecture
Two repositories, two upgrade tracks, one CMS nobody used
fastforward.sh ran on Pantheon's Decoupled Sites platform: a Gatsby 4 front-end in one repository, a headless WordPress install in another, and a WPGraphQL endpoint stitching them together at build time. Two repositories, two upgrade tracks (Node + Gatsby on the front; PHP + plugins on the back), and one CMS that the editorial team had quietly stopped logging into.
The diagram traces the request path under that setup. WordPress held the source of truth, GraphQL was the integration layer, Gatsby was the build tool, and Pantheon's Decoupled Sites platform fronted the result. Every architectural decision had to flow through both halves; every plugin update on the WordPress side risked schema drift on the Gatsby side.
(02)The New Architecture
One repository, fully static, served from Pantheon's CDN
The new shape replaces the entire backend with the repository itself. Content lives as MDX and YAML files under content/. A build-time loader reads them with gray-matter and js-yaml, returning typed objects to statically-generated routes. Next.js 16 on Pantheon's Next.js platform builds the site from GitHub on every push to main, and Pantheon's CDN serves the result.
The CMS database is gone. The GraphQL layer is gone. The plugin update treadmill is gone. The runtime surface — the only routes that aren't prerendered — is a single API route for the contact form. One repository. One pipeline. One mental model.
(03)A Future-Friendly Shape
If the editorial reality changes, the shape can too
Today's editorial team works in pull requests, so MDX-in-repo fits. If that changes — if non-technical editors come back into the picture, or if content volume outgrows what's comfortable in version control — the Next.js platform absorbs a headless CMS without a full re-platform.
The diagram sketches that future shape. A headless CMS (Contentful, Sanity, Payload, or another) feeds Next.js at build time; the rest of the stack — Pantheon's hosting, the CDN, the Dev/Test/Live promotion model — is unchanged. The architecture is intentionally open at the source-of-truth boundary, so the platform shape can grow with the editorial reality, not against it.
(04)The Release Workflow
Push to main, tag to promote
Pantheon's Next.js platform inherits the Dev → Test → Live environment model from their WordPress and Drupal products. The mental model collapses to one line: push to main, tag to promote.
Every push to main auto-builds and deploys to Dev, usually within 1–3 minutes. Promotion to Test happens by pushing a git tag matching the pantheon_test_* prefix at the commit you want to ship; Pantheon watches for the pattern and builds. Promotion to Live is the same shape, with pantheon_live_*. The git log is the deploy log: every Test build has a tag, every Live build has a tag, and the diff between two tags is the diff that shipped.
(05)Tagging Test and Live
Two commands, two environments
The promotion commands are short enough to commit to memory or to alias. They follow a single pattern: annotated tag with a date-stamped suffix, then push the tag.
To promote to Test: git tag -a pantheon_test_$(date +%Y%m%d) -m "Promote to Test", followed by git push origin pantheon_test_$(date +%Y%m%d). The same shape with the pantheon_live_* prefix promotes to Live. Rolling back is just tagging a prior commit with a fresh pantheon_live_* tag — the same forward mechanism walks backward, no separate undo path.
(06)PR Preview Environments
Multidev environments per pull request
For work that warrants a stakeholder review URL — a redesign branch, a migration phase mid-flight, a customer demo build — Pantheon's Next.js platform supports per-branch multidev environments. Each one is fully isolated: its own URL, its own Secrets bucket, its own CDN.
The diagram traces a typical pull-request lifecycle. A feature branch is pushed; Pantheon spins up a multidev environment with its own URL; stakeholders review the change on a real, production-like build; the PR merges to main; the multidev is torn down. The whole loop runs without blocking the trunk and without two reviews colliding on the same environment — the same operational model that the team has used for years across other Pantheon platforms, applied to Next.js.
