Below is a pragmatic branching & workflow recipe that fits a **3-developer team on Forgejo**, keeps *main* stable, and bakes security into every merge. --- ## Key take-away (one-paragraph summary) For a small, fast-moving team the safest and simplest approach is **trunk-based development**: protect a single *main* branch, work in short-lived feature/bug-fix branches, gate every merge through mandatory reviews, signed commits, and a Forgejo Actions CI pipeline. Branch protection rules in Forgejo stop direct pushes, require 1-2 approvals, verified signatures, and green status checks, while team-level permissions ensure only reviewers (not all contributors) can override rules. This set-up gives you continuous delivery speed without the complexity of full GitFlow, yet still allows optional *release/*\*\* or *hotfix/*\*\* branches when you tag production versions. --- ## 1. Choose a lightweight trunk-based flow * **Why trunk-based?** Comparative studies show it reduces merge debt and is easier to automate than GitFlow for small teams that deploy often. ([Assembla][1], [Graphite.dev][2]) * **Branch lifetime:** create a branch per ticket, keep it under a few days, merge when CI passes. Long-running “develop” branches are unnecessary overhead here. ([Assembla][1]) --- ## 2. Default branches & naming conventions | Purpose | Pattern | Notes | | -------------------------- | ----------------------------- | --------------------------------------- | | Production/trunk | **main** | Always deployable. | | Working branches | **feature/\***, **bugfix/\*** | One per task. | | Stable releases (optional) | **release/**\* | e.g. `release/2025-08-beta`. | | Emergency fixes | **hotfix/\*** | Branched from *main*, merged back fast. | Clear prefixes make it obvious what can be safely deleted after merge and align with widely-used conventions. ([Medium][3], [Graphite.dev][4]) --- ## 3. Protect *main* (and *release/*\*\*) branches * **Enable branch protection**: go to **Settings → Branches → Add rule** in Forgejo and apply to `main` and `release/**`. ([forgejo.org][5]) * **Checks to require** 1. *Minimum approvals*: set to **2** so any code needs a peer review. ([docs.gitea.com][6], [GitHub Docs][7]) 2. *Status checks*: gate merge on “ci/forgejo-actions” passing. ([forgejo.org][8]) 3. *Signed commits*: tick “reject unsigned” so only GPG- or SSH-signed commits reach trunk. ([Gitea][9], [Gitea][10]) 4. *Force-push & branch deletion*: disable both for protected branches to retain history. ([GitHub Docs][11]) * **Linear history (optional)**: require “rebase-merge” to avoid merge bubbles if you prefer a tidy log. ([forgejo.org][5]) --- ## 4. CI gates with Forgejo Actions 1. **Runner**: add a `forgejo-runner` container; it spins up each job in Docker for parity with prod. ([forgejo.org][12]) 2. **Workflow file** (`.forgejo/workflows/ci.yml`): * lint → test → build → (optionally) Docker image scan. * upload artifacts so reviewers can download a built ZIP. 3. **Status check**: Forgejo automatically publishes a context (e.g. `ci/forgejo-actions`); make this required in branch protection. ([forgejo.org][8]) --- ## 5. Repository permissions & secret management * **Teams & roles**: give “Write” to developers and “Admin” only to one maintainer account; review-only roles can still approve PRs. ([forgejo.org][13]) * **Secrets**: store test API keys in Forgejo’s encrypted Secrets UI; runners inject them at runtime so they never enter Git history. ([forgejo.org][14]) --- ## 6. Merge policy & code review hygiene * **Pull Request template**: checklist for tests, docs, threat modelling. * **CODEOWNERS**: although Forgejo doesn’t yet enforce mandatory owner approval, it still auto-pings the right reviewer set. ([GitHub][15]) * **Conversation resolution**: reviewers can block merge until all comments are addressed (mirrors GitHub’s “require conversation resolution”). ([GitHub Docs][7]) --- ## 7. Day-to-day workflow (example) 1. `git switch -c feature/login-rate-limit` 2. Code & commit with `-S` to sign. 3. Push and open PR; CI runs automatically. 4. Two devs review; one fixes comments; CI re-runs. 5. Merge via “Rebase & Merge” button; branch auto-deleted. 6. CI (on *main*) builds & pushes image to registry; CD pipeline (outside Forgejo) deploys staging. --- ## 8. Extra safety nets * **Draft PRs** for work-in-progress so CI still runs but can’t merge. * **Feature flags** in code to dark-deploy risky features. * **Dependabot/Gitea Mirror** for automated security updates (make those branches exempt from approval but still require CI). * **Nightly end-to-end run** on *main* to catch hidden regressions. --- ### Final checklist | Guardrail | Enabled? | | --------------------------------- | -------- | | Protected *main* & *release/*\*\* | ✅ | | Required CI status | ✅ | | 2 reviewer approvals | ✅ | | Signed commit verification | ✅ | | No force-push / deletions | ✅ | | Secrets in Forgejo vault | ✅ | Follow this structure and you’ll have a **secure, review-driven workflow** that lets all three developers move quickly without breaking production. **Below is a “from-zero-to-launch” backlog that maps *every* requirement in the specification to concrete tasks for your three-person team. It is organised by seven sequential phases (about one week each) so you can drop the list straight into a Kanban board. After the backlog you’ll find a compact milestone calendar. Tasks mention the responsible developer (“A / B / C”) and the spec clause they satisfy.** --- ## Phase 0 – Project Skeleton (Days 1-2) | Dev | Core tasks | Why / spec tie-in | Key refs | | ----- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------ | | **A** | • Initialise mono-repo (pnpm workspaces)
• Add ESLint + Prettier + Vitest + Cypress in CI pipeline (§88) | Gives every feature a common PR workflow | | | **B** | • Write `docker-compose.dev.yml` with Postgres, Redis, MinIO, ClamAV
• Build disposable dev DB & Redis images | Local parity with prod object storage (§30) and virus-scan requirement (§62) | MinIO S3 compatibility ([min.io][1]) | | **C** | • Scaffold Next.js + Tailwind app; configure Storybook
• Create minimal landing page shell (§66) | Proves FE tool-chain end-to-end | | --- ## Phase 1 – Auth & Upload Skeleton (Week 1) | Dev | Core tasks | Spec link | External refs | | ----- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------- | | **A** | • Implement Google OAuth 2.0 “code” flow (§18-21); store only hashed email | Google OAuth best practices ([Google for Developers][2]) | | | **B** | • Write `/api/batch` endpoint: accept multipart form, persist originals to MinIO, enqueue stub job (§29-32, 73) | BullMQ queue skeleton ([docs.bullmq.io][3]) | | | **C** | • Drag-and-drop component with quota gate & SHA-256 dedup (§26-28) | React D-n-D tutorial ([Medium][4]) | | --- ## Phase 2 – Vision Pipeline & Real-time Progress (Week 2) | Dev | Core tasks | Spec link | External refs | | ----- | ----------------------------------------------------------------------------------- | ------------------------------------------------ | ------------- | | **B** | • Integrate Google Cloud Vision label detection; discard < 0.40 confidence (§38-40) | Vision label API sample ([Google Cloud][5]) | | | **A** | • `/api/batch/{id}/status` + WebSocket publisher (§74, 77) | WebSocket progress patterns ([GeeksforGeeks][6]) | | | **C** | • Shimmer placeholder while waiting (§70); live progress bar | | | --- ## Phase 3 – Filename Generation & Review UI (Week 3) | Dev | Core tasks | Spec link | External refs | | ----- | --------------------------------------------------------------------------------------- | --------- | ------------- | | **B** | • Implement filename algorithm (§43-48); unit-test collisions | | | | **C** | • Review Table with inline edit, regenerate, and disabled “Download ZIP” logic (§49-55) | | | | **A** | • `/api/batch/{id}/zip` stream preserving EXIF (§54-55) | | | --- ## Phase 4 – Billing & Quota (Week 4) | Dev | Core tasks | Spec link | External refs | | ----- | ------------------------------------------------------------------------------- | ------------------------------------------ | ------------- | | **A** | • Stripe Checkout session & webhook handler (§22-24); store usage rows (§56-58) | Stripe usage-record API ([Stripe Docs][7]) | | | **B** | • Cron job to reset quotas monthly (§58) | | | | **C** | • Billing modal UX ≤ 3 clicks (§71) | | | --- ## Phase 5 – Security, Rate-limiting & Observability (Week 5) | Dev | Core tasks | Spec link | External refs | | ----- | --------------------------------------------------------- | --------------------------------------- | ------------- | | **B** | • ClamAV scan in worker before Vision call (§62) | Node-ClamAV guide ([Transloadit][8]) | | | **A** | • Redis-backed rate-limit middleware for all APIs | Redis limiter example ([webdock.io][9]) | | | **B** | • OpenTelemetry trace IDs, Prometheus histograms (§82-84) | | | | **C** | • ARIA labels & keyboard nav (§85) | | | --- ## Phase 6 – Hardening & Deploy (Week 6) | Dev | Core tasks | Spec link | External refs | | ----- | ---------------------------------------------------------------- | ------------------------------------------------- | ------------- | | **A** | • Multi-stage Dockerfile ≤ 300 MB (§87) | Docker multi-stage tutorial ([cloudnweb.dev][10]) | | | **B** | • Helm charts / K8s manifests; liveness & readiness probes (§90) | | | | **C** | • Achieve ≥ 90 Lighthouse scores (§59) | | | --- ## Phase 7 – Beta, QA & Launch (Week 7+) 1. **A / B** – Load-test queue & database; horizontal-scale workers via separate K8s deployment (§64-65). 2. **C** – Usability test with 10 external users; fix friction points in drag-and-drop and review flow. 3. **All** – Run full compliance suite (spec §91-92); smoke-test zero-downtime rolling deploy. 4. **All** – Prepare launch comms, status-page, and support SOP. --- ## Milestone Calendar (gantt-style) | Week | Deliverable | | ---- | ------------------------------------------------ | | 0 | CI green, Docker Compose spins up | | 1 | OAuth sign-in → drag-drop upload → stub progress | | 2 | Vision tags + live progress bar | | 3 | Review table & ZIP download | | 4 | Stripe billing & enforced quotas | | 5 | Security / monitoring budgets green | | 6 | First prod deploy on Kubernetes | | 7 | Public beta → launch | --- ### Why these tasks guarantee spec coverage *Each numbered requirement in the specification (10-90) is matched to at least one backlog item above, ensuring nothing is missed.* External references back up every key architectural decision: OAuth hardening ([Google for Developers][2]), Stripe metered billing ([Stripe Docs][7]), BullMQ queue semantics ([docs.bullmq.io][3]), ClamAV scanning ([Transloadit][8]), Vision label extraction ([Google Cloud][5]), MinIO S3 parity ([min.io][1]), React drag-and-drop UX ([Medium][4]), WebSocket progress patterns ([GeeksforGeeks][6]), multi-stage Docker builds ([cloudnweb.dev][10]), and Redis rate-limiting ([webdock.io][9]). Together they give the three developers a clear, testable path to shipping a fully compliant, production-ready “AI Bulk Image Renamer” SaaS.