CI/CD-Pipeline-Diagramm

Die strukturelle Karte des Build-, Validierungs- und Veröffentlichungs-Workflows, der jede Änderung am Apothem-Ökosystem kontrolliert. Dieses Dokument installiert die Visualisierungsoberfläche. Die GitHub-Actions-Workflow-Dateien, die es beschreibt, liegen in .github/workflows/ (zum Beispiel ci.yml und release.yml), und das Release-Werkzeug liegt in scripts/release/.

Pipeline-FormCopy 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

SpurrollenCopy Anchor Link

• Spur für statische Analyse — schnelles Feedback. Ruff deckt den Python-Stil und ein kuratiertes Regelwerk ab; mypy erzwingt Typdisziplin im Strict-Modus; der Frontmatter-Validator prüft die Schemakonformität der Artefakte für Regeln, Skills, delegierte Worker und Befehle. markdownlint gehört nicht zu dieser Spur: Sein Pre-Commit-Hook läuft in der CI im Markdown-Lint-Workflow, wenn sich Markdown-Dateien ändern (siehe Markdown-Konventionen).
• Test-Spur — pytest tests/hooks übt die Hook-Laufzeit gegen die vollständige Ereignismatrix aus; validate_ecosystem.py ist das primäre strukturelle Gate für artefaktübergreifende Konsistenz; chaos_pass.py läuft im CI-Qualitätsjob bei Pushes und Pull Requests auf main (pfadgefiltert), um Verschlechterungen bei beeinträchtigten Eingaben zu erkennen. Die klassenbezogenen Benchmark-Treiber unter src/apothem/benchmarks/ laufen in CI über die pytest-Suite und über den Job metrics. Jeder vollständige pytest-Lauf in CI sammelt tests/unit/test_benchmarks.py, das jeden Treiber außer bench_install.py aufruft. Der Job metrics führt scripts/dev/collect_metrics.py aus, das bench_hooks.py --json ausführt und das Ergebnis als hook_e2e_ms erfasst. bench_tests.py und bench_install.py messen echte Läufe nur unter make benchmarks. Kein Workflow führt make benchmarks aus.
• Sicherheits-Spur — gitleaks in ci.yml erkennt versehentlich committete Anmeldedaten. Das Lizenz-Audit (license-audit.yml) schlägt bei einer Abhängigkeitslizenz fehl, die nicht auf seiner Allowlist steht. Es läuft wöchentlich sowie dann, wenn sich Abhängigkeits- oder Lizenzdateien ändern. Das REUSE-Gate (reuse.yml) läuft bei jeder Änderung und schlägt fehl, wenn eine Datei keine Lizenzzeile hat oder ein SPDX-Ausdruck nicht geparst werden kann. release.yml erzeugt die SBOM für jedes getaggte Release.
• Veröffentlichungs-Spur — die Release-Workflows werden durch Tag-Pushes ausgelöst; der npm- und der VS-Code-Publisher lassen sich für einen bestehenden Tag auch per manuellem Dispatch erneut ausführen. Die Signed-Tag-Verifikation bestätigt die Herkunft des Release-Branches; die Release-Notes leiten sich aus CHANGELOG.md im Keep-A-Changelog-Format ab. Die Projekt-Website wird von site/dist/ auf das GitHub-Pages-Ziel veröffentlicht, bei Pushes auf main, die ihre Build-Eingaben berühren, oder bei manuellem Dispatch.

Konkrete KonfigurationCopy Anchor Link

Die tatsächlichen Workflow-Dateien (.github/workflows/ci.yml, .github/workflows/release.yml usw.) liegen im Repository. Dieses Diagramm definiert die kanonische Form, an der sich jede künftige Konfiguration ausrichtet.

Maßgebliche QuerverweiseCopy Anchor Link

• pyproject.toml — Quelle der Wahrheit für die Ruff- / mypy- / pytest-Konfiguration.
• scripts/dev/validate_ecosystem.py — das primäre artefaktübergreifende Gate.
• scripts/dev/validate_hooks.py — hook-spezifische strukturelle Validierung.
• scripts/dev/chaos_pass.py — adversarialer Durchlauf jedes konfigurierten Hooks.
• src/apothem/benchmarks/ — klassenbezogene Laufzeitbudget-Verifizierer.
• site/content/docs/developer-guide.mdx — der bedienerorientierte Contributor-Workflow.
• CHANGELOG.md — Quelle der Release-Notes.