inkwell/ci-requirements.md

CI Requirements — Inkwell

Spec lives in docs/process.md in the CI-Runner repo.

Runtime images

Image	Used by
git.fabledsword.com/bvandeusen/ci-python:3.14	every ci.yml job; the decide jobs in desktop.yml and android.yml
git.fabledsword.com/bvandeusen/ci-tauri:1.97	desktop.yml verify, build, manifest; android.yml rust
git.fabledsword.com/bvandeusen/ci-tauri-win:1.97	desktop.yml windows
git.fabledsword.com/bvandeusen/ci-rust-android:1.97	android.yml build, server-image
postgres:16-alpine	service container for ci.yml integration

Each is selected via container.image; runs-on is only a scheduling label.

The Rust pin is in LOCKSTEP across ci-tauri, ci-tauri-win and ci-rust-android. All three build inkwell-core from one workspace Cargo.lock under --locked, so a mismatched Rust minor would mean divergent resolution for no reason. Bump them together or not at all.

Image deps used

ci-python

• python 3.14 for the tests. The runtime Dockerfile targets python:3.12-slim; both are >=3.12, so results stay representative.
• node 24 — npm ci, vue-tsc and the web unit tests. Also required by the JS-based actions/checkout: a Node-less runner fails every job at checkout. The Dockerfile's own frontend stage uses node:22-alpine.
• ruff — the lint job runs ruff check src/ with no install.
• uv — the test jobs create the venv (uv venv /opt/venv) and install the package with dev deps.
• docker CLI + buildx — the build job pushes the image to the Fabled-Git registry.
• curl — packaging/fetch-clients.sh and packaging/guard-forward.sh. The guard refuses to run without it, because every lookup would read as "nothing published".

ci-tauri — Rust, Node, WebKitGTK 4.1, the Tauri v2 Linux deps and tauri-cli.

• libssl-dev + pkg-config are load-bearing. inkwell-core, which the desktop crate builds in, uses reqwest with the native-tls backend, which on Linux compiles against OpenSSL. Dropping either fails the build at openssl-sys. They are also Tauri's documented Linux prerequisites. This is why android.yml's host-target rust job runs here and not on ci-rust-android, whose OpenSSL is vendored for the Android targets alone.
• dpkg-deb, dpkg-query, apt-cache and dpkg-shlibdeps (from dpkg-dev, pulled in by build-essential) for desktop/packaging/deb/verify.sh; tar and a compressor for desktop/packaging/arch/package-prebuilt.sh.
• Optional, used when present: bsdtar (libarchive-tools) for the pacman package's .MTREE, zstd (compression falls back zstd → xz → gzip), and a docker CLI for the .deb clean-container install test. ci-tauri has the first two, so the package ships as .pkg.tar.zst with an .MTREE. It has no docker CLI, so the install test is skipped; adding one would enable it, and its absence does not block a green build.

ci-tauri-win — Rust, Node, cargo-xwin, LLVM/lld and NSIS. A separate image per CI-Runner's fork rule: the MSVC CRT/SDK cache alone is >1 GB.

ci-rust-android — Rust, the four Android ABIs, cargo-ndk, SDK/NDK, JDK 25, ktlint and detekt. The NDK binutils symlinks and PATH append are there because NDK r23 removed the triple-prefixed binutils that autotools, and so vendored OpenSSL, invokes by bare name. JDK 25 requires Gradle 9.1+ in the wrapper. The analyzers are the image's pinned CLIs rather than Gradle plugins, so there is one version of each.

Per-job tool installs

None. Every job runs entirely on its image.

The lanes

ci.yml — on every push to dev and main, and when dispatched. gate, typecheck, lint, test and integration run in parallel, and build needs all five, so nothing publishes on red. dev publishes :dev; main publishes :latest and :<sha>. The image always builds: it is ~15 seconds, and building every push picks up python:3.12-slim updates.

gate stands the build down when the push touched the Android client's file set. The Android lane then dispatches ci.yml once it has published the APK, so the image bakes in the client from the same commit.

desktop.yml — on every push to dev and main.

• decide reads the file set in packaging/version.sh and skips everything when the channel already serves this source. packaging/guard-forward.sh runs here, so it also covers the skip path.
• verify builds the frontend, runs the web unit tests, then cargo clippy --locked --workspace, cargo test --workspace and cargo fmt --all --check from the repo root. Run from desktop/src-tauri instead, cargo would scope to the desktop package and the core's tests would silently not run. If you add a workspace member, check that it appears in the cargo test output.
• build (Linux): cargo tauri build for .deb and AppImage, de-bundles the AppImage's graphics libs and re-signs it, verifies the .deb, repackages for pacman, and publishes to the channel. APPIMAGE_EXTRACT_AND_RUN=1 is set because CI containers have no /dev/fuse.
• windows: cross-compiles the NSIS installer. There is no Windows build host, and a Windows container cannot run on a Linux host. .msi needs WiX v3, a Windows program, so NSIS only.
• manifest writes latest.json after both, so it describes both platforms.

android.yml — on every push to dev and main. decide, then rust (the core's clippy and tests, which gate the APK), then build (native library and bindings, ktlint, detekt, host-JVM unit tests, assemble, check the signing certificate, publish), then server-image, which dispatches ci.yml.

release.yml — on a v* tag. Builds nothing; it writes the changelog for the release.

Notes

• No actions/cache for npm or uv. It is a GitHub-fetched JS action, and on a cold runner concurrent jobs race fetching it. The pinned images' toolchains carry the load; cold npm ci / uv pip install cost is a non-blocker.

• Artifacts: stock actions/upload-artifact@v7, never @v3. Stock works on this forge because gitea/runner 3.x edits the action's client-side isGhes() refusal out of its bundle (verified for upload-artifact v4–v7 and download-artifact v4–v8). @v3 reports success, but Gitea serves artifacts back only through the v4 API (content_encoding = application/zip), so a v3 upload is stored and invisible to every retrieval path. Upload steps set if-no-files-found: error and carry no continue-on-error, so a failed or empty upload fails the run.

  Download: GET /api/v1/repos/{owner}/{repo}/actions/runs/{run_id}/artifacts for the id (the global run id, not the repo-scoped run number), then …/actions/artifacts/{id}/zip. Without unzip, use python3 -m zipfile -e.

• libssl3 is covered transitively, on purpose — don't "fix" it. dpkg-shlibdeps lists libssl3 among the binary's needs, but the .deb declares only libwebkit2gtk-4.1-0 + libgtk-3-0. verify.sh passes it because webkit's own dependency closure includes OpenSSL, so apt installs it either way. Declaring it would be worse: the name is release-dependent (libssl3 on bookworm, libssl3t64 after the 64-bit time_t transition in trixie/Ubuntu 24.04). If webkit ever stops pulling OpenSSL, verify.sh fails the build.

• The Windows TLS backend is chosen for that lane's sake. native-tls on x86_64-pc-windows-msvc resolves to schannel, pure-Rust bindings to the OS TLS stack, which keeps C and assembly out of the cross-compile. rustls would pull in ring/aws-lc-rs and their assembler, the class of dependency that breaks this lane (libsqlite3-sys → llvm-lib). Treat a TLS-backend change as a change to the Windows lane.

• What CI cannot verify. The runner is Debian, so the pacman package is not pacman -U-tested; the step logs .PKGINFO and the file listing instead. A Linux runner cannot launch a Windows binary or an APK, so green means built: a real Windows machine and a real phone are the check before trusting a release. Windows installers are unsigned and trip SmartScreen.

The integration lane

Real Postgres, so the schema the migrations build is checked against the models that read it before any deployment runs alembic upgrade head.

• Job key integration, no name:. act_runner derives the service container's name from the truncated job DISPLAY name, and the discovery step filters docker ps by it. A spaced or underscored name breaks the filter.
• Service hostnames are not routable on this runner, so the step resolves the Postgres container's bridge IP and builds INKWELL_DATABASE_URL from it. postgres:5432 will not connect. The runner's docker daemon is shared, so the lookup is scoped to this task's own containers.
• run: is busybox sh — no /dev/tcp — so the readiness wait is a small Python heredoc. Its terminator must dedent to column 0 after YAML strips the block indent; check with yaml.safe_load and print the run string if you edit it.
• Real migrations, never metadata.create_all. The alembic upgrade head step IS the migration test: a broken revision fails the job there, before it can fail a container start.

Tests are marked integration (registered in pyproject.toml); the unit lane runs -m "not integration" and stays DB-free. Data resets with TRUNCATE ... CASCADE BEFORE each test rather than after, so a failure leaves its rows behind to look at.

Checking lanes before pushing

The analyzers and tests below can run locally against the CI images, with the workflow's exact arguments, because a local check that differs from CI is worse than none. They reproduce CI exactly: same image, same lockfile, same units. Nothing else — no bundle builds, no services — is meant to run locally.

Rust

Run all three, in this order, before any push that touches Rust:

IMG=git.fabledsword.com/bvandeusen/ci-tauri:1.97
DOCK="docker run --rm --user $(id -u):$(id -g) -e CARGO_HOME=/tmp/cargo -v $PWD:/w -w /w"

$DOCK $IMG cargo fmt --all --check
$DOCK $IMG cargo clippy --locked --workspace --all-targets -- -D warnings
$DOCK $IMG cargo test --locked --workspace

Drop --check from the first to apply it. --user keeps the container from leaving root-owned files behind; CARGO_HOME points somewhere writable for that user. target/ persists between runs, so after the first cold build these take seconds; it is gitignored and reaches ~1.4 GB.

Run them on every Rust-touching push, not just the risky-looking ones. A removal looks safe and often isn't — a private fn deleted along with the pub fn above it, an orphaned #[serde] attribute — and nothing in the Python or TypeScript lanes compiles Rust, so a break can travel several commits before a lane that does gets to it.

Don't infer formatting from existing code. Some lines in local/store.rs exceed 100 characters and survive only because rustfmt cannot break a string literal.

Kotlin

From android/:

IMG=git.fabledsword.com/bvandeusen/ci-rust-android:1.97
DOCK="docker run --rm --user $(id -u):$(id -g) -e HOME=/tmp -v $PWD:/w -w /w"

$DOCK $IMG ktlint "app/src/main/**/*.kt"
$DOCK $IMG detekt --build-upon-default-config --config config/detekt.yml \
    --input app/src/main/java

HOME=/tmp because both tools want a writable home for their caches and --user has taken the image's away.

Neither can see a missing import. They parse Kotlin without resolving symbols, so a file that cannot compile passes both. Two more checks cover the blind spots:

python3 android/tools/check-symbols.py
python3 android/tools/check-strings.py

check-symbols.py flags any capitalised identifier that is neither imported, declared in the same package, a type parameter, nor implicitly available — and members of this package's own object declarations, so Foo.bar() fails when Foo has no bar. It is not a type checker: compileDebugKotlin in CI is the only one.

check-strings.py covers resources, where the compiler is no help: R is generated, so R.string.whatever type-checks whether or not the string exists. It catches a missing name, stringResource used on a plural or the reverse, and a format string that takes more arguments than the call passes — which renders %2$s as literal text rather than failing.

Run all four before a push that touches Kotlin.

A checker of this shape is easy to get vacuously right: re.sub(r'//.*', ..., flags=re.S) makes //.* swallow each file from its first comment to EOF and report everything clean. Test a checker against a known-bad tree before trusting a green from it. check-symbols.py is verified by deleting an import from a copy of the source; check-strings.py by introducing one of each of its three fault kinds.

Read the artifact, don't recall the API. Compose comes from a BOM (compose-bom in libs.versions.toml), so no file here states which material3 a build gets, and guessing costs eight minutes of CI a try. Resolve and read it:

# androidx is on Google's Maven, NOT Maven Central — repo1 returns 404
BOM=https://dl.google.com/dl/android/maven2/androidx/compose/compose-bom
curl -sS $BOM/2026.05.01/compose-bom-2026.05.01.pom | grep -A3 'material3</artifactId>'

M3=https://dl.google.com/dl/android/maven2/androidx/compose/material3/material3-android
curl -sS -o m3-src.jar $M3/1.4.0/material3-android-1.4.0-sources.jar

The sources jar answers what javap cannot: default arguments, parameter names, and whether a declaration carries @ExperimentalMaterial3Api. An unnecessary @OptIn is itself a Kotlin warning, so guessing "safely" breaks the zero-warning build as surely as omitting a required one. The same works for any dependency — it is how work-runtime-ktx shows up as an empty 6 KB stub as of 2.11, with CoroutineWorker and PeriodicWorkRequestBuilder in work-runtime itself.

Frontend

vue-tsc --noEmit type-checks only the SCRIPT block, so a malformed TEMPLATE passes the typecheck lane and fails vite build in the desktop lanes. npm run build runs both:

docker run --rm --user "$(id -u):$(id -g)" -e HOME=/tmp -v "$PWD:/w" -w /w/frontend \
  git.fabledsword.com/bvandeusen/ci-python:3.14 sh -c "npm ci --silent && npm run build"

Delete frontend/node_modules and frontend/dist afterwards.

The Cargo lockfile

Cargo.lock is committed at the workspace root, per Cargo's guidance for binary crates, so a build is reproducible from its commit and can't break with no repo change, and Renovate has something to bump.

--locked on each job's first cargo invocation enforces it — cargo clippy --locked on Linux, a dedicated cargo fetch --locked --target x86_64-pc-windows-msvc step on Windows. If the manifest and the lockfile disagree, the run fails there; everything after it in the same job compiles the recorded versions. The Windows step exists because that job's only other crate-graph command is the cross-compile, and drift is cheaper to learn in thirty seconds than thirty minutes in.

To regenerate it after a dependency change:

docker run --rm --user "$(id -u):$(id -g)" -e CARGO_HOME=/tmp/cargo \
  -v "$PWD:/w" -w /w \
  git.fabledsword.com/bvandeusen/ci-tauri:1.97 cargo fetch

cargo fetch, not cargo generate-lockfile. generate-lockfile re-resolves the whole graph and will bump crates unrelated to your change, turning a two-line manifest edit into a few-hundred-line lockfile diff. cargo fetch keeps existing pins and adds only new entries. Check it stayed additive (git diff Cargo.lock | grep '^-' should show nothing but re-ordered dependency lists), and commit it with the Cargo.toml edit — a manifest change pushed without it fails the gate.

Channel releases: dev-rolling and stable

The two update channels are releases on fixed tags, because Fabled-Git has no /releases/latest/download/<asset> route and the updater needs a permanent URL. The channel is called dev everywhere a person sees it; its release tag is dev-rolling, because a tag named dev would shadow the branch and make git push origin dev fail with error: src refspec dev matches more than one. packaging/channel-tag.sh is the one mapping CI reads; desktop/src-tauri/src/update.rs and desktop/packaging/install.sh carry their own copy because neither can run it — change all three together. tests/test_channel_tag.py and the update.rs tests fail if a channel tag is spelled like a branch.

A desktop app installed before 2026-09-10 reads a dev tag that no longer exists and gets no further updates; reinstall it with install.sh.

Shell scripts have no CI lane

Nothing lints desktop/packaging/*.sh, and a broken installer or publish script fails when a user runs it, not in a build. Check them before pushing — install.sh is POSIX sh, the rest are bash:

dash -n desktop/packaging/install.sh          # or: sh -n
bash -n desktop/packaging/publish-release.sh

Where a script resolves URLs from the Fabled-Git API, exercise the resolution against the live instance (plain reads, no install) rather than trusting the regex by eye.

Hand-assembled JSON: parse it before you push it. publish-release.sh builds its request bodies as shell strings, and quoting context decides what survives into the JSON — a \ inside an unquoted heredoc loses its backslash to the shell, the same \ inside a single-quoted variable does not, and reaches Fabled-Git as an illegal escape (HTTP 422). sh -n cannot see this. Extract the body block and parse it for every branch it can take:

sed -n '/^# The install command printed/,/^JSON$/p' desktop/packaging/publish-release.sh > /tmp/body.sh
echo ')' >> /tmp/body.sh
bash -c 'GITHUB_SERVER_URL=https://git.fabledsword.com GITHUB_REPOSITORY=o/r \
  TAG=dev RELEASE_PRERELEASE=true; . /tmp/body.sh; printf "%s" "$BODY" | python3 -m json.tool >/dev/null'