vac-optimizer/docs/gitea-actions.md

Gitea Actions conversion

Issue #268 converts the repository's CI to .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	Required seven-scenario protocol, with one warm-up and two measured repetitions, outside coverage with one worker, a 2 GiB Node heap and the unchanged 300-second timeout.
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, including the benchmark, 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, including the benchmark. Requires image publication when expected; accepts its intentional skip for fork PRs and manual dispatch.

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 and package authorization.

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 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 translates the previous title, closing-issue references, and review reference using Gitea's supported variables. For a PR titled ci: migrate to Gitea Actions, closing #268, with reference #271, the checked expansion is:

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.