How it works

From a commit to a verified site.

Git is the source of truth. The Narrative service is a build-and-deploy machine attached to it, so no laptop has to be in the loop.

Illustration: the empty iron bed of an old letterpress with a clean blank sheet laid on it, a heavy lever and roller above, one red lamp in the dark workshop.

The pipeline

Four steps, the same every time

Content, templates, and settings live in each site's repository. The service holds a registry and build history, and nothing it stores is the only copy of anything.

Push
A commit lands on the staging branch. It can come from an editor, the command line, an MCP call, or the web app, and every one of them is a git commit with the acting person as author.
Build
A verified webhook queues a build. Builds of the same site and stage run one at a time, because they share an output folder and a cache. Different sites render in parallel.
Verify
After the deploy, Narrative checks the live site. A failed check fails the build, and the report stays in the build history.
Live
Promote merges staging into production and deploys it. Rollback is a revert, so history stays append-only.

One pipeline

Four doorways, one pipeline

A git push, a command, an MCP call, and a button in the web app all invoke the same server-side pipeline. Only the recorded trigger differs.

Git push

The webhook is checked with an HMAC signature before it queues anything.

Command line

narrative deploy, promote, rollback, status, and doctor. It installs with pipx.

MCP

Twenty-six tools cover sites, members, content, builds, deploys, promotes, and rollbacks.

Web app

Sites, content, and build history in one place, with each edit committed to git.

Verified deploys

What Narrative checks after a deploy

These checks used to be a manual routine. Narrative runs them for every deploy and keeps the result with the build.

What Narrative checks after a deploy
The page responds	The home page of the live site answers with a good status.
Expected content	A marker that should be in the page is there, so a blank or wrong deploy is caught.
Staging is noindex	A staging site is marked so search engines stay away, and production is not.
No preview token leaks	A scan of the production output finds no preview access key.

A gated staging site still verifies. The checker signs in through the VelvetRope gate the same way a visitor would.

Promote and roll back

Merge to ship, revert to undo

Promoting is a merge of staging into the production branch, with the full history kept. Rolling back is a revert commit, never a force-push, so a rollback can itself be undone.

A site in another AWS account deploys through a role Narrative assumes with an ExternalId for that account. A person's sign-in is never used.

Content can wait for its moment. Put a publish_at date in front matter, and a scheduler checks every site each minute and publishes what is due.

Build history

Every build keeps its story

Each build records its stage, status, page count, what triggered it, the commit it built, how long it took, and its verification report. Open a build in the web app to read its log.