Environments and deployments

UnitOps runs in two environments. Both are complete stacks; staging is the rehearsal room for production.

The environments

	Staging	Production
App	https://dev-staging-unitops.datalakehouse.io	https://unitops.datalakehouse.io
Docs	https://unitops-docs-staging.pages.dev	https://docs.unitops.com
API	https://staging-api.unitops.datalakehouse.io	https://api.unitops.datalakehouse.io
Docs project	unitops-docs-staging	unitops-docs
Deploys from	develop	main

Branch strategy

feature branch  ->  develop  ->  main
                    staging      production

• develop is the integration branch. Merging into it deploys staging.
• main is the release branch. Merging into it deploys production.
• Feature branches follow dlhfeature/<feature-concept-name> and are cut from develop.

Every pull request runs CI, and pull requests against the docs site also publish a temporary preview URL.

What deploys where

Piece	Mechanism
Web app	Firebase App Hosting rolls out automatically on a push to the live branch of dlh-unitops-ai
API	GitHub Actions builds the image and deploys to GKE Autopilot in the environment's project
Docs	GitHub Actions builds this Docusaurus site and deploys it to Cloudflare Pages in the environment's project

How the docs site is served

The docs are a separate static site deployed to Cloudflare Pages. The production project serves the custom domain docs.unitops.com, and the staging project serves unitops-docs-staging.pages.dev.

https://docs.unitops.com/...
  -> Cloudflare Pages project `unitops-docs`

https://unitops-docs-staging.pages.dev/...
  -> Cloudflare Pages project `unitops-docs-staging`

docusaurus.config.ts builds with baseUrl / by default, trailingSlash: true, and environment-aware SITE_URL and APP_URL values. scripts/stage-pages.mjs copies the build into public_dist/ and writes Cloudflare _headers and _redirects files.

Publishing a documentation change

1. Cut a branch from develop in datalakehouse/unitops-docs.
2. Edit or add a Markdown file under docs/.
3. Open a pull request against develop. CI typechecks and builds the site, and the preview workflow comments a temporary URL on the pull request.
4. Merge into develop. Staging docs update automatically.
5. When you are happy with staging, open a pull request from develop into main and merge it. Production docs update automatically.

Broken internal links fail the build, so a merged pull request cannot publish a dead link.

One-time Cloudflare setup

An operator with access to the Cloudflare dashboard and the GitHub repository settings does this once.

1. Create the Cloudflare Pages projects:

   • unitops-docs for production (main)
   • unitops-docs-staging for staging (develop)

2. Add the GitHub repository secrets:

   Secret	Description
   CLOUDFLARE_API_TOKEN	API token with Cloudflare Pages:Edit permission
   CLOUDFLARE_ACCOUNT_ID	Your Cloudflare account ID

   If you use the dashboard Git integration instead of the workflows, set the build command to npm run build:pages and the output directory to public_dist.

3. Attach the custom domain docs.unitops.com to the production project.

Rollback

Roll back a Cloudflare Pages deployment from the project's deployment list in the dashboard, or revert the commit on the deploying branch and let CI publish again. Docs and application deploys are independent, so rolling back one does not affect the other.