This repository follows the estate’s branch-per-environment model — see
platform-db/.github/environments.json, the canonical map.
| Branch | Environment | Role |
|---|---|---|
main |
development | Where contracts land. GitHub Pages publishes from here |
staging |
staging | The staging source of truth — promoted from main with the release |
features/0.2.0-nexusflow |
feature-testing | Phase-two source of truth |
Promotion is a fast-forward push of the environment’s branch to the release commit. A non-fast-forward
means the environment branch carries something main does not; reconcile it, never force.
Do not delete a branch without checking that no workflow triggers on it, it is in no
environments.json, it is not an open PR head, and it is not the GitHub Pages source. An environment
branch can look like a stale feature branch — features/0.2.0-nexusflow is named for a shipped release
and only moves when a nightly merge runs.
This repository builds a navigable contract site, one per environment, deployed to GKE. Each environment’s site is built from that environment’s branch, so it always shows the contracts that environment is serving — which is the point of deploying one per environment rather than a single site for the estate.
| Environment | Branch | URL | Namespace |
|---|---|---|---|
| development | main |
https://apis.development.cloud.gradera.ai/docs |
platform-development |
| staging | staging |
https://apis.staging.cloud.gradera.ai/docs |
platform-staging |
| feature-testing | features/0.2.0-nexusflow |
https://apis.phase-two.cloud.gradera.ai/docs |
platform-phase-two |
The contracts sit on the same hostname as the APIs they describe, under /docs. No new DNS, and
the relationship between a contract and its service is visible in the URL.
cd site && npm install
DOCS_ENVIRONMENT=development npm run build # writes ../dist
docker build --build-arg DOCS_ENVIRONMENT=staging -t platform-api-docs:local .
docker run --rm -p 6100:6100 platform-api-docs:local
# → http://localhost:6100/docs/
Every page is generated: one per contract, rendered with Redoc, plus a landing page grouped by area.
The raw YAML is served beside each page for Postman, codegen and CI, as application/yaml. Every
contract answers on exactly one URL: sos-admin and tenant-management each published a
latest.yaml alongside v1.yaml until 2026-09-18, and the builder collapsed the pair into one card
whenever the two files were byte-identical — which is precisely why nobody noticed when they stopped
being identical.
GET /docs/health returns the environment, branch and commit the site was built from — which is also
the readiness probe.
Pages previously served this repository, from an unmerged branch. The per-environment sites replace it: a single public site cannot show four environments’ contracts, and the one that existed was showing none of them accurately.