CI/CD 파이프라인 다이어그램

Apothem 생태계의 모든 변경을 게이트하는 빌드 · 검증 · 게시 워크플로의 구조적 지도입니다. 이 문서는 시각화 표면을 설치합니다. 이 문서가 설명하는 GitHub Actions 워크플로 파일은 .github/workflows/(예: ci.yml과 release.yml)에 있으며, 릴리스 도구는 scripts/release/에 있습니다.

파이프라인 형태Copy 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

레인 역할Copy Anchor Link

• 정적 분석 레인 — 빠른 피드백. Ruff는 Python 스타일과 엄선된 규칙 집합을 다룹니다. mypy는 strict 모드로 타입 규율을 강제합니다. 프런트매터 검증기는 규칙, 스킬, 위임된 워커, 명령에 대한 아티팩트 스키마 준수를 게이트합니다. markdownlint는 이 레인에 속하지 않습니다. Markdown 파일이 바뀌면 Markdown Lint 워크플로가 CI에서 이 도구의 pre-commit 훅을 실행합니다(Markdown 규약 참조).
• 테스트 레인 — pytest tests/hooks는 전체 이벤트 매트릭스에 대해 훅 런타임을 실행합니다. validate_ecosystem.py는 아티팩트 간 일관성을 위한 주요 구조 게이트입니다. chaos_pass.py는 main을 대상으로 하는 push와 pull request에서 CI 품질 작업으로 실행되며(경로 필터 적용), 저하된 입력에서의 품질 저하를 잡아냅니다. src/apothem/benchmarks/ 아래의 클래스별 벤치마크 드라이버는 pytest 스위트를 통해 CI에서 실행되며, metrics 작업을 통해서도 실행됩니다. CI에서 pytest 전체 실행마다 tests/unit/test_benchmarks.py가 수집되며, 이 파일은 bench_install.py를 제외한 모든 드라이버를 호출합니다. metrics 작업은 scripts/dev/collect_metrics.py를 실행하고, 이 스크립트는 bench_hooks.py --json을 실행하여 결과를 hook_e2e_ms로 기록합니다. bench_tests.py와 bench_install.py는 make benchmarks에서만 실제 실행 시간을 측정합니다. 어떤 워크플로도 make benchmarks를 실행하지 않습니다.
• 보안 레인 — ci.yml의 gitleaks는 실수로 커밋된 자격 증명을 잡아냅니다. 라이선스 감사(license-audit.yml)는 허용 목록에 없는 의존성 라이선스가 있으면 실패합니다. 이 감사는 매주 실행되며, 의존성 또는 라이선스 파일이 바뀔 때도 실행됩니다. REUSE 게이트(reuse.yml)는 모든 변경에서 실행되며, 파일에 라이선스 줄이 없거나 SPDX 표현식이 파싱되지 않으면 실패합니다. release.yml은 태그가 지정된 각 릴리스에 대해 SBOM을 생성합니다.
• 게시 레인 — 릴리스 워크플로는 태그 push로 트리거됩니다. npm 및 VS Code 게시기는 기존 태그에 대해 수동 디스패치로 다시 실행할 수도 있습니다. 서명된 태그 검증은 릴리스 브랜치의 출처를 확인하며, 릴리스 노트는 CHANGELOG.md의 Keep-A-Changelog 형식에서 파생됩니다. 프로젝트 웹사이트는 빌드 입력을 건드리는 main push 시, 또는 수동 디스패치 시 site/dist/에서 GitHub Pages 대상으로 게시됩니다.

구체적 구성Copy Anchor Link

실제 워크플로 파일(.github/workflows/ci.yml, .github/workflows/release.yml 등)은 저장소에 있습니다. 이 다이어그램은 앞으로 모든 구성이 따르는 정규 형태를 정의합니다.

권위 있는 상호 참조Copy Anchor Link

• pyproject.toml — Ruff / mypy / pytest 구성의 진실의 출처.
• scripts/dev/validate_ecosystem.py — 주요 아티팩트 간 게이트.
• scripts/dev/validate_hooks.py — 훅 전용 구조 검증.
• scripts/dev/chaos_pass.py — 구성된 각 훅에 대한 적대적 스윕.
• src/apothem/benchmarks/ — 클래스별 런타임 예산 검증기.
• site/content/docs/developer-guide.mdx — 운영자 대상 기여자 워크플로.
• CHANGELOG.md — 릴리스 노트 출처.