ci: migrate to Gitea Actions

docs/gitea-actions.md

@@ -0,0 +1,131 @@
+# Gitea Actions conversion
+
+[Issue #268](https://gitea.nessar.fr/nessar/vac-optimizer/issues/268) converts the
+repository's CI to [`.gitea/workflows/ci.yml`](../.gitea/workflows/ci.yml).
+The workflow and merge-message template have passed implementation review.
+Repository Actions is enabled with owner approval. Publisher credentials and
+live workflow validation are still pending.
+The existing `gitlab-to-gitea/ci-conversion-required` status stays in place until
+that review, a successful Gitea PR run, and approval of the prepared first merge
+message.
+
+## Jobs and triggers
+
+Every branch and tag push runs CI. Pull requests run on opening, reopening,
+synchronization, and title/body edits. Manual dispatch runs validation without
+publishing images. There is no schedule or deployment job in the preserved
+configuration; the Compose files remain manual deployment options.
+
+| Job         | Behavior                                                                                                                                                                                                  |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `policy`    | Tests the policy and publisher, then validates the checked-out commit, GitFlow, PR title, commits, and stable release version.                                                                            |
+| `validate`  | Runs lint, formatting, and application/test type checks.                                                                                                                                                  |
+| `test`      | Runs functional coverage with one worker and a 2 GiB Node heap; uploads coverage for seven days even on failure.                                                                                          |
+| `benchmark` | Runs outside coverage with the same worker/heap limits and 300-second protocol timeout. Advisory while #78 is open.                                                                                       |
+| `build`     | Builds browser/server production bundles and retains `dist` for seven days.                                                                                                                               |
+| `security`  | Runs Semgrep JavaScript/TypeScript SAST and Trivy dependency/secret scans; retains SARIF reports for seven days. Scanner execution must succeed; findings remain reports rather than a new severity gate. |
+| `images`    | Publishes branch/SHA images after required validation, or promotes an existing SHA image for a stable tag. Runs only for pushes and same-repository PRs.                                                  |
+| `required`  | Fails on failed, cancelled, or skipped required validation. Requires image publication when expected; accepts its intentional skip for fork PRs and manual dispatch. Excludes the advisory benchmark.     |
+
+Push and PR runs are separate so PR title and rebase checks run on the PR event.
+New runs cancel older runs for the same event/ref. Image jobs serialize per
+branch slug; stable promotions share one group and are not cancelled in progress.
+
+## Runners and permissions
+
+Validation uses Node 24.21.0 and Bun 1.4.2 with the frozen lockfile. The image
+job uses Docker 29.8.2 and its matching Docker-in-Docker service. Scanner
+versions are Semgrep 1.180.0 and Trivy 0.75.0; Trivy downloads are checksum-checked.
+Jobs select the `ubuntu-latest` label and require Linux container-job support.
+Allow at least the preserved 2 GiB Node heap plus runner and container overhead.
+
+The instance currently has an online inherited runner named `srvhome`, labelled
+`ubuntu-latest` and `ubuntu-24.04`. Repository runners, secrets, and variables
+were empty at implementation time. The owner must verify that this runner can
+run the job containers, JavaScript actions, artifact uploads, and the privileged
+Docker-in-Docker service before replacing the migration gate. Use isolated runners for untrusted
+contributor code; the privileged publishing service belongs to trusted runs.
+
+The workflow requests a read-only repository token. Checkout removes persisted
+credentials; publication credentials are passed only to the image step. Fork PRs
+and manual dispatches cannot run that step. Gitea's job token cannot publish
+container packages, so provision the two repository Actions secrets below.
+See [job-token permissions](https://docs.gitea.com/usage/actions/token-permissions/)
+and [package authorization](https://docs.gitea.com/usage/actions/comparison/).
+
+| Secret              | Purpose                                                                     |
+| ------------------- | --------------------------------------------------------------------------- |
+| `REGISTRY_USERNAME` | The package publisher's Gitea username, authorized to publish for `nessar`. |
+| `REGISTRY_PASSWORD` | A dedicated personal access token with `write:package` permission.          |
+
+Keep secret values in Gitea's Actions secret store. The configured tea account's
+administrator token is not a CI publishing credential. No SSH or deployment
+secret is required by this workflow.
+
+## Images and releases
+
+Images use the [Gitea container registry](https://docs.gitea.com/usage/packages/container/)
+at `gitea.nessar.fr/nessar/vac-optimizer`. Branch pushes and same-repository PRs
+publish `branch-<slug>` and `sha-<full commit SHA>`. Slugs retain the previous
+lowercase, non-alphanumeric-to-hyphen, 63-byte normalization; choose distinct
+branch slugs.
+
+Only stable `vX.Y.Z` tags matching the tagged commit's `package.json` version
+and reachable from `main` may promote images. Promotion first pulls the existing
+SHA image, then publishes the version tag and `latest`; it never rebuilds.
+An absent SHA image fails before either stable tag changes. Wait for the main
+image job before tagging. No version increment or deployment is automatic.
+
+## Merge messages and activation
+
+The [merge template](../.gitea/default_merge_message/MERGE_TEMPLATE.md) translates
+the previous title, closing-issue references, and review reference using
+[Gitea's supported variables](https://docs.gitea.com/usage/issues-prs/merge-message-templates/).
+For a PR titled `ci: migrate to Gitea Actions`, closing #268, with reference #271,
+the checked expansion is:
+
+```text
+ci: migrate to Gitea Actions
+
+close #268
+
+See pull request #271
+```
+
+The owner has enabled Actions and approved validation before adding publisher
+secrets. Complete the remaining activation checks in this order:
+
+1. Review this workflow against the protected administrator exports for runner
+   requirements, triggers/schedules, permissions, secrets, publishing, and
+   deployment dependencies. The original CI definition is retained in Git:
+   `git show 0d900fd72d1a405d257f5a566c55cc0cb3d2bc61:.gitlab-ci.yml`.
+2. Publish the reviewed feature branch and open its PR to register the workflow.
+   Once registered, manual dispatch verifies validation and artifacts without
+   publishing images. Push and PR validation can also run now; their image and
+   aggregate checks remain blocked until publisher secrets are provisioned.
+3. Verify runner isolation and Docker service support, then provision the two
+   publisher secrets. Review the package publisher's permissions and registry
+   namespace before permitting publication. Rerun the PR workflow and require a
+   successful **pull-request run** on the final commit, including PR title and
+   rebase checks, artifact handling, and actual image publication. A push run
+   or manual run alone does not validate the PR policy and publication.
+4. Prepare and review the first PR's merge message before replacing the migration
+   gate. The target branch will not contain the new template until that first
+   merge, so explicitly use the validated PR title, closing references, and PR
+   reference for its merge message. Keep the migration gate throughout this
+   review.
+5. After the successful PR run and merge-message approval, replace the migration
+   status requirement on both protected branches with the **actual reported
+   pull-request context** for the `required` job. Select it from the PR's reported
+   checks rather than a push run or a guessed context spelling. Fork PRs must
+   also be able to satisfy this check without base-repository push permissions.
+   Keep direct/force pushes disabled, merges restricted to maintainers, outdated
+   PRs blocked, and administrator protection bypass disabled. Select merge
+   commits and disable squash/rebase merge methods.
+6. Merge the first PR using the approved message, then verify the resulting merge
+   commit. Subsequent merges read the committed template. No direct
+   integration-branch push is needed.
+
+Historical job execution, reports, and downloadable artifacts remain in the
+administrator rollback backups. They are not recreated or uploaded by this
+conversion.