Yuvomi-App/docs/ci-runners.md

# Gitea CI runners

Workflows live in `.gitea/workflows/` for `git.nesterovic.cc`. Enable repository
Actions in Gitea settings. Scheduling uses the labels supplied by the maintainer:

| Job | `runs-on` | Eligible runners |
| --- | --- | --- |
| Android builds, JVM/lint checks | `ubuntu-latest` | `ubuntu-runner-1` through `ubuntu-runner-6` |
| Android emulator matrix (API 35 / 37.0) | `ubuntu-latest` | Same Ubuntu pool, with KVM access |
| Manual unsigned Android release build | `ubuntu-latest` | Same Ubuntu pool |
| iOS simulator, XCTest and unsigned archive | `macos-arm64` | `macos-m4pro` |

Runner names are informational; Gitea matches labels. The Mac's additional
`macos` label is not needed. No `self-hosted` label is requested because it is not
present in the supplied configuration. No runner registration or host settings
are changed by these workflows.

## Ubuntu prerequisites

The job environment must be Linux x86_64 with Bash, Git (SHA-256 capable), curl,
unzip, Python 3 and the shared libraries needed by the Android SDK/emulator and
Node's native build tools. Use a maintained Ubuntu runner image with compiler,
make, SQLite build prerequisites and emulator runtime libraries available. The
pinned setup actions provision Temurin 17, Android SDK packages and Node 22 for
the upstream fixture. SDK installation accepts the Android SDK licenses.

Emulator jobs require virtualization and readable/writable `/dev/kvm` **inside
the job environment**. For container-backed runners, the administrator must pass
the device through (for example `--device=/dev/kvm`) and configure group access.
VM hosts need nested virtualization. The preflight fails with a clear message
instead of attempting privileged host changes or silently using slow emulation.
All runners sharing `ubuntu-latest` must meet these prerequisites. Run each
emulator job in its own container; if using host execution, do not share an ADB
server/AVD directory with simultaneous jobs on that host.

## Apple Silicon prerequisites

Map `macos-arm64` to native host execution on the M4 Pro (not a Linux container or
Rosetta shell). Use a dedicated unprivileged CI account with Bash, SHA-256-capable Git, curl,
unzip and Python 3 available to the runner service's PATH. Install/select full
Xcode 16.4+ (or a current release supporting this project), accept its license and
complete first-launch setup. Install an iOS 18.4+ simulator runtime and create an
available iPhone simulator; `select-simulator.py` chooses the newest eligible one.

Before the first JavaScript action, an inline shell bootstrap installs verified
native Node 22.22.1 into a versioned runner tool cache and exports its bin directory
through `GITHUB_PATH`. It needs no Homebrew/root access and remains available to
action post-cleanup. This addresses run #4's `Cannot find: node in PATH` failure;
native bootstrap and checkout were verified in Mac job 1062 (run 661/#6).
That job subsequently stalled in Apple-tool preflight after printing Xcode 27.1.
The preflight now prints each tool probe and bounds it to 60 seconds using Python
(`scripts/check-apple-tools.py`), so the next run identifies the unresponsive
command rather than hanging silently. This does not validate the iOS app.

If an Apple probe stalls, run the named command in the runner user's interactive
login session, check the selected full Xcode, finish its first-launch components
and confirm CoreSimulator/runtimes work for that user. CI does not accept licenses,
change `xcode-select`, install runtimes or kill host simulator services. The runner
administrator must repair those prerequisites before native Apple validation.

XcodeGen's pinned, checksum-verified binary includes native arm64 and x86_64
slices; Rosetta/Homebrew installation is not required by the workflow. Build,
archive and Swift package scratch outputs use `RUNNER_TEMP`. Scratch directories
and the upstream clone are uniquely allocated per job and removed after artifact
upload to avoid collisions and buildup on persistent hosts. No Apple signing
credentials are required or provisioned. Avoid concurrent native jobs on the same
Mac user/simulator; configure runner capacity accordingly.

## Forge compatibility and security

- External actions use explicit HTTPS hosts and full commit pins. The Node 20
  Gitea-compatible artifact action uses the v3 protocol, not GitHub's v4 backend.
- Checkout sets `GIT_DEFAULT_HASH=sha256` for this repository and does not persist
  its token. Upstream remains a separate, unmodified SHA-1 clone.
- Fork pull requests are skipped on these private runners. Same-repository PRs,
  pushes and manual runs are trusted code: restrict repository write access,
  require review, isolate runner accounts and keep unrelated credentials away.
  Do not enable `pull_request_target` to bypass this restriction.
- Gitea ignores GitHub `environment` approval gates. Consequently the manual
  release workflow only emits **unsigned** APK/AAB files and never loads signing
  secrets or publishes. Signing remains an owner-controlled external operation.

Local checks for workflow changes:

```sh
python3 scripts/check-repository.py
python3 scripts/test-ci-runner.py
python3 scripts/test-verifier.py
python3 scripts/lint-workflows.py /path/to/actionlint
bash -n scripts/check-ci-runner.sh
```

The actionlint adapter normalizes Gitea's absolute action URLs only for parsing;
repository checks validate the actual hosts, pins, checkout settings and labels.
These checks do not prove a remote job ran. Inspect the first Gitea Actions runs
and their artifacts before claiming hosted Android or Apple-platform validation.