Lean Ci (Ansible) — Agents

---
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:
  origin: Ansible
  author: APME Team
  version: 2.0.0
---

# Lean CI

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.

## Principles

1. **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.

2. **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-requirements ci/tox-requirements.txt tox -e <env>`.
   The local `uv.lock` also resolves tox through `ansible-dev-tools`; keep
   that tox version and the documented local install pin aligned with the CI
   pin. `tox-uv` is CI-only and is pinned in `ci/tox-requirements.txt` (#591).

3. **No scattered version pinning.** Python version is in `pyproject.toml`
   (`requires-python`). Node is in `frontend/package.json` (`engines.node`).
   Tool versions are managed in `.pre-commit-config.yaml`
   (ruff, mypy) and `pyproject.toml` (deps). Not in workflow YAML.
   Carve-out: CI installs `tox`/`tox-uv` with `uvx` from
   `ci/tox-requirements.txt` rather than the project lock. For local dev,
   tox is also resolved in `uv.lock` via `ansible-dev-tools`; keep that
   version and the documented `uv tool install` pin aligned with the CI
   tox pin. `tox-uv` is CI-only and remains outside the project lock.
   Jobs that need Node use `actions/setup-node` with
   `node-version-file: frontend/package.json`.

4. **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.
   **Exception:** `test.yml` jobs `ui` and `ui-workflow-pack` use
   `actions/setup-node` because `tox -e ui` / `ui-workflow-pack` need `npm`.

5. **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 as orchestration layer (ADR-047)

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=70`) | `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 ui-workflow-pack` | Pack `@apme/ui-workflow` release tarball | `test.yml` |
| `tox -e grpc` | Regenerate gRPC stubs | manual |
| `tox -e helm` | Lint + package Helm chart | `helm-charts.yml` |
| `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 e2e` | End-to-end pod scan (rebuild + start + scan + assert) | manual |
| `tox -e pm` | Build + start + open browser | manual |

Install: `uv tool install tox==4.61.4 --with tox-uv==1.36.0` (match CI pins, #591)

## Workflow structure

CI has seven workflows in `.github/workflows/`:

- **prek.yml**: Runs `prek` (ruff lint, ruff format, mypy strict, pydoclint,
  uv-lock). Quality gate for code style and type safety. Uses
  `j178/prek-action` directly for its built-in caching — intentional per
  ADR-047, not a violation of principle 2; `tox -e lint` is the local
  equivalent. Do not "fix" this without amending ADR-047.
- **test.yml**: Runs `tox -e unit`, `tox -e integration`, `tox -e ui`,
  `tox -e ai`, and `tox -e ui-workflow-pack` as separate jobs. Quality gate
  for correctness. Coverage threshold is enforced via `--cov-fail-under` in
  `tox.ini`.
- **container-images.yml**: Builds and pushes multi-arch container images
  (`linux/amd64` + `linux/arm64`, ADR-063) to GHCR on `main`, version tags, and
  `workflow_dispatch`, then merges manifests via
  `containers/ci/merge-manifests.sh` (image list: `containers/ci/images.txt`).
- **helm-charts.yml**: Lints/packages the Helm chart (`tox -e helm`) and
  publishes to GitHub Pages via chart-releaser when `deploy/helm/apme/**`
  changes on `main`. Also publishes values profiles
  (`tox -e helm-pages-profiles`) to `https://ansible.github.io/apme/`.
- **deprecation-scrape.yml**: Monthly cron scraping ansible-core for deprecation
  gaps.
- **pr-feedback.yml**: Labels PRs with failing checks or merge conflicts.
- **ui-workflow-release.yml**: Publishes the `@apme/ui-workflow` release tarball.

`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.

## Rules for modifications

When adding or modifying CI:

- **DO** add new build logic as a tox environment in `tox.ini`, then call it
  from the workflow with `uvx --with-requirements ci/tox-requirements.txt tox -e <env>`.
- **DO** use SHA-pinned actions with a tag comment (e.g.,
  `actions/checkout@de0fac2e...  # v6`).
- **DO** set `FORCE_COLOR: 1` and `PY_COLORS: 1` as workflow-level env vars
  for readable CI logs.
- **DO** use `ubuntu-24.04` explicitly rather than `ubuntu-latest`.
- **DO NOT** put multi-line shell scripts in `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.
- **DO NOT** add `actions/setup-python` or other setup actions. `setup-uv`
  handles the Python toolchain.
- **DO NOT** hardcode tool versions in YAML. Versions belong in
  `.pre-commit-config.yaml` or `pyproject.toml`.
- **DO NOT** add secrets or publishing steps without explicit approval.