CI/CD

canonical term: deployment workflow

Doc Status: Current operating model | This page describes the GitHub Actions flow for future feature work. Production deploys from main, not from a developer laptop.

Why This Matters

House of Legends runs public booking, operations, payment, and staff workflows from one codebase. A change should move through review, preview, and production in a predictable path so backend contracts, frontend generated clients, Turnstile, and Cloudflare Workers stay aligned. The deployment source of truth is GitHub Actions. Local machines are for development and emergency diagnostics, not normal production releases.

Branch Model

Branch	Purpose	Deploy Target
`feature/*`	Short-lived feature work	No automatic deploy
`dev`	Integration validation	CI only until isolated staging exists
`main`	Production release branch	`Production` environment

Use dev as the place where multiple features meet before production. Use main only for code that is ready to ship.

Feature Development Flow

Start from dev

Create a short-lived feature branch from the latest dev.

git fetch origin
git switch dev
git pull origin dev
git switch -c feature/<short-feature-name>

Make the change locally

Keep changes scoped. Backend API changes update Hono schemas/routes first, then regenerate OpenAPI and Fern clients.

pnpm --filter @hol/hono generate
pnpm --filter @hol/client generate

Verify before opening a PR

Use the same non-test checks expected by CI.

pnpm --filter @hol/hono typecheck
pnpm --filter @hol/hono lint
pnpm --filter @hol/frontend typecheck
pnpm --filter @hol/frontend lint
pnpm --filter @hol/mintlify build

Open a PR into dev

The first PR target is dev, not main.

gh pr create --base dev --head feature/<short-feature-name>

Merge to dev after CI passes

A merge to dev triggers the CI workflow. This is the shared integration gate before production promotion.

Promote dev to main

After preview verification, open a PR from dev to main.

gh pr create --base main --head dev --title "Release: promote dev to production"

Production deploy

A merge to main triggers CI again. If CI succeeds, GitHub Actions deploys the Production environment.

Future Feature Lifecycle

Every later feature should follow the same promotion path unless it is an emergency production hotfix.

Stage	Owner Action	System Action	Result
Start	Branch from latest `dev`	No deploy	Isolated feature work
Review	Open PR into `dev`	CI runs API, client, frontend, and docs checks	Contract and build issues are caught before preview
Preview	Merge PR into `dev`	CI runs again	Integration issues are caught before production
Promote	Open PR from `dev` into `main`	CI runs on the release PR	Production release is reviewed as a batch
Release	Merge to `main`	CI runs again, then deploys `Production`	Live site updates from GitHub Actions

Do not merge feature branches directly to main. Skipping dev also skips the shared preview step, which is where frontend/backend contract issues and deployment configuration problems should be found.

Backend Feature Rules

Backend changes must keep the generated contract in sync before a PR is opened.

pnpm --filter @hol/hono generate
pnpm --filter @hol/client generate
git diff -- apps/hono/generated packages/client

If the generated OpenAPI or Fern client changes, commit those generated artifacts with the backend change. The frontend should consume the generated client rather than redefining API request or response shapes.

Frontend Feature Rules

Frontend features should call Hono through existing hooks and generated client code. UI components should not own API calls or backend business rules.

pnpm --filter @hol/frontend typecheck
pnpm --filter @hol/frontend lint

When a frontend change depends on a new Hono response field, merge the backend contract and generated client into the same feature branch before opening the PR to dev.

Docs Feature Rules

Docs changes go through the same branch flow. If the docs describe a deployed behavior, verify the implementation first.

pnpm --filter @hol/mintlify build

Release Types

Release Type	Branch Path	Notes
Normal feature	`feature/*` → `dev` → `main`	Default path for product and backend work
Documentation-only	`docs/*` → `dev` → `main`	Still uses CI so navigation/build issues are caught
Backend contract	`feature/*` → `dev` → `main`	Must include OpenAPI and Fern regeneration
Payment change	`feature/*` → `dev` → `main`	Requires production payment verification after release
Emergency hotfix	`hotfix/*` → `main`, then back-merge to `dev`	Use only when production is actively broken

Payment, reservation, seeding, migration, and reset changes are higher risk. CI/CD may deploy code, but it must not silently run data-changing operations. Operator-triggered database actions stay separate from deployment.

What CI Checks

The CI workflow should run on pull requests and pushes for both dev and main.

Area	Command
Hono contract generation	`pnpm --filter @hol/hono generate`
Fern client generation	`pnpm --filter @hol/client generate`
Generated artifact check	`git diff --exit-code`
Hono typecheck	`pnpm --filter @hol/hono typecheck`
Hono lint	`pnpm --filter @hol/hono lint`
Client typecheck/build	`pnpm --filter @hol/client typecheck` and `pnpm --filter @hol/client build`
Frontend typecheck/lint	`pnpm --filter @hol/frontend typecheck` and `pnpm --filter @hol/frontend lint`
Docs build	`pnpm --filter @hol/mintlify build`

Automated tests are currently archived and disabled in this repository. Do not add test runners to CI until the repo policy changes.

What Deploys

Git event	GitHub environment	Cloudflare target
CI succeeds on `dev`	None	Integration validation only
CI succeeds on `main`	`Production`	Live Cloudflare Workers and Pages
Manual dispatch	`Production`	Emergency/operator-controlled production deploy

The deploy workflow owns:

Hono API Worker
Frontend Worker/assets
Videos Worker
Mintlify docs Pages deployment

The deploy workflow must not run seed commands, database reset commands, or migration commands.

dev must not deploy to the existing Cloudflare production Worker names. A real Preview deployment requires separate staging Worker names, database/storage bindings, secrets, domains, and payment callback rules.

Secrets

GitHub Actions needs deployment and frontend build values:

CLOUDFLARE_API_TOKEN
CLOUDFLARE_ACCOUNT_ID
NEXT_PUBLIC_TURNSTILE_SITE_KEY

Cloudflare Worker secrets stay in Cloudflare:

TURNSTILE_SECRET_KEY
BETTER_AUTH_SECRET
SUPERUSER_API_TOKEN

Do not commit secrets to the repository. Do not put TURNSTILE_SECRET_KEY into GitHub unless a future workflow explicitly rotates Worker secrets. The normal deployment workflow only needs the public Turnstile site key for the frontend build.

Operational Rules

Feature branches merge into dev.
dev validates integration before production.
main is production-only.
Production deploys happen from GitHub Actions after CI succeeds.
Local wrangler deploy is emergency-only and should be reported when used.
Seeder, migration, and reset commands are manual operator actions, not deploy steps.
Payment-flow changes still require real production verification after deployment.

Domains & Deployment — domain routing and environment URLs
OnePay — payment gateway environment configuration

​CI/CD

​Why This Matters

​Branch Model

​Feature Development Flow

​Future Feature Lifecycle

​Backend Feature Rules

​Frontend Feature Rules

​Docs Feature Rules

​Release Types

​What CI Checks

​What Deploys

​Secrets

​Operational Rules

​Related Pages

CI/CD

Why This Matters

Branch Model

Feature Development Flow

Future Feature Lifecycle

Backend Feature Rules

Frontend Feature Rules

Docs Feature Rules

Release Types

What CI Checks

What Deploys

Secrets

Operational Rules

Related Pages