Ship and operate

A change travels one road. It starts on a branch from integration, passes every gate on a pull request, and is merged by the owner, which deploys staging. A release merges integration into main, which runs the gated production deploy: every required check on the exact commit, the API and the website proven before anyone can reach them, then promotion, then the tag. The app follows from that tag. Nobody deploys by hand, and every step can be undone.

Poster 11 — the delivery pipeline: from a branch to staging, to a release on main, to production and the App Store, every step gated by CI, verified by commit, and reversible · open full size

1. Branch and run the local gates. Branch feat/… or fix/… from integration, the trunk. Before opening a pull request run make ci (versions, dataset check, the server tests, the contract, the docs gates) so the pull request’s checks are a confirmation, not a discovery.
2. The pull request. Every workflow on the CI gates map runs on the commit: web-ci, scripture-integrity, version-consistency, security, pr-hygiene, e2e and the docs job. A change to scripture handling, search, verification or the dataset pin completes the scripture-safety checklist in the template.
3. Squash merge. Feature and fix pull requests are squash-merged into integration so the trunk carries one clean commit per change. Only the owner merges (the ruleset requires CODEOWNERS); the engineer hands over the exact command.
4. deploy-staging. The push runs deploy-staging: the gates job waits for the core checks and playwright on the commit, preflight checks the staging secrets, the API functions are generated from the pinned database (each context’s slice proven by the slicer), vercel build proves what each function bundles, the deployment is aliased to sggs-staging.vercel.app and the CDN cache is purged.
5. Verify staging, then a person looks. verify_functions.py checks every function’s /readyz reports this commit and exactly its contexts; the gateway probes prove each context answers through the real rewrites with its own X-Service; the web smoke runs; the whole golden contract passes through the gateway. Then the owner reviews the staging site, logged in to Vercel, before any release.
6. The release pull request. make release VERSION=X.Y.Z bumps the unified version everywhere and stubs the CHANGELOG section; a dataset change arrived earlier as a reviewed lock bump with a regenerated contract. The pull request goes from integration to main and is merged as a merge commit — never squashed — so main stays a descendant of integration.
7. gates, preflight, approve. deploy-production waits until every check the main ruleset requires, plus playwright, has succeeded on the exact merge commit; preflight proves every production secret exists; approve is an optional human click when the production-approval environment has reviewers. Nothing has been deployed yet.
8. The Render standby, verified by commit. deploy-api triggers the Render deploy hook with ref=SHA and waits until /api/health.commit equals the commit and the health checks are all true; verify-api then samples compositions and proves exact lines, present headings and 404 on the permanent comp_id gaps. Since 1.3.10 production’s /api is answered by the API functions in the web deployment; the Render API is kept deployed and proven as the standby. The web is untouched until this passes.
9. The web and the API functions, built unaliased and proven. vercel build and deploy with --skip-domain produce a deployment nobody can reach yet: the website and the API functions together. Its functions are checked at the commit, the golden contract is replayed against it and the @smoke tests run. A failure here leaves users on the previous deployment.
10. Promote — with a way back. vercel promote puts the deployment on gurbanisoul.com, the CDN cache is purged so no stale API body outlives its dataset, and the @smoke tests run against the public domain. If they fail, the job runs vercel rollback to the recorded previous deployment — the website and the API functions go back together — and opens an incident issue. Sending the API to the Render standby is a routing change in gateway/routes.json; a dataset rolls back by reverting the lock bump.
11. Tag, and the app follows. Only after a verified deploy does the release job create the tag vX.Y.Z and a GitHub Release from the CHANGELOG section. The app repository then vendors the contract at that tag, sets MARKETING_VERSION and uploads X.Y.Z (1) with CHANNEL=appstore; scripts/release/check_release_complete.py proves web, API and the binary report the same number from the same commit.
12. After the release. make verify-prod proves what production serves by commit identity. Every six hours the data canary proves the served scripture equals the pin at the origin and through the CDN and replays the golden contract; every fifteen minutes uptime probes /api/health and the App Store URLs. The wiki deploys through the same chain in deploy-docs.yml.

How it works

• Branching and delivery flowthe branch model, which pull requests squash and which merge, and why.
• Environmentslocal, staging and production side by side: hosts, the API, data, protection, who deploys.
• CI gateswhat every workflow and job proves, and which a merge requires (poster 10).
• Release processthe steps from a green integration to a tagged production release.

Runbooks

• Deploysthe CI-gated pipeline gate by gate, its secrets, and how to read a failed run.
• Rollbackthe website and the API together, the Render standby, a dataset, the app.
• Moving production to functionsthe per-context cut-over, gated on the performance baseline and the data canary.
• The docs sitekeeping docs.gurbanisoul.com honest: deploys, watchers, pins, reviews.
• Support inboxthe public support address and how mail to it is handled.
• Launch-notice sign-upthe sign-up on the landing page and its privacy rules.

The handbook

The rules behind all of this — the invariants, local setup, delivery and versioning, brand and domains, the release timeline — are the engineering handbook.