From d549c2405f47b8ceb95236791deaa0bab989a8ae Mon Sep 17 00:00:00 2001
From: ops <ops@x>
Date: Mon, 1 Jun 2026 23:42:57 +0000
Subject: [PATCH] add README

---
 README.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 61 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 19e24df..6637426 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,62 @@
-# ci-templates
+# platform/ci-templates
 
-Reusable deploy workflow for Forgejo Actions
\ No newline at end of file
+Centralised deploy logic for the Forgejo Actions flow (Phase 5+).
+
+## What's here
+
+- **`action.yml`** — the composite action that does everything: checkout, parse
+  `.env`, detect deploy type, build (bun for static / `docker build` for
+  docker), publish (rsync to `/srv/sites` for static / `docker run` for docker),
+  generate the Caddy fragment + reload, inject `RUNTIME_KEYS` secrets, honour the
+  `ENABLED` kill-switch and auto-www.
+- **`auto.yml`** — LEGACY GitLab CI template (still used by repos on the old
+  GitLab until Phase 8). Do not extend; new work goes in `action.yml`.
+- **`Dockerfile.react`** — legacy reference SPA Dockerfile.
+
+## How dev repos use it
+
+A dev repo (forked from `templates/starter`) has a tiny
+`.forgejo/workflows/deploy.yml` that calls this action by **full URL**:
+
+```yaml
+jobs:
+  deploy:
+    runs-on: docker-cli
+    container:
+      image: docker:24.0.7
+      volumes:
+        - /srv/sites:/srv/sites
+        - /srv/platform/caddy/sites:/srv/platform/caddy/sites
+    steps:
+      - uses: https://git.154.83.149.72.nip.io/platform/ci-templates@main
+        with:
+          repo: ${{ github.repository }}
+          ref: ${{ github.ref_name }}
+          sha: ${{ github.sha }}
+          token: ${{ github.token }}
+          secrets_json: ${{ toJSON(secrets) }}
+          vars_json: ${{ toJSON(vars) }}
+```
+
+Fix a bug / add a feature → edit `action.yml`, push to `main` → every project
+picks it up on its next deploy. The per-repo caller never changes.
+
+## Why a composite action (not a reusable workflow)
+
+Forgejo 11.0.14 (gitea-1.22) **does not trigger cross-repo reusable workflows**
+(`uses: owner/repo/.forgejo/workflows/x.yml@ref` produces no run). A composite
+action is the supported way to centralise logic. Referenced by **full URL**
+because the runner's default actions registry is `data.forgejo.org`, so a bare
+`platform/ci-templates` would resolve there, not on our instance.
+
+## Mechanism notes
+
+- Jobs run on the runner with `/var/run/docker.sock` mounted (host daemon) → the
+  action builds/runs images and `docker exec caddy caddy reload` directly. No
+  registry: build and run hit the same daemon.
+- The deploy job bind-mounts `/srv/sites` and `/srv/platform/caddy/sites` (added
+  to the runner's `valid_volumes` in `/srv/platform/forgejo/runner/config.yaml`).
+- The `docker:24.0.7` job image has no Node, so the action uses **no JS actions**
+  (manual `git clone` instead of `actions/checkout`).
+- Phase 8 host rename: change `git.154.83.149.72.nip.io` → `git.extractl.online`
+  in `FORGE_HOST` (action.yml) and the starter caller URL.