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 with Bun, then validates the checked-out commit, GitFlow, PR title, commits, and stable release version.
validate	Runs ESLint, Prettier (application, scripts/ci-*.mjs and workflow files) and bun check type checks of application and test code, all on Bun with the frozen lockfile.
test	Runs functional coverage with bun test --isolate (line coverage only), converts it to HTML and Cobertura, and uploads coverage for seven days even on failure.
benchmark	Required seven-scenario protocol (one warm-up, two measured repetitions) outside coverage in a container limited to 3 GiB. It first times the frozen engine on two years (best of three) and fails any scenario whose mean planning time exceeds its multiplier times that calibration; the 600-second timeout is only a hang guard.
build	Builds the client-only Angular production bundle (the only check of Angular templates; bun check does not replace it) and the Bun static-server bundle, 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. The scanners are not project JavaScript, so this job installs no Bun.
images	Publishes branch/SHA images after required validation, including the benchmark, or promotes an existing SHA image for a stable tag, running the publisher with Bun. 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. It is shell only and needs no Bun.

The benchmark runs on both push and pull_request events: the push run gates image publication (images.needs includes benchmark) and the required aggregate. The relative gate absorbs a slower runner and load that lasts through the whole job, because calibration runs in the same job. It does not absorb load that starts or stops during the protocol, such as an overlapping push and pull_request run of the same commit; the 600-second hang guard still bounds those runs.

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

Every job that runs project commands uses Bun 1.4.3 with the frozen lockfile (see Bun toolchain and Node). Job containers stay on Node 24.22.0. The image job uses Docker 29.9.1 and its matching Docker-in-Docker service. Scanner versions are Semgrep 1.180.0 and Trivy 0.75.0; Trivy downloads are checksum-checked. Trivy downloads its vulnerability database from Aqua's public ECR mirror because the default registries returned a missing database blob and a download timeout. Jobs select the ubuntu-latest label and require Linux container-job support. Allow at least the benchmark job's 3 GiB container memory limit plus runner 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.

Bun toolchain and Node

Project commands run on Bun 1.4.3 only. package.json (packageManager), @types/bun, both Docker stages and scripts/install-bun.sh carry the same version. To upgrade, change all of them together and replace the installer's four SHA-256 values with those of the new release's SHASUMS256.txt; the installer refuses a package.json that names a different version, so a bump of only one place fails CI instead of drifting.

• Install. policy, validate, test, benchmark, build and images run sh scripts/install-bun.sh. It downloads the release zip for the runner's architecture (x64 or aarch64) and libc (glibc, or musl on Alpine), verifies its pinned SHA-256, and installs /opt/bun/bin/bun. It uses no npm.
• Node-free project steps. The five Debian jobs set defaults.run.shell: env PATH=/opt/bun/bin:/usr/bin:/bin bash -e {0}. Every run: step then sees Bun but not /usr/local/bin, where the node image keeps node, npm and yarn. bun run additionally runs Node-shebang tools on Bun through bunfig.toml. The security scanners are not project JavaScript, so security has no Bun and no custom shell.
• Why the containers keep Node. actions/checkout@v4 (node20) and actions/upload-artifact@v3 (node16) are JavaScript actions. The runner starts them with the container's node; the custom shell does not affect uses: steps. This is a platform requirement, not permission to run project commands on Node.
• images exception. Alpine's nodejs package installs node into /usr/bin, beside git, and checkout's post step needs it, so PATH cannot hide it there. The project command is /opt/bun/bin/bun scripts/ci-image.mjs; it starts only process.execPath, docker and git. Hiding Node there needs an infrastructure decision (for example a runner image that ships Node outside PATH), which this conversion does not make.
• Needs live validation. The custom shell template is a GitHub Actions feature that Gitea's runner implements. A local run of the real engine (gitea-runner exec v5.1.0, with the job containers above) executed it, but only a live Gitea run confirms the instance's runner version, the checkout action and the privileged Docker-in-Docker images job.

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.