CI/CD Pipeline Diagram

The structural map of the build · validate · publish workflow that gates every change to the Apothem ecosystem. This document installs the visualization surface. The GitHub Actions workflow files it describes live in .github/workflows/ (for example ci.yml and release.yml), and the release tooling lives in scripts/release/.

Pipeline shapeCopy Anchor Link

%%{ init: { "theme": "neutral" } }%%
%% verified: 2026-04-27 %%
%% provenance: pyproject.toml + scripts/dev/validate_ecosystem.py + scripts/dev/validate_hooks.py %%
%% cross-reference: site/content/docs/developer-guide.mdx (contributor workflow) %%
flowchart LR
    accTitle: CI/CD pipeline shape
    accDescr: Left-to-right flowchart of the apothem CI CD pipeline showing build, test, lint, type-check, security scan, docs build, package, sign, and publish stages with branch protection gates between them.
    subgraph Trigger["Trigger surface"]
        PR["Pull request opened or updated"]
        PUSH["Push to main"]
        TAG["Tag release vX.Y.Z"]
    end
    subgraph Static["Static analysis lane"]
        LINT["Ruff lint + format check"]
        TYPE["Mypy strict"]
        FRONT["Frontmatter validator"]
    end
    subgraph Test["Test lane"]
        PYTEST["pytest tests/hooks"]
        ECO["validate_ecosystem.py"]
        CHAOS["chaos_pass.py (CI quality job)"]
        BENCH["src/apothem/benchmarks/ (unit tests in CI, bench_hooks in metrics job)"]
    end
    subgraph Security["Security lane"]
        SECRETS["Secret scan"]
        SBOM["SBOM generation (tags only)"]
        LICENSE["License audit"]
    end
    subgraph Publish["Publish lane (tags only)"]
        SIGN["Signed-tag verification"]
        ATTEST["Provenance attestation"]
        RELEASE["Release notes from CHANGELOG.md"]
    end
    DOCS["Project website publish"]
    PR --> Static
    PR --> Test
    PR --> Security
    PUSH --> Static
    PUSH --> Test
    PUSH --> Security
    PUSH --> DOCS
    TAG --> Static
    TAG --> Test
    TAG --> Security
    TAG --> Publish
    Static --> GATE{All lanes green?}
    Test --> GATE
    Security --> GATE
    GATE -->|yes| MERGE[Merge / publish]
    GATE -->|no| BLOCK[Block · surface failures · request fix]
    Publish --> MERGE

Lane rolesCopy Anchor Link

• Static analysis lane — fast feedback. Ruff covers Python style and a curated rule set; mypy enforces type discipline at strict; the frontmatter validator gates artifact-schema compliance for rules, skills, delegated workers, and commands. markdownlint is not in this lane: the Markdown Lint workflow runs its pre-commit hook in CI on changed Markdown (see Markdown conventions).
• Test lane — pytest tests/hooks exercises the hook runtime against the full event matrix; validate_ecosystem.py is the primary structural gate for cross-artifact consistency; chaos_pass.py runs in the CI quality job on pushes and pull requests to main (path-filtered) to catch degradation under degraded inputs. The per-class benchmark drivers under src/apothem/benchmarks/ run in CI through the pytest suite and through the metrics job. Each full pytest run in CI collects tests/unit/test_benchmarks.py, which calls every driver except bench_install.py. The metrics job runs scripts/dev/collect_metrics.py, which runs bench_hooks.py --json and records the result as hook_e2e_ms. bench_tests.py and bench_install.py time real runs only under make benchmarks. No workflow runs make benchmarks.
• Security lane — gitleaks in ci.yml catches accidental committed credentials. The license audit (license-audit.yml) fails on a dependency license outside its allowlist. It runs weekly and when dependency or license files change. The REUSE gate (reuse.yml) runs on every change and fails when a file has no license line or an SPDX expression does not parse. release.yml generates the SBOM for each tagged release.
• Publish lane — the release workflows are triggered by tag pushes; the npm and VS Code publishers can also be re-run by manual dispatch for an existing tag. Signed-tag verification confirms release-branch provenance; release notes derive from CHANGELOG.md Keep-A-Changelog format. The project website publishes from site/dist/ to the GitHub Pages target on pushes to main that touch its build inputs, or on manual dispatch.

Concrete configurationCopy Anchor Link

The actual workflow files (.github/workflows/ci.yml, .github/workflows/release.yml, etc.) are in the repository. This diagram defines the canonical shape every future configuration mirrors.

Authoritative cross-referencesCopy Anchor Link

• pyproject.toml — Ruff / mypy / pytest configuration source of truth.
• scripts/dev/validate_ecosystem.py — the primary cross-artifact gate.
• scripts/dev/validate_hooks.py — hook-specific structural validation.
• scripts/dev/chaos_pass.py — adversarial sweep of every configured hook.
• src/apothem/benchmarks/ — per-class runtime budget verifiers.
• site/content/docs/developer-guide.mdx — the operator-facing contributor workflow.
• CHANGELOG.md — release-note source.