Files

T

Jon Chery 031887ec56 refactor(P57): contract surface redesign + rename + .yml repo-wide

Contract surface redesign:
- New top-level fields: id (3-6 char acronym → stack.name), name (full → stack.title),
  infrastructure (map keyed by module name, replaces module:)
- Drop uses: field (dead reference; version pin lives in CI workflow uses: line)
- Drop top-level module/inputs (now nested under infrastructure map)
- Per-module optional version (defaults to latest published from registry)
- Multi-module contracts: one file deploys N modules in one pipeline run,
  resource IDs namespaced with module name to avoid collisions
- stack.schema.json: add optional title field for display name

Rename:
- pipelines/deploy.yaml → pipelines/contract.yml (declarative spec, not a pipeline)
- pipelines/ci.yaml → pipelines/ci.yml
- All 44 .yaml files → .yml repo-wide (contracts, module examples, kyverno policies)
- .acdl/contract.yaml → .acdl/contract.yml

Resolver (core/contract_resolver.py):
- Rewrite resolve() to loop infrastructure map, default version to latest,
  merge module fragments into one stack with namespaced resource IDs
- _latest_version() picks highest non-deprecated from registry
- _namespace_resources() prefixes IDs + rewrites ref: expressions for multi-module
- Single-module path: unprefixed IDs (backward compatible)

Verification:
- 494 tests pass (0 contract-shape failures)
- Local E2E passes (contract → resolver → adapter → local ECS HTTP 200 → outbox)

---ci---
project: acdl
phase: 57
milestone: v1.10.2
status: execute
---/ci---

2026-07-27 21:37:40 +00:00

2.7 KiB

Raw Blame History

ACDL Pipelines

Overview

ACDL uses declarative pipeline contracts (YAML) as the single source of truth. Both Gitea and GitHub workflows implement the same contract (byte-identical). The shell runner (scripts/run_ci.sh) mirrors the CI pipeline locally so that every stage that runs in CI can be reproduced on a developer machine without a forge.

Existing Pipelines

Pipeline	File	Stages	Triggers
ACDL CI	`ci.yml`	`lint`, `test`, `check-only`	push/PR to `main`
ACDL Deploy	`contract.yml`	`validate-contract`, `resolve-stack`, `terraform-plan`, `checkov`, `confidence`, `apply`, `publish-outputs`, `deploy-uptime`, `comment-outputs`	push/PR to `main` (consumer repos via `workflow_call`)

How to Write a Pipeline

YAML structure: name, environment, triggers (with push and pull_request branch arrays), runner, python_version, and a stages[] list.
Each stage is an object with name, command, required (boolean), and optional install (pip install command) + description (human-readable summary).
Validate the resulting YAML against schemas/pipeline.schema.json (CI) or schemas/deploy-pipeline.schema.json (deploy).

How to Wire a Pipeline

Create byte-identical workflow YAMLs in .gitea/workflows/<name>.yml and .github/workflows/<name>.yml.
Both workflows must implement the same stages, commands, triggers, and runner declared in the contract.
scripts/run_ci.sh mirrors ci.yml locally so the same stages run without a forge.
Consumer repos reference the deploy pipeline via uses: acdl/.github/workflows/deploy.yml@vX.Y.

Dependencies

scripts/run_ci.sh — local CI mirror that runs the ci.yml stages.
scripts/run_platform.sh — platform pipeline runner that implements the contract.yml stages.
Workflow YAMLs in .gitea/workflows/ and .github/workflows/.
Schemas in schemas/ (pipeline.schema.json, deploy-pipeline.schema.json).

How to Test Pipelines

tests/test_pipeline_contract.py — validates each pipeline YAML against its schema, asserts workflow conformance (byte-identical Gitea/GitHub workflows with the same stages/commands/triggers), and tests scripts/run_ci.sh execution against the contract.

Adding a New Pipeline

Create pipelines/<name>.yml using the structure above.
Create or extend the schema in schemas/ for the new pipeline shape.
Create byte-identical workflow YAMLs in .gitea/workflows/<name>.yml and .github/workflows/<name>.yml.
Extend scripts/run_ci.sh if a local mirror of the new pipeline is needed.
Write or extend tests in tests/test_pipeline_contract.py to assert schema validity and workflow conformance.

2.7 KiB Raw Blame History