xiaoxia-saas/docs/GITEA-RUNTIME-BUILDER-RUNNER.md

Dedicated Gitea Runtime Builder Runner

Goal: build API/Worker runtime image tar on a machine that does not host production services.

Required machine

Minimum recommended spec:

• 2 vCPU minimum, 4 vCPU preferred.
• 4GiB RAM minimum, 8GiB preferred.
• 40GiB disk minimum.
• Docker Engine installed.
• Network access to Gitea and production SSH.

Do not install this runner on the current production host.

Runner label

The production runtime image workflow targets:

runs-on: runtime-builder

Register the new runner with a label named runtime-builder. Keep the existing production/staging runner separate.

Required Gitea secrets

Configure repository or organization secrets:

• PRODUCTION_SSH_HOST
• PRODUCTION_SSH_USER
• PRODUCTION_SSH_KEY

The key must allow uploading to:

/var/lib/xiaoxia-saas-production/runtime-images-<tag>.tar

Do not store SSH private keys in the repository.

Workflow behavior

On v* tag push:

1. build-production-runtime-images runs on runtime-builder.
2. It executes scripts/build_release_images.sh <tag>.
3. It uploads dist/release-images/xiaoxia-runtime-images-<tag>.tar to production.
4. deploy-production runs after the build job succeeds.
5. deploy-production loads /var/lib/xiaoxia-saas-production/runtime-images-<tag>.tar and restarts API/Worker/Web.

If the tar is missing, production deploy must fail.

Preflight checks on runner

Run on the new runner before registration:

docker version
docker ps --format '{{.Names}}' | grep -Eq '^(xiaoxia-(api|web|worker|postgres|redis)-production|gitea)$' && exit 1 || true

The second command must not find production containers.

Validation release

After runner registration:

1. Push a test tag only after develop is green.
2. Confirm runtime image build job runs on the dedicated runner.
3. Confirm production deploy waits for the image job.
4. Run:

python scripts/smoke_public_auth_flow.py
python scripts/smoke_public_upload_flow.py

5. Record release result in the Phase progress document.