Lumotia/docs/architecture-map/05-core-storage-hotkey-build/ci-pipeline.md

name, type, slice, last_verified

name	type	slice	last_verified
CI pipeline	architecture-map-page	05-core-storage-hotkey-build	2026/05/09

CI pipeline

Where you are: Architecture map → Core, Storage, Hotkey, Build → CI pipeline

Plain English summary. Three GitHub Actions workflows. check.yml runs per-push compile + lint + library tests + frontend build on Linux, Windows, and macOS. build.yml produces installer artefacts (.AppImage/.deb on Linux, .msi/.exe on Windows, .dmg/.app on macOS) for tag pushes and on-demand. audit.yml runs cargo-audit and npm-audit weekly.

At a glance

• Files: .github/workflows/check.yml, build.yml, audit.yml.
• LOC: 7,017 + 7,157 + 1,443 bytes respectively.
• Shared concerns across check and build: same Linux / macOS / Windows system-package install steps (libwebkit2gtk, Vulkan SDK, libclang for bindgen), same Swatinem/rust-cache@v2 cache scoping (workspaces: . because the workspace target dir is ./target, not src-tauri/target — this was the silent miss that made Windows checks slow).

check.yml — per-push compile + lint + tests

Triggers

on: [push, pull_request]
concurrency:
  group: check-${{ github.ref }}
  cancel-in-progress: true   # newer push supersedes older

Jobs

rust — matrix

strategy:
  fail-fast: false
  matrix:
    os: [ubuntu-22.04, windows-latest, macos-latest]

Steps per OS:

1. Install system deps — libwebkit2gtk-4.1, libappindicator3, librsvg2, libasound2, libudev, patchelf, cmake, build-essential, libclang, clang, libvulkan, glslang-tools, spirv-tools (Linux); Homebrew vulkan-headers, vulkan-loader, molten-vk, shaderc, llvm (macOS); choco llvm + vulkan-sdk (Windows). Each install resolves LIBCLANG_PATH / VULKAN_SDK dynamically so a minor SDK version bump does not hardcode-break the step.
2. dtolnay/rust-toolchain@stable with rustfmt, clippy.
3. Swatinem/rust-cache@v2 with workspaces: . and shared key lumotia-${{ matrix.os }}.
4. cargo check --workspace --all-targets.
5. cargo fmt --all -- --check.
6. cargo clippy --workspace --all-targets -- -D warnings.
7. cargo test --workspace --lib (Linux only, gated on matrix.os == 'ubuntu-22.04').
8. cargo audit (Linux only).

The Linux-only gating on tests + audit keeps macOS and Windows legs focused on compile coverage. The library-tests-only flag (--lib) excludes integration tests that need a runtime / GPU.

frontend — Linux only

1. Setup Node 20.
2. npm ci.
3. npm audit --audit-level=high.
4. npm run build — Vite-only build (no tauri build).
5. svelte-check for type and template errors.

Why the workspace cache scope matters

The original CI step pointed Swatinem/rust-cache@v2 at workspaces: src-tauri. The workspace target dir is at ./target (defined by the repo-root Cargo.toml), not src-tauri/target. That meant the cache silently missed every run, and Windows check runs felt like they recompiled sqlx from scratch every time. Documented inline at check.yml. The current scope workspaces: . is the fix.

build.yml — release artefacts

Triggers

on:
  push:
    tags: ['v*']             # tagged releases (v0.1.0, v0.2.0, ...)
  workflow_dispatch:          # manual, any branch
    inputs:
      tag_name:
        description: 'Optional tag name to attach the build to'
        required: false

workflow_dispatch lets us build a Windows binary on demand to dual-boot test without cutting a release.

Concurrency

concurrency:
  group: build-${{ github.ref }}
  cancel-in-progress: false   # release builds finish even on tag re-pushes

Different from check.yml: a release build is too expensive to abandon mid-flight.

Matrix

include:
  - os: ubuntu-22.04   artefacts: *.AppImage, *.deb
  - os: windows-latest artefacts: *.msi,      *.exe
  - os: macos-latest   artefacts: *.dmg,      *.app

Steps

1. System deps (same as check.yml).
2. Rust toolchain.
3. Cache (shared-key: lumotia-build-${{ matrix.os }}, distinct from check.yml's key so the build cache is not invalidated by check runs).
4. npm ci.
5. tauri-apps/tauri-action@v0 — runs tauri build. On tag pushes, attaches artefacts to a draft GitHub Release. Empty tagName for workflow_dispatch so we get artefacts only.
6. actions/upload-artifact@v4 — always uploads to the run page (30-day retention) so the workflow_dispatch path produces something downloadable too.
7. du -h on the produced bundle directory for visibility.

Code signing

Not configured. Both macOS (Apple Developer ID) and Windows (code-signing certificate) signing blocks are commented out in build.yml. Users hit Gatekeeper / SmartScreen on first run.

To enable later:

• macOS: uncomment the APPLE_SIGNING_IDENTITY / APPLE_CERTIFICATE / APPLE_CERTIFICATE_PASSWORD env block; add the corresponding repo secrets.
• Windows: uncomment the WINDOWS_CERTIFICATE / WINDOWS_CERTIFICATE_PASSWORD env block; add the secrets.

Documented in the file header.

audit.yml — weekly vulnerability scan

Triggers

on:
  schedule:
    - cron: "0 6 * * 1"    # Mondays 06:00 UTC
  workflow_dispatch:

Mondays so any advisory has the whole week to be triaged rather than landing on a Friday.

Jobs

cargo-audit

Uses rustsec/audit-check@v2 against the RustSec advisory DB. Fails on any unignored advisory.

npm-audit

npm audit --audit-level=high. Ignores low / moderate noise — only high and critical advisories warrant a bump.

Why a separate workflow?

A newly published advisory surfaces as its own failing run (easy to spot, easy to track) without blocking unrelated PR work. The same cargo audit runs as part of check.yml on every push, so this workflow is the catch-all for advisories that land between pushes.

Watch-outs

• cargo audit runs in two places. check.yml (Linux only, on every push) and audit.yml (weekly). The duplication is cheap and useful.
• tauri-action@v0 is unpinned. @v0 floats. A breaking change in tauri-action would surface on the next release attempt. Worth pinning to a specific version when v0.1 ships.
• macOS LIBCLANG_PATH resolution. brew --prefix llvm resolves to the Apple Silicon path on M-series runners (/opt/homebrew/...) and the Intel path on intel runners (/usr/local/...). The dynamic resolution handles both.
• Linux runners use Ubuntu 22.04, not 24.04. Pinned because 22.04's libwebkit2gtk-4.1 package is stable; 24.04's namespace shifted. Worth re-evaluating once GitHub Actions retires 22.04.
• No nightly clippy. The -D warnings clippy step uses stable. A nightly canary job would catch upcoming lint changes earlier.

See also

• Workspace Cargo.toml — the release profile this CI consumes.
• Dev launcher and scripts — local equivalent.