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

The workflow can use either Gitea secrets or the dedicated runner-local upload key.

Preferred repository or organization secrets:

• PRODUCTION_SSH_HOST
• PRODUCTION_SSH_USER
• PRODUCTION_SSH_KEY

If these secrets are absent, the workflow falls back to:

• host: 47.98.113.167
• user: root
• key path on the dedicated builder: /root/.ssh/xiaoxia_runtime_builder

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. Checkout downloads the repository archive using the explicit ${{ github.token }} environment binding; runner shell environments must not assume GITHUB_TOKEN is implicitly set.
3. It executes scripts/build_release_images.sh <tag>.
4. It builds apps/web/dist in a Node Docker container, not on production.
5. It packages release-<tag>.tar.gz with the prebuilt Web dist.
6. It uploads both runtime-images-<tag>.tar and release-<tag>.tar.gz to production.
7. deploy-production runs after the build job succeeds, on runtime-builder, and drives production over SSH.
8. deploy-production extracts the prebuilt release artifact on production, loads /var/lib/xiaoxia-saas-production/runtime-images-<tag>.tar, and restarts API/Worker/Web.

If either the release tar or runtime image tar is missing, production deploy must fail. The production deploy job intentionally also runs on runtime-builder because Gitea needs scheduling previously skipped the downstream ubuntu-latest deploy job after a successful cross-runner build.

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.