CI Workflows and Repository Automation

Use this page to understand the GitHub Actions workflows contributors hit most often and to keep the workflow list grouped predictably in the GitHub UI.

Naming Convention

GitHub lists workflows by the top-level name field.

Sambee groups workflow display names by operational purpose using Area: Subject.

Current workflow groups are:

• CI.
• Release.
• Deploy.
• Security.
• Admin.

Keep new names short, stable, and grouped by what the workflow does rather than by how it is triggered.

Workflow Map

GitHub also shows repository-level features such as Dependabot updates and Dependency graph.

Those are not repository workflows, so their display names are not controlled by these YAML files.

CI: Test

CI: Test is the main validation workflow for pushes to main, pull requests against main, and manual dispatch.

It first detects which top-level product areas changed, then fans out only the relevant jobs for:

• backend
• frontend
• companion

Manual dispatch runs all three areas.

The workflow ends with a single gate job so branch protection can depend on one stable required check instead of a changing set of per-area jobs.

Caching Model

The test workflow uses layered caching to reduce repeated setup work while keeping dependency inputs explicit.

Current cache layers include:

• backend/.venv caching keyed by the resolved backend requirement files and Python version.
• backend/.mypy_cache caching keyed by backend Python source changes.
• actions/setup-node npm download caching for frontend and companion jobs.
• frontend/node_modules caching keyed by frontend/package-lock.json.
• Rust build caching for companion/src-tauri.

Treat those cache keys as reviewed dependency inputs, not as disposable generated noise.

When dependency manifests or lockfiles change, commit the corresponding lockfile updates in the same pull request so cache invalidation and dependency review stay aligned.

Local Parity

For fast local iteration, use ./scripts/test.

When you want a closer CI-style pass, run the per-subsystem checks from Test Strategy Overview and keep lockfile-driven installs intact.

CI: Lint

CI: Lint applies the same change-detection pattern, then runs the repository’s static checks for only the affected areas.

Current coverage includes:

• backend Ruff checks and formatting validation.
• frontend Biome validation.
• companion Clippy, Rustfmt, and Biome validation.

The workflow also ends with one gate job so branch protection can depend on a stable result.

Runner Distro Policy

Sambee does not require every GitHub Actions job to run on the same base distro.

Instead, the rule is:

• jobs that validate production-like runtime behavior or install native runtime dependencies should follow the same Debian family used by the production image and the dev container
• jobs that only run language-level checks, dependency audits, repository automation, or other host-agnostic validation can stay on ubuntu-latest

Current Debian-family jobs include:

• the backend job in CI: Test
• the validate-tests job in Release: Create Docker Image

Those jobs run inside the pinned python:3.13.12-slim container because scripts/install-system-deps now requires distro-provided ImageMagick 7, while the default Ubuntu GitHub-hosted runner image still resolves imagemagick to ImageMagick 6.

Current jobs that intentionally remain on ubuntu-latest include:

• change-detection, label-sync, and website deployment workflows
• pure Python lint, lockfile freshness, and dependency-audit workflows
• frontend-only and companion-only validation workflows
• Docker build, smoke-test, and vulnerability-scan workflows, where the distro-sensitive logic runs inside the built image rather than on the host runner

When adding or changing a workflow, treat runner distro as part of the test contract whenever a job installs OS packages or validates native behavior.

CI: Check Backend Lockfiles

CI: Check Backend Lockfiles protects the reviewed Python dependency workflow.

It runs scripts/refresh-backend-lockfiles --check on pushes, pull requests, and manual runs that touch backend requirement inputs, generated lockfiles, or the refresh script itself.

Use this as the fast failure signal when requirement files and generated lockfiles drift apart.

For the broader dependency-update workflow, use Dependency and Release Workflow .

Admin: Sync Labels

Admin: Sync Labels keeps repository labels aligned with .github/labels.yml.

It is intentionally conservative.

• Dependabot-related labels should stay declared in .github/labels.yml.
• The workflow uses skip-delete: true, so labels not declared there are left alone.

That keeps automation-owned labels deterministic without forcing the repository to delete every manually created label.

Related Workflow Docs

Use the more specific pages for the workflows that have dedicated operational guidance:

• Dependency Security and Dependabot
• Docker Release Overview
• Companion Release Overview
• Set Up Cloudflare Pages Publishing