docs: document stripe branch and add propagate/CI support (#229)

* docs: document stripe branch and add propagate/CI support (#228)

Point main docs and README at the optional stripe branch, document the
merge recipe and conflict-prone files, and extend propagate.yml and
test.yml so stripe receives main updates and runs CI with dummy Stripe env.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(ci): keep Test workflow push triggers unfiltered

Narrowing push to main/stripe would drop CI on feature branches and
modal/hetzner; only extend pull_request targets for stripe.

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: chriscarrollsmith <chriscarrollsmith@gmail.com>

Author: 3 people

.github/workflows/propagate.yml

@@ -13,7 +13,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        branch: [modal, hetzner]
+        branch: [modal, hetzner, stripe]
     runs-on: ubuntu-latest
     steps:
       - name: Generate token
@@ -162,6 +162,101 @@ jobs:
             git push origin "$BRANCH"
           }
 
+          conflicts_are_stripe_overlay() {
+            [ "$BRANCH" = "stripe" ] || return 1
+
+            conflicts="$(unresolved_conflicts)"
+            [ -n "$conflicts" ] || return 1
+
+            while IFS= read -r file; do
+              case "$file" in
+                pyproject.toml|uv.lock) ;;
+                *) return 1 ;;
+              esac
+            done <<< "$conflicts"
+          }
+
+          add_stripe_dependency() {
+            python3 <<'PY'
+          from pathlib import Path
+          import subprocess
+          import tomllib
+
+          def is_stripe_dependency(dependency: str) -> bool:
+              return dependency.split(";", 1)[0].strip().lower().startswith("stripe")
+
+
+          def stripe_dependency_from_branch() -> str:
+              try:
+                  result = subprocess.run(
+                      ["git", "show", ":2:pyproject.toml"],
+                      check=True,
+                      capture_output=True,
+                      text=True,
+                  )
+              except subprocess.CalledProcessError:
+                  return "stripe>=15.3.0"
+
+              dependencies = tomllib.loads(result.stdout).get("project", {}).get("dependencies", [])
+              return next(
+                  (dependency for dependency in dependencies if is_stripe_dependency(dependency)),
+                  "stripe>=15.3.0",
+              )
+
+
+          path = Path("pyproject.toml")
+          text = path.read_text()
+          data = tomllib.loads(text)
+
+          dependencies = data.get("project", {}).get("dependencies", [])
+          if any(is_stripe_dependency(dependency) for dependency in dependencies):
+              raise SystemExit(0)
+
+          lines = text.splitlines()
+          start = next(
+              (index for index, line in enumerate(lines) if line.strip() == "dependencies = ["),
+              None,
+          )
+          if start is None:
+              raise SystemExit("Could not find project dependencies in pyproject.toml")
+
+          end = next(
+              (index for index in range(start + 1, len(lines)) if lines[index].strip() == "]"),
+              None,
+          )
+          if end is None:
+              raise SystemExit("Could not find end of project dependencies in pyproject.toml")
+
+          lines.insert(end, f'    "{stripe_dependency_from_branch()}",')
+          path.write_text("\n".join(lines) + "\n")
+          PY
+          }
+
+          resolve_stripe_overlay() {
+            if unresolved_conflicts | grep -qx "pyproject.toml"; then
+              git checkout --theirs pyproject.toml
+            fi
+
+            add_stripe_dependency
+
+            if unresolved_conflicts | grep -qx "uv.lock"; then
+              git checkout --ours uv.lock
+            fi
+
+            uv lock
+            git add pyproject.toml uv.lock
+
+            remaining_conflicts="$(unresolved_conflicts)"
+            if [ -n "$remaining_conflicts" ]; then
+              echo "Conflicts remain after stripe overlay resolution:"
+              echo "$remaining_conflicts"
+              return 1
+            fi
+
+            git commit --no-edit
+            git push origin "$BRANCH"
+          }
+
           git checkout "$BRANCH"
 
           if git merge origin/main --no-edit; then
@@ -170,6 +265,9 @@ jobs:
           elif conflicts_are_modal_overlay; then
             echo "Merge conflict only affects the modal dependency overlay; resolving automatically"
             resolve_modal_overlay
+          elif conflicts_are_stripe_overlay; then
+            echo "Merge conflict only affects the stripe dependency overlay; resolving automatically"
+            resolve_stripe_overlay
           else
             echo "Merge conflict detected, opening PR"
             git merge --abort

.github/workflows/test.yml

@@ -3,7 +3,7 @@ name: Test
 on:
   push:
   pull_request:
-    branches: [main]
+    branches: [main, stripe]
   workflow_dispatch:
   workflow_call:
 
@@ -62,4 +62,10 @@ jobs:
           DB_NAME: db
           DB_USER: postgres
           DB_PASSWORD: postgres
+          SECRET_KEY: test-secret-key-that-is-at-least-32-bytes-long
+          BASE_URL: http://localhost:8000
+          # Required on the stripe branch (billing always on); harmless on main.
+          STRIPE_SECRET_KEY: sk_test_dummy
+          STRIPE_WEBHOOK_SECRET: whsec_test_dummy
+          STRIPE_PRICE_ID: price_test_dummy
         run: uv run pytest tests/

README.md

@@ -34,6 +34,25 @@ The template also includes full-featured secure auth with:
 - Password recovery flow
 - Role-based access control system
 
+## Optional branches
+
+Some capabilities are maintained on dedicated branches so `main` stays lean:
+
+| Branch | Purpose |
+|--------|---------|
+| `main` | Core template (auth, orgs, RBAC) |
+| [`stripe`](https://github.com/Promptly-Technologies-LLC/fastapi-jinja2-postgres-webapp/tree/stripe) | Organization-scoped Stripe billing |
+| [`modal`](https://github.com/Promptly-Technologies-LLC/fastapi-jinja2-postgres-webapp/tree/modal) | Modal.com deployment artifacts |
+| [`hetzner`](https://github.com/Promptly-Technologies-LLC/fastapi-jinja2-postgres-webapp/tree/hetzner) | Hetzner Cloud deployment artifacts |
+
+New SaaS forks can start from `stripe`, or merge it later:
+
+```bash
+git remote add upstream https://github.com/Promptly-Technologies-LLC/fastapi-jinja2-postgres-webapp.git
+git fetch upstream stripe
+git merge upstream/stripe
+```
+
 ## Design Philosophy
 
 The design philosophy of the template is to prefer low-level,

user_guide/00-overview.qmd

@@ -24,6 +24,8 @@ The template also includes full-featured secure auth with:
 - Password recovery flow
 - Role-based access control system
 
+Optional [organization-scoped Stripe billing](https://github.com/Promptly-Technologies-LLC/fastapi-jinja2-postgres-webapp/tree/stripe) (Checkout, Customer Portal, webhooks) lives on the **`stripe`** branch.
+
 ## Design Philosophy
 
 The design philosophy of the template is to prefer low-level, best-in-class open-source frameworks that offer flexibility, scalability, and performance without vendor-lock-in. You'll find the template amazingly easy not only to understand and customize, but also to deploy to any major cloud hosting platform.

user_guide/04-customization.qmd

@@ -32,6 +32,20 @@ Your custom Python backend code should go primarily in the `routers/app/` and `u
 
 For the frontend, you will also need to develop custom Jinja2 templates in the `templates/` folder and add custom static assets in `static/`.
 
+### Billing (optional)
+
+Organization-scoped Stripe billing is maintained on the [`stripe`](https://github.com/Promptly-Technologies-LLC/fastapi-jinja2-postgres-webapp/tree/stripe) branch. See `user_guide/07-billing.qmd` on that branch for Dashboard setup, webhooks, fork helpers (`org_has_active_subscription`), and a manual end-to-end checklist.
+
+To add billing to an existing fork:
+
+```bash
+git remote add upstream https://github.com/Promptly-Technologies-LLC/fastapi-jinja2-postgres-webapp.git
+git fetch upstream stripe
+git merge upstream/stripe
+```
+
+When merging, expect conflicts in shared core files such as `main.py`, `pyproject.toml`, `utils/core/db.py`, `routers/core/organization.py`, header/organization templates, `tests/conftest.py`, and `.env.example`. Resolve by keeping billing additions from `stripe` while preserving your fork-specific changes.
+
 ### Testing
 
 The project uses Pytest for unit testing. It's highly recommended to write and run tests before committing code to ensure nothing is broken!

user_guide/05-deployment.qmd

@@ -13,6 +13,8 @@ There are *many* hosting options available for each of these services; this guid
 
 ::: {.callout-note}
 Deployment artifacts (Dockerfiles, deploy scripts, compose files, etc.) are kept on separate git branches — one per deployment target — to avoid cluttering the main branch. See the `modal` branch for Modal deployment files and the `hetzner` branch for Hetzner Cloud deployment files. The documentation below describes how to use them.
+
+Optional organization-scoped Stripe billing (Checkout, Customer Portal, webhooks) lives on the [`stripe`](https://github.com/Promptly-Technologies-LLC/fastapi-jinja2-postgres-webapp/tree/stripe) branch — not on `main`. Deploy billing-enabled apps from `stripe` (or after merging it into your fork); see `user_guide/07-billing.qmd` on that branch for setup.
 :::
 
 ## Deploying and Configuring the FastAPI App

user_guide/06-contributing.qmd

@@ -43,6 +43,10 @@ To contribute code to the project:
    - Provide a clear description of the changes
    - Link to any related issues
 
+### Optional branches
+
+Core template changes on `main` propagate automatically to `modal`, `hetzner`, and `stripe` via CI. Pull requests to `main` that touch shared files (`main.py`, `pyproject.toml`, `utils/core/db.py`, `routers/core/organization.py`, templates, `tests/conftest.py`, `.env.example`) may need manual conflict resolution when those changes are merged into `stripe`. See the [customization guide](https://promptlytechnologies.com/fastapi-jinja2-postgres-webapp/user-guide/customization.html) for the `git merge upstream/stripe` recipe.
+
 ### Rendering the documentation
 
 The documentation website is built with [Great Docs](https://posit-dev.github.io/great-docs/). If you make changes to the `.qmd` files in the `user_guide/` folder, you will need to rebuild the docs with Great Docs.