puzzle-quest/.gitea/workflows/README.md

Gitea Actions CI

Workflow defined in build.yml. Triggered on push / PR to dev and main, or manually via workflow_dispatch.

Jobs

Job	Image	Role
validate	barichello/godot-ci:4.6	godot --headless --import then grep for SCRIPT ERROR / Parse Error. Uploads .godot/ cache.
lint	ubuntu-latest (Python)	gdlint scripts db scenes via gdtoolkit==4.* (Scony). Parallel to validate; does not gate exports yet.
export-desktop	barichello/godot-ci:4.6	Matrix: Windows / Linux / macOS. Reuses the import cache, uploads each binary as artifact.
export-android	barichello/godot-ci:4.6 + JDK 17 + Android SDK installed at runtime	Provisions keystore, writes editor_settings-4.tres with SDK / JDK paths, exports APK.

Artifacts are kept 14 days, accessible from the Gitea run page.

Prerequisites before the first successful run

1. Docker image tag — verify barichello/godot-ci:4.6 exists on Docker Hub. Otherwise adjust GODOT_IMAGE (common alternatives: 4.3, 4.4).
2. macOS preset missing — add it in Godot Editor → Project → Export → Add → macOS, name it exactly macOS (or change the matrix entry). The .zip will be unsigned; on Mac it needs xattr -dr com.apple.quarantine to launch.
3. Linux/X11Debug preset — Godot-3-era name. Reopen the project in Godot 4 once and re-save the preset (the editor may rename it). Update the matrix preset: field accordingly if it does.
4. Gitea runner — must support Docker containers (act_runner in docker mode, or host mode with Docker installed). Check act_runner exec access to Docker Hub.
5. Optional secret ANDROID_KEYSTORE_BASE64 — base64 -w0 debug.keystore, stored as a Gitea repo secret. Without it, a throwaway keystore is generated per run, so the APK signature changes every build.

Linting

gdlint (from Scony's gdtoolkit) runs in the lint job over scripts/, db/, and scenes/. addons/ (third-party LOD plugin) and developers/ (sandbox) are intentionally excluded.

The job is non-blocking today — the export jobs only depend on validate, so a lint failure prints warnings but still produces binaries. Once the codebase is clean, switch the export jobs' needs: validate to needs: [validate, lint] to make lint a hard gate.

Suppress specific rules per-line with # gdlint: disable=<rule> or project-wide with a gdlintrc file at the repo root (see gdtoolkit docs).

Known issues from first runs

Captured from the first triggered runs on feature/godot-migration (2026-05-17). Both must be resolved before the workflow can pass.

1. Container jobs fail at actions/checkout@v4 with node: not found

OCI runtime exec failed: ... exec: "node": executable file not found in $PATH

actions/checkout@v4 is a JavaScript action and needs Node.js inside the container. The barichello/godot-ci:4.6 image does not ship Node, so every job using container: (validate, export-desktop, export-android) breaks immediately.

Fix path (recommended): drop the container: block entirely and install Godot in a step (the default catthehacker/ubuntu:act-latest image used for runs-on: ubuntu-latest already has Node, Python, git, JDK). The lint job is already structured this way.

Alternative: switch to a Godot CI image that bundles Node (some community images do); pin a specific tag.

2. actions/checkout clones the wrong URL (resolved 2026-05-17)

The first runs failed at clone time because the runner asked for https://dev.stilobique.com/darknight/puzzle-quest/info/refs while Gitea was mounted under /gitea/ behind YunoHost — the request was intercepted by the YunoHost SSO at the root and redirected before reaching Gitea.

Resolved by relocating Gitea to the root: it now serves at https://dev.stilobique.com/ directly (API at /api/v1/..., clone_url at /<owner>/<repo>.git). The runner-injected GITHUB_SERVER_URL and the actual Gitea base URL now agree.

If Gitea is ever moved back under a sub-path, the fix is ROOT_URL in app.ini ([server] ROOT_URL = https://<host>/<prefix>/) or re-registering act_runner with the full instance URL.

3. Default-branch mismatch

The Gitea API reports default_branch: main for the repo, but CLAUDE.md describes dev as the default. The workflow listens to both, so jobs trigger correctly either way, but the "Workflows" sidebar in the Gitea UI reads from whatever the actual default branch is. If you intend dev to be the default, update it under repo Settings → Branches.

Differences from the old .drone.yml

• No more Drone, no more Butler — build only, artifacts downloadable from the Gitea UI.
• GDScript validation step before export (didn't exist).
• .godot/ import cache shared between jobs (faster reruns).
• Keystore via Gitea secret instead of a public pCloud link.
• macOS target added (preset still to be created in Godot).
• master / empty ReleaseVersion pipeline → replaced by triggers on main (release branch per CLAUDE.md).

Future: itch.io deploy via Butler

Not wired. When you want it back, add a deploy-itch job gated on tag push (v*) that downloads the artifacts and runs butler push <dir> dev-crea/ahog:<channel> with BUTLER_API_KEY from secrets. Channels used historically: windows, linux, android, mac.