Documentation And CI

The authored site is an Astro Starlight project, self-contained in docs/, with Dokime’s Charcoal and Gilt identity, strict content collections, and theme-aware client-rendered Mermaid diagrams. Content lives in docs/src/content/docs/; the version badge and the included changelog are generated, ignored partials under docs/src/generated/.

Local Commands

mise run dev:docs:dev
mise run build:docs:release

build:docs:release regenerates the ignored version and changelog partials and runs astro build into site/. The CI docs job publishes that directory as a one-week artifact whenever documentation inputs change, and on tags. The docs build reads one optional environment variable, DOCS_SITE_URL — the public URL the site is served under. When set (the CI docs job sets it to https://stokkertechnologies.ch/products/dokime/docs), Astro’s site and base are derived from it, generated links carry the public prefix, and a sitemap is emitted; unset, local builds serve at /. Hand-written content links are relative so both modes resolve, and a links validator fails the build on broken internal links either way. The docs project is its own pnpm workspace with its own lockfile: mise run sync (or pnpm --dir docs install --frozen-lockfile) installs its pinned dependencies.

SDK Pin

crates/sdk-pin.rs names the Dokime revision that cargo dokime new writes into every generated plugin manifest, and the test:plugin:starter:release task builds a generated project against that revision over Git. The pin is deliberately independent of the checkout, so it goes stale silently: a change to the public dokime API is not done until the pin follows it. The order is fixed, because a pin can never name the commit that introduces it:

# 1. land and push the SDK change
# 2. repin to the pushed tip and prove it against the release starter
mise run sdk:pin
# 3. commit crates/sdk-pin.rs and push again

The test:plugin CI job runs the same release starter test, so a pushed SDK change whose pin was not refreshed fails the pipeline rather than the next plugin author.

Runner Discovery And Verification

The parent .gitlab-ci.yml runs mise run ci:discover on an online controller runner (tag linux by default; override CI_CONTROL_RUNNER_TAG to use a dedicated controller). A controller must remain online to discover the worker fleet. Configure masked GITLAB_RUNNER_READ_TOKEN with read_api and project runner visibility on every trusted ref where CI should run. Protected credentials are only available on protected refs; untrusted pipelines must not receive this token. Missing credentials or failed API requests fail discovery rather than claiming a skip.

Discovery queries all pages of assigned/inherited project runners, includes busy online runners, and excludes offline, paused, incorrectly tagged, or inaccessible protected runners. target/ci/availability.json lists selected platforms and skip reasons. With no eligible platform, discovery fails. Selection is a startup snapshot; a runner going offline later may still leave a selected job pending.

The generated child pipeline includes this repository’s .gitlab/ci/platforms.yml. Docs and protocol lanes use the parent commit diff; new branches and missing base metadata conservatively run both. verified depends on all selected check, test, plugin, and scheduled docs/protocol jobs. Only after those succeed does it publish target/ci/verified.json with the platforms actually verified. Installers are built only for those platforms. The parent mirrors the child result, including failures. A green pipeline with a skipped platform does not certify that platform.

Linux and Windows use the same mise run check and mise run test requirements. The test aggregate covers the Rust workspace and native feature configurations, repository tooling, frontend tests, installed Python wheel tests, and installer configuration. Platform-specific primitives such as POSIX FIFOs report explicit test skips; Windows does not substitute a smaller aggregate.

Run mise run test:ci for discovery and publication tooling regression tests.

Python Binding Validation

mise run check:python:bindings inspects Rust PyO3 declarations and registration against the Python stubs without compiling. Its mapping is declared in the [pyo3] section of stkr.toml. The normal check aggregate includes this gate, alongside Ruff and Pyright for authored Python. The separate bindings:check task validates generated protobuf bindings.

mise run test:python builds and installs the Python wheel before exercising its imports, runtime exports, stub compatibility, and consumer workflows. Both Linux and Windows include this task in the shared test aggregate.

Docs Image

docker/docs.Dockerfile packages the site/ artifact into a Caddy image; docker/docs.Caddyfile serves it at / with a 200 /health. The deployment edge strips the public /products/dokime/docs prefix.

On protected main or version tags, changed docs can publish when Linux is verified and an eligible Docker/Dind runner is online. mise run ci:publish:docs uses pinned Docker and Buildx tools, builds and loads the image, probes /health and /, cleans up the smoke container, and pushes $CI_REGISTRY_IMAGE/docs:$CI_COMMIT_SHA. Publication is visibly omitted from the discovery report when prerequisites do not hold.

When DEPLOYMENT_PROJECT is set, the downstream deployment receives DEPLOY_ENVIRONMENT (staging for main, production for version tags), DEPLOY_SERVICE=dokime-docs, and the immutable DEPLOY_IMAGE. The deployment repository owns deployment credentials and rollout logic. Trigger failures fail this pipeline as well.