> ## Documentation Index
> Fetch the complete documentation index at: https://docs.theroyalglow.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Git Workflow

> Branch strategy, CI/CD pipeline, commit conventions, and database-per-environment for Royal Glow.

# Git Workflow

<Info>
  **In one line:** Single-developer workflow with four persistent branches
  (`dev → test → pprd → prod`), each mapped to a Neon DB branch. Gates get
  stricter at every stage, **no direct pushes to `prod`**, and commits follow
  Conventional Commits.
</Info>

## Branch Strategy

Single developer workflow with **4 persistent branches**, each mapped to an environment:

| Branch | Environment    | Neon Branch | Purpose                            |
| ------ | -------------- | ----------- | ---------------------------------- |
| `prod` | Production     | `prod`      | Live traffic — real customers      |
| `pprd` | Pre-production | `pprd`      | Final validation before going live |
| `test` | Test / QA      | `test`      | Integration tests, CI              |
| `dev`  | Development    | `dev`       | Active development work            |

**Flow direction:** `dev → test → pprd → prod`

Work happens on `dev` (or short-lived feature branches off `dev`). Code must pass all CI gates at each stage before being promoted. **No direct pushes to `prod`.**

## Branch Protection Rules

| Branch | Protection                                                     |
| ------ | -------------------------------------------------------------- |
| `prod` | Require manual approval + all CI checks passing                |
| `pprd` | Require all CI checks (lint, test, Playwright, Lighthouse, k6) |
| `test` | Require lint + unit + integration + Playwright + Lighthouse CI |
| `dev`  | Require lint + type check + unit tests                         |

## Database Per Environment

All environments use **Neon DB branches** within a single Neon project — no separate paid projects needed.

| Branch | Neon Branch | Reset Policy                                |
| ------ | ----------- | ------------------------------------------- |
| `prod` | `prod`      | Never reset — live customer data            |
| `pprd` | `pprd`      | Auto-reset daily from `prod` + PII stripped |
| `test` | `test`      | Wiped and reseeded before each CI run       |
| `dev`  | `dev`       | Developer sandbox, scales to zero when idle |

## Prod → pprd Data Replication

Every 24 hours, a GitHub Actions cron job uses the **Neon Branch Reset API** to sync pprd from prod.

<Steps>
  <Step title="Reset the branch">
    Call the Neon API to reset the `pprd` branch from `prod`.
  </Step>

  <Step title="Anonymise PII">
    Run a PII anonymisation script — names, phone numbers, and emails are replaced with fake data.
  </Step>

  <Step title="Ready for UAT">
    pprd is now a clean, realistic copy of prod without real customer data.
  </Step>
</Steps>

This is faster than `pg_dump` / `pg_restore` because Neon branching is a near-instant copy-on-write operation at the storage layer.

```yaml theme={null}
# .github/workflows/replicate-prod-to-pprd.yml
on:
  schedule:
    - cron: '0 1 * * *'  # 1 AM UTC daily
```

## CI/CD Pipeline

Gates are cumulative — each stage adds checks on top of the previous one.

<Tabs>
  <Tab title="PR to dev">
    ```text theme={null}
    ✅ Lint + Format (Biome + Ultracite)
    ✅ Type check (tsc --noEmit)
    ✅ Unit tests (Vitest)
    ```
  </Tab>

  <Tab title="PR to test">
    ```text theme={null}
    ✅ Lint + Format
    ✅ Type check
    ✅ Unit tests
    ✅ Integration tests (Neon test branch)
    ✅ Playwright E2E tests
    ✅ Lighthouse CI (performance ≥ 95; accessibility, best practices, SEO = 100)
    ```
  </Tab>

  <Tab title="PR to pprd">
    ```text theme={null}
    ✅ All tests from test branch
    ✅ k6 load test against pprd environment
    ✅ OWASP ZAP security scan
    ✅ Smoke test Playwright suite
    ```
  </Tab>

  <Tab title="PR to prod">
    ```text theme={null}
    ✅ All CI gates passing
    ✅ Manual approval required
    🚀 Deploy to Cloudflare Workers (OpenNext adapter)
    ```
  </Tab>
</Tabs>

## Commit Conventions

Use **Conventional Commits** for clean history and automatic changelog generation:

```text theme={null}
feat: add booking confirmation email
fix: correct availability calculation for same-day slots
chore: update dependencies
docs: update testing plan
test: add E2E test for admin booking flow
refactor: extract pricing logic to service layer
perf: cache service catalog in Cloudflare KV
security: add rate limiting to /api/leads
```

## Pre-Commit Hooks

Every `git commit` automatically runs **Biome** lint + format on staged files via Husky + lint-staged:

```bash theme={null}
# What runs on every commit (~200ms):
biome check --write --staged
```

This catches formatting issues and obvious lint errors **before they ever reach CI** — saving pipeline minutes and avoiding "fix lint" commits.

## Secrets Management

| Secret                            | Where Stored                     |
| --------------------------------- | -------------------------------- |
| `DATABASE_URL_PROD/PPRD/TEST/DEV` | GitHub Actions encrypted secrets |
| `DATABASE_URL_UNPOOLED_*`         | GitHub Actions encrypted secrets |
| `RESEND_API_KEY`                  | GitHub Actions encrypted secret  |
| `BETTER_AUTH_SECRET`              | GitHub Actions encrypted secret  |
| `GOOGLE_OAUTH_CLIENT_ID/SECRET`   | GitHub Actions encrypted secret  |

<Warning>
  **Never commit secrets to git.** Use `.env.local` locally (gitignored) and
  GitHub Actions secrets in CI.
</Warning>

## Deployment

<Tabs>
  <Tab title="Render (today)">
    * `rgss-web` (`theroyalglow.in`), `rgss-admin` (`admin.theroyalglow.in`) and `rgss-cms` (`cms.theroyalglow.in`)
    * Auto-deploy on push to `prod`, built and started with Bun (`next build` → `next start`)
    * Zero-downtime deploys via Render's rolling restart
    * Rollback: redeploy a previous commit from the Render dashboard
  </Tab>

  <Tab title="AWS (target)">
    * `apps/web` and `apps/admin` only: Lambda (ARM64) + CloudFront + S3 per app, via SST. CMS stays on Render; invoicing stays on Cloud Run
    * `deploy-aws.yml` on push to `prod`: GitHub OIDC → `bunx sst deploy --stage production` → health check
    * Rollback: redeploy a previous ref (3–5 min). PostHog feature flags are the instant kill switch
    * Full runbook: `M2AWS.md`
  </Tab>
</Tabs>

## Weekly Backup

Every Sunday at 2 AM UTC, a GitHub Actions workflow:

<Steps>
  <Step title="Dump">
    Run `pg_dump` against the Neon `prod` branch.
  </Step>

  <Step title="Upload">
    Upload the compressed dump to Cloudflare R2 (`backups/weekly/`).
  </Step>

  <Step title="Retain">
    Keep 8 weeks of backups.
  </Step>

  <Step title="Heartbeat">
    Ping the BetterStack heartbeat on success.
  </Step>
</Steps>

## Related

* [Testing](/docs/testing) — Full CI gate specifications
* [Deployment](/docs/deployment) — Platform configuration details
* [Environment Variables](/docs/environment-variables) — All secrets and their purpose


## Related topics

- [Getting Started](/content/docs/getting-started.md)
- [Data Seeding](/content/docs/data-seeding.md)
- [Deployment](/content/docs/deployment.md)
- [Environment Variables](/content/docs/environment-variables.md)
- [Background Jobs](/content/docs/background-jobs.md)