unsupervised-scheduler/docs/ci.md

CI

CI and release jobs do not install PHP. They run inside the shared images maintained in Unsupervised/ci-php:

git.unsupervised.ca/unsupervised/ci-php:8.1
git.unsupervised.ca/unsupervised/ci-php:8.2
git.unsupervised.ca/unsupervised/ci-php:8.3
git.unsupervised.ca/unsupervised/ci-php:8.5

The Unsupervised org is public, so they pull anonymously — no registry credentials in any job here. What the images contain, how they are published, and how to add a PHP version are documented in that repository's README.

Which job runs where

Job	Runs in
Coding Standards (PHPCS)	ci-php:8.3
Static Analysis (PHPStan)	ci-php:8.3
Tests	ci-php:${{ matrix.php }}
Build Plugin Zip	ci-php:8.3
No Debug Code	runner image — no PHP, and it uses GNU grep --include
Open next-version bump PR (release.yml)	runner image — no PHP

PHPCS and PHPStan are separate jobs so a coding-standards failure still lets the static analysis result through. They run in parallel.

Composer

composer.lock is committed, so every job installs the same dependency set and two builds of the same tag ship the same vendor tree. bin/build-zip.sh stages the lock into its build directory for the same reason, then removes it before writing the zip.

The Composer download cache lives at /composer/cache — COMPOSER_HOME is /composer in the image — and is keyed on composer.lock.

Adding a PHP version to the test matrix

The image has to exist first. Add the version to the php matrix in ci-php's .gitea/workflows/publish.yml and merge, then add it to the test matrix in .gitea/workflows/ci.yml here.

Signing the version bump commit

main is a protected branch that requires signed commits, and Gitea will not merge a pull request containing an unsigned one. The bump-version job in release.yml therefore signs the commit it makes, using a dedicated release-bot SSH key rather than the key Gitea signs merge commits with — that one is [repository.signing] SIGNING_KEY on the server and no runner can reach it. Keeping the CI key separate also means it can be rotated on its own if the secret ever leaks.

There is deliberately no release-bot Gitea account. A key attached to an account is only consulted for signature checking after it has been through the web Verify flow, and that flow has no API — a bot account would need an interactive login to be worth anything. Listing the key under TRUSTED_SSH_KEYS instead makes Gitea verify commits signed with it without any account lookup, which is all the protected branch asks for.

Set up once for the instance, and again only if the key is rotated:

1. Generate a passphrase-less key (it has to be usable unattended):

   ssh-keygen -t ed25519 -C '[email protected]' -f release-bot -N ''
   

2. Add the public half to app.ini and restart Gitea:

   [repository.signing]
   TRUSTED_SSH_KEYS = ssh-ed25519 AAAAC3Nza... [email protected]
   

3. Store the private half as the organisation Actions secret RELEASE_BOT_SIGNING_KEY (Org → Settings → Actions → Secrets): the whole release-bot file verbatim, -----BEGIN OPENSSH PRIVATE KEY----- header and footer included — not the .pub, and not a GPG export. Organisation secrets are readable as secrets.RELEASE_BOT_SIGNING_KEY from every repository in the org, so no repository-level copy is needed. Delete both local files afterwards.

Two consequences of trusting the key instance-wide are worth knowing. Any commit signed with it verifies in every repository on the instance, not just these — the trust is in the key, not in a user with permissions you can scope. And the signature is attributed to SIGNING_NAME / SIGNING_EMAIL, not to the Release Bot <[email protected]> committer the job sets; that address backs no account and is only a label.

The job fails fast if the secret is missing or ssh-keygen is absent from the runner image, and it re-reads the commit it just made to confirm a signature is attached before pushing — an unsigned bump commit would otherwise look fine until someone tried to merge the PR.

Nothing else in the pipeline signs anything: release tags are made by a human through Gitea's release UI, and the merge commit is signed by the server when the PR is merged.