# 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. Deletes and recreates the `rolling` tag at the pushed commit using Gitea's
   repository tag API.
3. Creates a prerelease named with the commit prefix.
4. Uploads the `.deb`, extension ZIP, and `SHA256SUMS`.

The moving tag is intentionally mutable. This server's Swagger API exposes tag
replacement as `DELETE /repos/{owner}/{repo}/tags/{tag}` followed by
`POST /repos/{owner}/{repo}/tags`; the publisher uses that contract rather than
the unsupported Git refs patch route. 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.