R1

docs/ci-gitea.md

@@ -0,0 +1,46 @@
+# Gitea CI and rolling releases
+
+Gitea Actions reads workflows from `.gitea/workflows/`. This repository has two
+workflows:
+
+```mermaid
+flowchart LR
+  Push[Push / pull request] --> CI[.gitea/workflows/ci.yml]
+  CI --> Tests[npm test + Python syntax + package smoke]
+  Main[Push to main] --> RR[rolling-release.yml]
+  RR --> Build[Build deb + extension + checksums]
+  Build --> API[Gitea release API]
+  API --> Tag[Move rolling tag]
+  API --> Release[Replace rolling prerelease]
+```
+
+## Required repository configuration
+
+Create a repository secret named `RELEASE_TOKEN`. It must be able to read the
+repository and create/update tags, releases, and release assets. The workflow
+references it as `${{ secrets.RELEASE_TOKEN }}`; the value is never committed.
+
+## Rolling behavior
+
+Each push to `main` runs tests and packaging. The publish script:
+
+1. Deletes the existing release associated with `rolling`, if present.
+2. Moves or creates the `rolling` tag at the pushed commit.
+3. Creates a prerelease named with the commit prefix.
+4. Uploads the `.deb`, extension ZIP, and `SHA256SUMS`.
+
+The moving tag is intentionally mutable. Permanent releases should use reviewed
+immutable tags after validating a rolling artifact.
+
+## Local rehearsal
+
+```bash
+npm ci
+npm test
+npm run package
+cat dist/SHA256SUMS
+```
+
+Do not run the publish script locally unless `GITEA_SERVER_URL`,
+`GITEA_REPOSITORY`, `GITEA_SHA`, and a write-capable `RELEASE_TOKEN` are
+intentionally set.