ci: gitea actions for the suites, the image and the APK

Four workflows, none of which existed:

* `tests.yml` — backend, desktop, `:core` and the web app's typecheck+build, in
  parallel. `:core` needs no Android SDK at all, because settings.gradle.kts
  leaves `:app` out when there is none; `:app`'s Robolectric suite therefore
  lives in the APK workflow, where the SDK is installed anyway. Nothing needs a
  running backend — the suites feed on committed fixtures, which is the whole
  reason they were written that way.
* `lint.yml` — ruff, which the repo had been configured for and never run.
* `docker.yml` — builds the image, *starts* it against SQLite and waits for
  /api/health before pushing, then publishes `:latest` and `:<short-sha>` to
  git.timka.su. A tag nobody can run is worse than no tag.
* `android-release.yml` — the release APK on every push to master, signed from
  secrets, with `apksigner verify --print-certs` reporting which key was really
  used and failing if it was the debug one.

Three things the repo needed before any of that could work:

`versionCode` was pinned at 1, so every APK looked like the same version to the
phone and would not install over its predecessor. It now comes from the run
number, with `versionName` from a property, both via one `setting()` helper that
reads a Gradle property or an environment variable.

The release build fell back to the *debug* signing key whenever the keystore was
missing — silently. That is a trap: the APK installs, looks fine, and can never
be upgraded by a properly signed build. `KADENCE_REQUIRE_SIGNING=1` makes that
case fail the build instead, and the release job sets it whenever a keystore
secret is present.

The compose files built an image with no name, so there was nothing to pull.
`image:` now names the registry tag while `up --build` still builds locally.

Also: `android/ci/install-sdk.sh` (idempotent, cacheable, and the one place that
knows `platforms;android-37.0` is spelled with the minor version), the runner as
a compose service with its config and a setup checklist, six make targets, and a
README section. No runner is registered yet — `make ci-runner` is step two of
that checklist.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.gitea/workflows/android-release.yml

@@ -0,0 +1,116 @@
+# The release APK, on every push to master.
+#
+# This is the one job that needs the Android SDK, so it is also where the `:app`
+# unit tests run — `:core`'s suite is in `tests.yml`, where no SDK is needed
+# because `settings.gradle.kts` leaves `:app` out when there is none.
+#
+# The Glyph Matrix AAR is deliberately *not* fetched: its licence forbids
+# redistribution, and `app/build.gradle.kts` compiles the `noglyph` source set
+# without it. A CI APK therefore has an inert rear display, which is also exactly
+# right for any phone that is not a Nothing.
+name: android
+
+on:
+  push:
+    branches: [master]
+    tags: ["v*"]
+
+env:
+  ANDROID_HOME: /opt/android-sdk
+  JAVA_HOME: /usr/lib/jvm/java-21-openjdk-amd64
+  DEBIAN_FRONTEND: noninteractive
+
+jobs:
+  apk:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install JDK 21 and the tools the SDK installer needs
+        run: |
+          apt-get update -qq
+          apt-get install -y --no-install-recommends \
+            openjdk-21-jdk-headless curl unzip >/dev/null
+
+      # Keyed on the pinned SDK versions, so this is a download once and a
+      # restore every time after.
+      - uses: actions/cache@v4
+        continue-on-error: true
+        with:
+          path: /opt/android-sdk
+          key: android-sdk-${{ hashFiles('android/gradle/libs.versions.toml') }}
+
+      - uses: actions/cache@v4
+        continue-on-error: true
+        with:
+          path: ~/.gradle/caches
+          key: gradle-app-${{ hashFiles('android/gradle/libs.versions.toml', 'android/gradle/wrapper/gradle-wrapper.properties') }}
+
+      - name: Install the Android SDK
+        run: ./android/ci/install-sdk.sh
+
+      - name: Unit tests (:app, on the JVM via Robolectric)
+        working-directory: android
+        run: ./gradlew --no-daemon :app:testDebugUnitTest
+
+      - name: Unpack the signing key
+        id: key
+        env:
+          KEYSTORE_BASE64: ${{ secrets.KADENCE_KEYSTORE_BASE64 }}
+        run: |
+          if [ -z "${KEYSTORE_BASE64:-}" ]; then
+            echo "No KADENCE_KEYSTORE_BASE64 secret — nothing to sign with." >&2
+            echo "signed=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          mkdir -p "$RUNNER_TEMP"
+          printf '%s' "$KEYSTORE_BASE64" | base64 -d > "$RUNNER_TEMP/kadence.keystore"
+          echo "signed=true" >> "$GITHUB_OUTPUT"
+
+      - name: Build the release APK
+        working-directory: android
+        env:
+          # The run number, so successive APKs install over each other. It was
+          # pinned at 1, which made every build look like the same version.
+          KADENCE_VERSION_CODE: ${{ gitea.run_number }}
+          KADENCE_KEYSTORE: ${{ runner.temp }}/kadence.keystore
+          KADENCE_KEYSTORE_PASSWORD: ${{ secrets.KADENCE_KEYSTORE_PASSWORD }}
+          KADENCE_KEY_ALIAS: ${{ secrets.KADENCE_KEY_ALIAS }}
+          KADENCE_KEY_PASSWORD: ${{ secrets.KADENCE_KEY_PASSWORD }}
+          # With a keystore, a missing or misnamed secret must fail the build
+          # rather than silently produce a debug-signed "release".
+          KADENCE_REQUIRE_SIGNING: ${{ steps.key.outputs.signed == 'true' && '1' || '0' }}
+        run: ./gradlew --no-daemon :app:assembleRelease
+
+      - name: Say which key actually signed it
+        run: |
+          APKSIGNER="$(find "$ANDROID_HOME/build-tools" -name apksigner | sort | tail -1)"
+          APK=android/app/build/outputs/apk/release/app-release.apk
+          "$APKSIGNER" verify --print-certs "$APK"
+          if [ "${{ steps.key.outputs.signed }}" = "true" ]; then
+            # The debug key is unmistakable, and shipping it would be a trap: the
+            # APK installs, then cannot be upgraded by a properly signed one.
+            if "$APKSIGNER" verify --print-certs "$APK" | grep -q "CN=Android Debug"; then
+              echo "::error::signed with the debug key despite a keystore being provided"
+              exit 1
+            fi
+          fi
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: kadence-release-apk
+          path: android/app/build/outputs/apk/release/app-release.apk
+          if-no-files-found: error
+
+      - name: Attach it to the release, when this is a tag
+        if: startsWith(github.ref, 'refs/tags/v')
+        env:
+          TOKEN: ${{ secrets.GITEA_TOKEN }}
+        run: |
+          VERSION="${GITHUB_REF#refs/tags/}"
+          API="${GITHUB_SERVER_URL}/api/v1/repos/${GITHUB_REPOSITORY}"
+          ID="$(curl -fsS -H "Authorization: token $TOKEN" "$API/releases/tags/$VERSION" \
+                | sed -n 's/.*"id":[ ]*\([0-9]*\).*/\1/p' | head -1)"
+          curl -fsS -X POST -H "Authorization: token $TOKEN" \
+            -F "attachment=@android/app/build/outputs/apk/release/app-release.apk" \
+            "$API/releases/$ID/assets?name=kadence-$VERSION.apk"

.gitea/workflows/docker.yml

@@ -0,0 +1,70 @@
+# Build the backend + web image and push it to this Gitea's own registry.
+#
+# The image is the same one `docker compose` builds locally — one Dockerfile,
+# two stages, Vite's output baked in and served from the same origin as the API.
+# Tagged twice: `latest` for the deploy script to pull, and the short commit for
+# every build to be nameable after the fact.
+#
+# Needs a runner that can reach a docker daemon. The compose service in
+# `docker-compose.ci.yml` mounts the host's socket into the job container, which
+# is the usual arrangement for a single-machine Gitea.
+name: docker
+
+on:
+  push:
+    branches: [master]
+    tags: ["v*"]
+
+env:
+  REGISTRY: git.timka.su
+  IMAGE: git.timka.su/timka123/kadence
+
+jobs:
+  image:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check the daemon is reachable
+        run: docker version
+
+      - name: Log in to the Gitea registry
+        run: |
+          echo "${{ secrets.REGISTRY_TOKEN }}" \
+            | docker login "$REGISTRY" -u "${{ secrets.REGISTRY_USER }}" --password-stdin
+
+      - name: Build
+        run: |
+          SHORT="$(git rev-parse --short HEAD)"
+          echo "SHORT=$SHORT" >> "$GITHUB_ENV"
+          docker build -t "$IMAGE:$SHORT" -t "$IMAGE:latest" .
+
+      - name: Smoke-test the image before it is published
+        run: |
+          # A tag nobody can run is worse than no tag. SQLite keeps this to one
+          # container: no database service, no network, no .env.
+          docker run -d --name kadence-smoke \
+            -e DATABASE_URL="sqlite:///./kadence.db" \
+            -e SCHEDULER_ENABLED=0 -e TELEGRAM_BOT_ENABLED=0 \
+            -p 18000:8000 "$IMAGE:$SHORT"
+          for _ in $(seq 1 30); do
+            if curl -fsS http://127.0.0.1:18000/api/health >/dev/null 2>&1; then
+              echo "healthy"; break
+            fi
+            sleep 2
+          done
+          curl -fsS http://127.0.0.1:18000/api/health
+          docker logs kadence-smoke | tail -20
+          docker rm -f kadence-smoke
+
+      - name: Push
+        run: |
+          docker push "$IMAGE:$SHORT"
+          docker push "$IMAGE:latest"
+
+      - name: Push the tag, when there is one
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          VERSION="${GITHUB_REF#refs/tags/}"
+          docker tag "$IMAGE:$SHORT" "$IMAGE:$VERSION"
+          docker push "$IMAGE:$VERSION"

.gitea/workflows/lint.yml

@@ -0,0 +1,26 @@
+# ruff, which the repo has been configured for and never ran.
+name: lint
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install ruff
+        run: |
+          apt-get update -qq
+          apt-get install -y --no-install-recommends python3-venv >/dev/null
+          python3 -m venv /tmp/venv
+          /tmp/venv/bin/pip install -q ruff
+
+      # The rule set lives in backend/pyproject.toml; the desktop app has no ruff
+      # section of its own and is checked with the same one. `ruff format` is not
+      # run on purpose — see the note in that config.
+      - name: ruff check
+        run: /tmp/venv/bin/ruff check --config backend/pyproject.toml backend desktop

.gitea/workflows/test.yml

@@ -0,0 +1,99 @@
+# The suites, on every push and pull request.
+#
+# All four are offline by design: the backend only ever runs on one machine, so
+# nothing here may need it up. Fixtures and fakes, never a live server.
+#
+# `ubuntu-latest` is whatever the runner's label map points at — see
+# `docker-compose.ci.yml`, which pins it to catthehacker/ubuntu:act-24.04 for the
+# two things every job needs: a node (Gitea's javascript actions run inside the
+# job container) and Python 3.12, which the backend requires.
+name: tests
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+env:
+  DEBIAN_FRONTEND: noninteractive
+
+jobs:
+  backend:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Python tooling
+        run: |
+          apt-get update -qq
+          apt-get install -y --no-install-recommends python3-venv >/dev/null
+          python3 -m venv /tmp/venv
+          /tmp/venv/bin/pip install -q -e "./backend[dev]"
+
+      - name: pytest
+        working-directory: backend
+        run: PYTHONPATH="$PWD" /tmp/venv/bin/python -m pytest -q
+
+  desktop:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # No PyQt6 and no display: nothing under desktop/tests imports Qt. The
+      # three modules it covers — the blocker manager, the DNS stub, the mini
+      # timer's geometry — are plain standard library, which is why they are
+      # testable at all. `pythonpath = ["."]` is already in the pytest config.
+      - name: Install pytest
+        run: |
+          apt-get update -qq
+          apt-get install -y --no-install-recommends python3-venv >/dev/null
+          python3 -m venv /tmp/venv
+          /tmp/venv/bin/pip install -q pytest
+
+      - name: pytest
+        working-directory: desktop
+        run: /tmp/venv/bin/python -m pytest -q
+
+  web:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/cache@v4
+        continue-on-error: true
+        with:
+          path: frontend/node_modules
+          key: npm-${{ hashFiles('frontend/package-lock.json') }}
+
+      - name: Install, typecheck, build
+        working-directory: frontend
+        run: |
+          npm ci --no-audit --no-fund
+          npm run typecheck
+          npm run build
+
+  android-core:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # `:core` is plain Kotlin on the JVM and `settings.gradle.kts` only
+      # includes `:app` when an SDK is present, so this job needs a JDK and
+      # nothing else. The `:app` unit tests run in the release workflow, where
+      # the SDK has to be installed anyway.
+      - name: Install JDK 21
+        run: |
+          apt-get update -qq
+          apt-get install -y --no-install-recommends openjdk-21-jdk-headless >/dev/null
+
+      - uses: actions/cache@v4
+        continue-on-error: true
+        with:
+          path: ~/.gradle/caches
+          key: gradle-core-${{ hashFiles('android/gradle/libs.versions.toml', 'android/gradle/wrapper/gradle-wrapper.properties') }}
+
+      - name: gradlew :core:test
+        working-directory: android
+        env:
+          JAVA_HOME: /usr/lib/jvm/java-21-openjdk-amd64
+        run: ./gradlew --no-daemon :core:test

Makefile

@@ -51,6 +51,31 @@ android-build: ## Build the debug APK (needs the Android SDK)
 android-install: ## Install the debug APK on the connected phone
 	cd android && ./gradlew :app:installDebug
 
+lint: ## ruff over the backend and the desktop app (what CI runs)
+	# From the repo root and with these arguments, exactly as `.gitea/workflows/lint.yml`
+	# does: ruff decides what counts as a first-party import from where it is invoked,
+	# so a different cwd gives a different answer about import order.
+	backend/.venv/bin/ruff check --config backend/pyproject.toml backend desktop
+
+ci-test: ## Every suite, the way CI runs them — no venv assumptions
+	python3 -m venv /tmp/kadence-ci && /tmp/kadence-ci/bin/pip install -q -e "./backend[dev]"
+	cd backend && PYTHONPATH=$$PWD /tmp/kadence-ci/bin/python -m pytest -q
+	cd desktop && /tmp/kadence-ci/bin/python -m pytest -q
+	cd android && ./gradlew :core:test :app:testDebugUnitTest
+	cd frontend && npm ci --no-audit --no-fund && npm run typecheck && npm run build
+
+glyph-sdk: ## Download the Glyph Matrix SDK into android/app/libs
+	cd android && ./fetch-glyph-sdk.sh
+
+android-sdk: ## Install the Android SDK packages this app builds against
+	./android/ci/install-sdk.sh
+
+android-release: ## Build the release APK (set KADENCE_KEYSTORE* to sign it)
+	cd android && ./gradlew :app:assembleRelease
+
+ci-runner: ## Start the Gitea Actions runner (needs GITEA_RUNNER_REGISTRATION_TOKEN)
+	docker compose -f docker-compose.ci.yml up -d
+
 report: ## Build and send today's report right now
 	cd backend && PYTHONPATH=$$PWD .venv/bin/python -m app.cli report
 
@@ -64,4 +89,4 @@ deploy: ## Push master and redeploy kadence.timka.su on sw_pl_1
 deploy-logs: ## Follow the production app log
 	ssh sw_pl_1 'cd /opt/kadence && docker compose -f docker-compose.yml -f docker-compose.prod.yml logs -f --tail 100 app'
 
-.PHONY: help up down logs dev test backend-venv web-build desktop desktop-test desktop-install helper-install android-test android-test-core android-build android-install report set-password deploy deploy-logs
+.PHONY: help up down logs dev test lint ci-test backend-venv web-build desktop desktop-test desktop-install helper-install android-test android-test-core android-build android-install android-sdk android-release glyph-sdk ci-runner report set-password deploy deploy-logs

README.md

@@ -239,6 +239,10 @@ make desktop-install  # menu entry + icon
 make helper-install   # the privileged blocking helper
 make report           # build and send today's report right now
 make android-install  # build and install the phone client
+make lint             # ruff, the same invocation CI uses
+make ci-test          # every suite, with no venv assumed
+make android-release  # the release APK
+make ci-runner        # start the Gitea Actions runner
 make deploy           # push master and redeploy kadence.timka.su
 ```
 
@@ -254,6 +258,54 @@ python -m app.cli set-password  # set/rotate the web login password (prompts, ne
 
 ---
 
+## Continuous integration
+
+Gitea Actions, in `.gitea/workflows/`:
+
+| Workflow | When | What |
+| --- | --- | --- |
+| `test.yml` | push to master, every PR | backend (73), desktop (47), `:core` (196), and the web app's typecheck + build — four parallel jobs, none of which may need a running backend |
+| `lint.yml` | push to master, every PR | `ruff check` over `backend/` and `desktop/`, with the rule set named in `backend/pyproject.toml` |
+| `docker.yml` | push to master, `v*` tags | builds the image, starts it against SQLite and waits for `/api/health`, then pushes `git.timka.su/timka123/kadence:latest` and `:<short-sha>` |
+| `android-release.yml` | push to master, `v*` tags | `:app`'s Robolectric suite (44), then the release APK — signed from secrets, with `apksigner verify` printing the certificate it actually used |
+
+**Nothing runs until a runner is registered.** `docker-compose.ci.yml` is the whole
+of that, and its header is the setup checklist: a registration token from
+*Settings → Actions → Runners*, then `make ci-runner`. Gitea itself needs
+`[actions] ENABLED = true` and `DEFAULT_ACTIONS_URL = github` in `app.ini`, the
+second so `actions/checkout@v4` can be resolved.
+
+Two details decide whether the jobs work at all:
+
+* **The label map.** `runs-on: ubuntu-latest` is pinned to
+  `catthehacker/ubuntu:act-24.04` by the runner's own config, because the jobs need
+  two things from the image: a `node` (Gitea's javascript actions run *inside* the
+  job container) and Python 3.12, which the backend's `requires-python` insists on.
+* **The docker socket**, mounted into job containers so the image can be built. It
+  needs both the mount and `valid_volumes` naming it — see `deploy/act-runner.yaml`.
+
+Secrets, all under *Repository → Settings → Actions → Secrets*:
+
+| Secret | For |
+| --- | --- |
+| `REGISTRY_USER`, `REGISTRY_TOKEN` | pushing to the Gitea registry (a token with `package:write`) |
+| `KADENCE_KEYSTORE_BASE64` | `base64 -w0 your.keystore` |
+| `KADENCE_KEYSTORE_PASSWORD`, `KADENCE_KEY_ALIAS`, `KADENCE_KEY_PASSWORD` | the key inside it |
+
+With no keystore secret the APK job still runs and still produces an artifact —
+debug-signed, which is fine for installing on your own phone and no use for
+anything else. With one, `KADENCE_REQUIRE_SIGNING` makes a missing or misnamed
+secret **fail the build**: the Gradle config otherwise falls back to the debug key
+without a word, and a debug-signed "release" installs happily and can then never
+be upgraded by a properly signed one.
+
+The Glyph Matrix AAR is deliberately not fetched in CI — its licence forbids
+redistribution, and the build compiles the `noglyph` source set without it, so a
+CI APK has an inert rear display. That is also the correct behaviour on any phone
+that is not a Nothing.
+
+---
+
 ## Going public
 
 Kadence is still single-user: `AUTH_USERNAME`/`AUTH_PASSWORD` and

android/app/build.gradle.kts

@@ -19,6 +19,25 @@ plugins {
 val glyphAar = layout.projectDirectory.file("libs/glyph-matrix-sdk-2.0.aar").asFile
 val hasGlyphSdk = glyphAar.isFile
 
+/**
+ * One property or environment variable, whichever is set.
+ *
+ * CI passes these as environment variables and a developer puts them in
+ * `~/.gradle/gradle.properties`; neither should have to care which the build reads.
+ */
+fun setting(name: String): String? =
+    (project.findProperty(name) as String?) ?: System.getenv(name)
+
+/**
+ * Successive builds have to install over each other, so the code has to climb.
+ *
+ * It was pinned at 1, which meant every CI artifact looked like the same version to
+ * the phone. In CI this is the run number; locally it stays 1, because a developer
+ * installing over their own debug build does not care.
+ */
+val buildVersionCode = setting("KADENCE_VERSION_CODE")?.toIntOrNull() ?: 1
+val buildVersionName = setting("KADENCE_VERSION_NAME") ?: "0.1.0"
+
 android {
     namespace = "tech.kadence.android"
     compileSdk = libs.versions.compileSdk.get().toInt()
@@ -27,8 +46,8 @@ android {
         applicationId = "tech.kadence.android"
         minSdk = libs.versions.minSdk.get().toInt()
         targetSdk = libs.versions.targetSdk.get().toInt()
-        versionCode = 1
-        versionName = "1.0.0"
+        versionCode = buildVersionCode
+        versionName = buildVersionName
         testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
 
         buildConfigField("boolean", "HAS_GLYPH_SDK", hasGlyphSdk.toString())
@@ -53,16 +72,21 @@ android {
         // key: it still produces an installable APK for one's own phone, which is the
         // only distribution this app has.
         create("release") {
-            val storePath = (project.findProperty("KADENCE_KEYSTORE") as String?)
-                ?: System.getenv("KADENCE_KEYSTORE")
+            val storePath = setting("KADENCE_KEYSTORE")
             if (storePath != null && file(storePath).isFile) {
                 storeFile = file(storePath)
-                storePassword = (project.findProperty("KADENCE_KEYSTORE_PASSWORD") as String?)
-                    ?: System.getenv("KADENCE_KEYSTORE_PASSWORD")
-                keyAlias = (project.findProperty("KADENCE_KEY_ALIAS") as String?)
-                    ?: System.getenv("KADENCE_KEY_ALIAS") ?: "kadence"
-                keyPassword = (project.findProperty("KADENCE_KEY_PASSWORD") as String?)
-                    ?: System.getenv("KADENCE_KEY_PASSWORD")
+                storePassword = setting("KADENCE_KEYSTORE_PASSWORD")
+                keyAlias = setting("KADENCE_KEY_ALIAS") ?: "kadence"
+                keyPassword = setting("KADENCE_KEY_PASSWORD")
+            } else if (setting("KADENCE_REQUIRE_SIGNING") == "1") {
+                // Without this the fallback below quietly produces a *debug-signed*
+                // "release" APK: installable, apparently fine, and impossible to ship
+                // or to upgrade a real install with. A release job sets this so a
+                // missing or misnamed secret fails the build instead of the release.
+                throw GradleException(
+                    "KADENCE_REQUIRE_SIGNING is set but no keystore was found at " +
+                        "${storePath ?: "<KADENCE_KEYSTORE unset>"}",
+                )
             }
         }
     }

android/ci/install-sdk.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# Install just enough Android SDK to build this app, idempotently.
+#
+# Used by CI, and usable by hand on a fresh machine. Everything lands in
+# $ANDROID_HOME (default /opt/android-sdk), so pointing a cache or a volume at
+# that directory makes the whole thing a no-op on later runs.
+#
+# Two package names are worth knowing:
+#
+#   * `platforms;android-37.0` — Android's new minor-version scheme. Plain
+#     `android-37` does not exist and sdkmanager will not tell you why.
+#   * `build-tools;37.0.0` — needed for `apksigner`, which is how a release job
+#     proves what key it actually signed with.
+set -euo pipefail
+
+SDK_ROOT="${ANDROID_HOME:-/opt/android-sdk}"
+COMPILE_SDK="$(sed -n 's/^compileSdk = "\(.*\)"/\1/p' "$(dirname "$0")/../gradle/libs.versions.toml")"
+BUILD_TOOLS="${BUILD_TOOLS:-${COMPILE_SDK}.0.0}"
+CMDLINE_VERSION="13114758"  # cmdline-tools 17.0, the one that knows about minor platforms
+
+mkdir -p "$SDK_ROOT"
+
+if [ ! -x "$SDK_ROOT/cmdline-tools/latest/bin/sdkmanager" ]; then
+  echo "==> fetching cmdline-tools"
+  tmp="$(mktemp -d)"
+  curl -fsSL -o "$tmp/tools.zip" \
+    "https://dl.google.com/android/repository/commandlinetools-linux-${CMDLINE_VERSION}_latest.zip"
+  unzip -q "$tmp/tools.zip" -d "$tmp"
+  mkdir -p "$SDK_ROOT/cmdline-tools"
+  rm -rf "$SDK_ROOT/cmdline-tools/latest"
+  mv "$tmp/cmdline-tools" "$SDK_ROOT/cmdline-tools/latest"
+  rm -rf "$tmp"
+fi
+
+export PATH="$SDK_ROOT/cmdline-tools/latest/bin:$PATH"
+
+echo "==> licences"
+yes | sdkmanager --sdk_root="$SDK_ROOT" --licenses >/dev/null
+
+echo "==> platform-tools, platforms;android-${COMPILE_SDK}.0, build-tools;${BUILD_TOOLS}"
+sdkmanager --sdk_root="$SDK_ROOT" \
+  "platform-tools" \
+  "platforms;android-${COMPILE_SDK}.0" \
+  "build-tools;${BUILD_TOOLS}" >/dev/null
+
+echo "==> $SDK_ROOT is ready"

deploy/act-runner.yaml

@@ -0,0 +1,26 @@
+# act_runner's own configuration. See docker-compose.ci.yml for what it is for.
+log:
+  level: info
+
+runner:
+  capacity: 2
+  timeout: 1h
+  # Jobs pull their own tooling; nothing here needs to be fetched per job.
+  fetch_timeout: 10s
+  fetch_interval: 5s
+
+cache:
+  # Gitea's built-in cache server is what makes actions/cache@v4 work, and the
+  # Android SDK download is worth caching: it is most of that job's wall clock.
+  enabled: true
+
+container:
+  network: bridge
+  privileged: false
+  # The host's docker daemon, for the image build. Both lines are needed: the
+  # mount itself, and the allow-list that permits it.
+  options: -v /var/run/docker.sock:/var/run/docker.sock
+  valid_volumes:
+    - /var/run/docker.sock
+  # Let the job's own `docker` CLI find it.
+  docker_host: unix:///var/run/docker.sock

docker-compose.ci.yml

@@ -0,0 +1,48 @@
+# The Gitea Actions runner, for a single-machine Gitea.
+#
+# Nothing in .gitea/workflows runs until a runner is registered, and this is the
+# whole of it. Two settings do the work:
+#
+#   * the **label map** decides what `runs-on: ubuntu-latest` means. It is pinned
+#     to catthehacker/ubuntu:act-24.04 because the workflows need two things from
+#     the image: a node (Gitea's javascript actions — checkout, cache,
+#     upload-artifact — run *inside* the job container) and Python 3.12, which
+#     the backend's `requires-python` insists on. Ubuntu 24.04 ships 3.12.
+#   * the **docker socket**, mounted into job containers so the `docker` workflow
+#     can build and push an image. That is a real privilege handed to CI; it is
+#     also the normal arrangement when Gitea and its runner are the same box as
+#     the deployment.
+#
+# Setting it up:
+#
+#   1. Gitea → Settings → Actions → Runners → "Create new runner", copy the token.
+#   2. GITEA_RUNNER_REGISTRATION_TOKEN=<token> docker compose -f docker-compose.ci.yml up -d
+#   3. Repository → Settings → Actions → Secrets, add:
+#        REGISTRY_USER, REGISTRY_TOKEN            — a Gitea user and token with
+#                                                   package:write, for the registry
+#        KADENCE_KEYSTORE_BASE64                  — base64 -w0 of your keystore
+#        KADENCE_KEYSTORE_PASSWORD, KADENCE_KEY_ALIAS, KADENCE_KEY_PASSWORD
+#      Without the keystore secrets the APK job still runs and produces an
+#      unsigned-for-release (debug-signed) artifact rather than failing.
+#
+# Gitea itself needs `[actions] ENABLED = true` in app.ini, and
+# `DEFAULT_ACTIONS_URL = github` so `actions/checkout@v4` can be resolved.
+services:
+  runner:
+    image: gitea/act_runner:0.2.11
+    restart: unless-stopped
+    environment:
+      GITEA_INSTANCE_URL: ${GITEA_INSTANCE_URL:-https://git.timka.su}
+      GITEA_RUNNER_REGISTRATION_TOKEN: ${GITEA_RUNNER_REGISTRATION_TOKEN:?set this to the token from Gitea}
+      GITEA_RUNNER_NAME: ${GITEA_RUNNER_NAME:-kadence-runner}
+      GITEA_RUNNER_LABELS: ubuntu-latest:docker://catthehacker/ubuntu:act-24.04
+      # Mounted into every job container, which is what lets the docker workflow
+      # build an image. `valid_volumes` has to allow it explicitly.
+      CONFIG_FILE: /config/config.yaml
+    volumes:
+      - runner-data:/data
+      - ./deploy/act-runner.yaml:/config/config.yaml:ro
+      - /var/run/docker.sock:/var/run/docker.sock
+
+volumes:
+  runner-data:

docker-compose.yml

@@ -24,6 +24,10 @@ services:
       retries: 10
 
   app:
+    # Named as well as built, so the same compose file can run a published image
+    # instead: `KADENCE_IMAGE=git.timka.su/timka123/kadence:latest docker compose pull`.
+    # `up --build` still builds locally and tags it with this name.
+    image: ${KADENCE_IMAGE:-git.timka.su/timka123/kadence:latest}
     build:
       context: .
       dockerfile: Dockerfile