// Guide for writing and modifying GitHub Actions workflows in this repository. Use when creating CI/CD pipelines, adding workflow jobs, modifying build steps, or debugging CI failures. Enforces the project's lean CI philosophy.
| name | lean-ci |
| description | Guide for writing and modifying GitHub Actions workflows in this repository. Use when creating CI/CD pipelines, adding workflow jobs, modifying build steps, or debugging CI failures. Enforces the project's lean CI philosophy. |
| argument-hint | [workflow-name] |
| user-invocable | true |
| metadata | {"author":"APME Team","version":"2.0.0"} |
This project follows a strict "CI as thin wrapper" philosophy. GitHub Actions workflows must never contain substantive build logic. All logic lives in locally-runnable tox environments; CI just calls them.
Every CI step must be reproducible locally. A developer should be able to run the exact same command on their laptop. If a step only works inside GitHub Actions, it violates this rule.
Workflows call tox environments, not inline shell. Build and test logic
belongs in tox.ini environments -- never in multi-line YAML run: blocks.
CI runs uvx --with tox-uv tox -e <env>.
No scattered version pinning. Python version is in pyproject.toml
(requires-python). Tool versions are managed in .pre-commit-config.yaml
(ruff, mypy) and pyproject.toml (deps). Not in workflow YAML.
Minimal setup actions. astral-sh/setup-uv and actions/checkout only.
No actions/setup-python (uv handles it). No other setup actions without
explicit justification.
Pin actions to commit SHAs. Mutable tags (@v4) allow upstream changes
to affect CI without review. Always pin to a full commit SHA with a comment
noting the tag (ADR-015).
tox is the sole developer orchestration tool. Every CI step maps to a tox environment that developers run locally.
| tox environment | What it does | CI workflow |
|---|---|---|
tox -e lint | Lint, format, type check (prek: ruff + mypy + pydoclint) | prek.yml |
tox -e unit | Unit tests with coverage (--cov-fail-under=36) | test.yml |
tox -e integration | Integration tests (requires OPA binary) | test.yml |
tox -e ai | AI extra tests (abbenay) | test.yml |
tox -e ui | Playwright UI tests | test.yml |
tox -e grpc | Regenerate gRPC stubs | manual |
tox -e build | Build container images | container-images.yml (GHCR) |
tox -e up | Start the APME pod | manual |
tox -e down | Stop the APME pod | manual |
tox -e pm | Build + start + open browser | manual |
Install: uv tool install tox --with tox-uv
CI has five workflows in .github/workflows/:
prek (ruff lint, ruff format, mypy strict, pydoclint,
uv-lock). Quality gate for code style and type safety.tox -e unit, tox -e integration, tox -e ui, and
tox -e ai as separate jobs. Quality gate for correctness. Coverage threshold
is enforced via --cov-fail-under in tox.ini.main.prek.yml and test.yml trigger on pull_request targeting main and use
concurrency groups with cancel-in-progress to avoid stacking runs on rapid
pushes.
When adding or modifying CI:
tox.ini, then call it
from the workflow with uvx --with tox-uv tox -e <env>.actions/checkout@de0fac2e... # v6).FORCE_COLOR: 1 and PY_COLORS: 1 as workflow-level env vars
for readable CI logs.ubuntu-24.04 explicitly rather than ubuntu-latest.run: blocks. If it needs more
than one command, it belongs in a tox environment or a script in scripts/.
The git dirty check is the one exception -- it is a CI-only guard with no
local equivalent.actions/setup-python or other setup actions. setup-uv
handles the Python toolchain..pre-commit-config.yaml or pyproject.toml.Audit documentation coverage against common user questions. Generates a Q&A matrix, searches docs/code for answers, flags gaps, and creates DRs for missing content. Use when asked to "audit docs", "check documentation coverage", "what questions can users answer", or before releases/demos.
Review and help prepare a contributor's pull request (upstream or fork). Use when the user asks to review a PR, get a contributor PR ready, update a contributor's branch, or ensure a PR meets project standards before merge. Follow this skill so contributor PRs are reviewed consistently and avoid rework (lint/test failures, outdated base, weak description).
Prepare and submit a pull request for the APME project. Syncs with upstream, creates a feature branch, runs quality gates (tox -e lint, tox -e unit), updates documentation and ADRs as needed, commits with conventional commits, then creates the PR via gh. Use when the user asks to submit, create, or open a pull request, or says "submit PR", "open PR", "create PR", "new PR".
Guide for handling pull request reviews, including automated (Copilot) and human reviewer feedback. Use when responding to PR comments, resolving review threads, or updating PRs after review.
Align branch name with artifact ID when they mismatch. Use when: renumbering a REQ/DR/ADR after branch creation, "branch name is wrong", "rename branch to match", or when PR review flags branch/artifact mismatch. Handles the git branch rename and remote update.
Reference for running lint, test, build, and pod commands via tox. Agents MUST use tox for all quality gates — never invoke pytest, ruff, mypy, prek, or shell scripts directly. This skill is the canonical lookup table for which tox environment to use.