Deploy Strategy and Branch Policy

This document describes the FantasyWiki Cloudflare deployment strategy across local, QA (dev), and production (master) environments.

---

Branch Policy

Branch	Trigger	Deploy	Environments
master	push / PR	✅ Production	Prod Workers, Prod Pages, Prod D1
dev	push	✅ QA	backend-preview, frontend (dev branch), db-preview
feat/ (and the other Conventional types)	push / PR	❌ CI only	No deploy
renovate/	push	❌ Skip	No deploy (dependency updates)

---

CI/CD Workflows

1. Entry point (ci-cd.yml)

• Trigger: push, pull_request (forks included), workflow_dispatch
• Purpose: a dispatcher job decides which parts a change can have broken, then calls the reusable workflows below

2. Check (check.yml)

• Trigger: workflow_call from ci-cd.yml
• Purpose:
  • format, lint, typecheck, audit and every test suite, on all branches
  • the backend suite as a matrix, one leg per persistence target
  • no deployment logic, and no secret, so a fork's pull request may run it

3. Deploy (deploy.yml)

• Trigger: workflow_call, workflow_dispatch
• Purpose: deploy backend, frontend, and D1 migrations to explicit target environments
  • master: backend backend, Pages project frontend, D1 db
  • dev: backend backend-preview, Pages project frontend, D1 db-preview

4. Release (release.yml)

• Trigger: workflow_call from ci-cd.yml, on a push to master, after the production deploy succeeds
• Purpose: compute the next version from the Conventional Commits since the last one, tag it, and publish a GitHub release; the collector image is then tagged with the same version. See Release Process.

---

Cloudflare Environments

Production (master)

• Backend Worker: backend (luca0patrignani.workers.dev)
• Frontend Pages: frontend (fantasywiki.pages.dev)
• D1 Database: production database (db)
• Main vars:
  • FRONTEND_URL=fantasywiki.pages.dev
  • VITE_BACKEND_URL=luca0patrignani.workers.dev

QA (dev)

• Backend Worker: backend-preview
• Frontend Pages: frontend (dev.fantasywiki.pages.dev)
• D1 Database: preview database (db-preview)
• Main vars:
  • FRONTEND_URL=dev.fantasywiki.pages.dev
  • VITE_BACKEND_URL=backend-preview.luca0patrignani.workers.dev

Local

• Backend: wrangler dev (localhost:8787)
• Frontend: npm run dev (localhost:5173)
• D1: local SQLite (.wrangler/state/v3/d1/)

---

Required GitHub Secrets

Secret	Description
CLOUDFLARE_API_TOKEN	Cloudflare API token
CLOUDFLARE_ACCOUNT_ID	Cloudflare account ID
CLOUDFLARE_D1_MIGRATION_RUNNER_SECRET	Token used for production D1 migrations

---

QA Setup Procedure

1. Create Preview D1 Database

npx wrangler d1 create db-preview --remote

Set the returned database_id in backend/wrangler.jsonc under env.preview.d1_databases[0].database_id.

2. Apply preview migrations

cd backend
npx wrangler d1 migrations create db-preview init
npx wrangler d1 migrations apply db-preview --remote

3. Test QA Deployment

git push origin dev

Then verify the deploy.yml workflow in GitHub Actions.

---

Rollback and Debug

Production Rollback

git revert <commit-hash>
git push origin master

QA D1 Debug Query

npx wrangler d1 execute db-preview "SELECT * FROM users;" --remote

Workflow Logs

https://github.com/luca0patrignani/FantasyWiki/actions

---

D1 Binding Notes

The db binding is declared in Worker configuration and injected by Wrangler at runtime. In backend code:

type Bindings = {
  db: D1Database;
  // ...
};

const app = new Hono<{ Bindings: Bindings }>();

c.env.db resolves to the correct database for each environment.

Related

• Dev Branch & QA Deployment
• Setup QA Deploy
• Local Development Setup
• Development Process: how a change reaches a deploying branch
• Release Process: the version cut after a production deploy