Jon Chery
7ba72bf656
EXECUTE stage. Authors the modules-lifecycle pipeline that matrix-tests
every L1 module's examples/{simple,complex}.yml contracts through
apply→modify→destroy against live AWS. No per-module Python.
New files:
- pipelines/modules-lifecycle.yml: declarative contract (5 stages:
platform-vpc-apply, lifecycle-apply, lifecycle-modify, lifecycle-destroy,
platform-vpc-destroy). Matrix over 12 L1 modules.
- .gitea/workflows/modules-lifecycle.yml + .github/workflows/modules-lifecycle.yml:
byte-identical workflows. 3 jobs: platform-vpc-apply (prerequisite),
lifecycle (matrix of 12 modules × apply/modify/destroy), platform-vpc-destroy
(always runs, cleanup). Triggers: pull_request to main + workflow_dispatch.
- schemas/modules-lifecycle-pipeline.schema.json: schema for the new pipeline
shape (extends pipeline.schema.json with workflow_dispatch + matrix).
Tests (tests/test_pipeline_contract.py):
- TestModulesLifecyclePipeline: 12 tests (schema valid, contract validates,
byte-identical, workflow name, 3 jobs, triggers, matrix lists all 12 L1
modules, apply/modify/destroy steps present, platform-vpc-destroy always runs).
pipelines/README.md: added modules-lifecycle to the pipeline table.
Regression: 479 passed, 0 skipped, 5 deselected (slow).
---ci---
project: acdl
phase: P59
milestone: v1.11
status: execute
---/ci---
45 lines
2.9 KiB
Markdown
45 lines
2.9 KiB
Markdown
# 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`) |
|
|
| ACDL Modules Lifecycle | `modules-lifecycle.yml` | `platform-vpc-apply`, `lifecycle-apply`, `lifecycle-modify`, `lifecycle-destroy`, `platform-vpc-destroy` | PR to `main` + `workflow_dispatch` |
|
|
|
|
## How to Write a Pipeline
|
|
|
|
1. YAML structure: `name`, `environment`, `triggers` (with `push` and `pull_request` branch arrays), `runner`, `python_version`, and a `stages[]` list.
|
|
2. Each stage is an object with `name`, `command`, `required` (boolean), and optional `install` (pip install command) + `description` (human-readable summary).
|
|
3. Validate the resulting YAML against `schemas/pipeline.schema.json` (CI) or `schemas/deploy-pipeline.schema.json` (deploy).
|
|
|
|
## How to Wire a Pipeline
|
|
|
|
1. Create byte-identical workflow YAMLs in `.gitea/workflows/<name>.yml` and `.github/workflows/<name>.yml`.
|
|
2. Both workflows must implement the same stages, commands, triggers, and runner declared in the contract.
|
|
3. `scripts/run_ci.sh` mirrors `ci.yml` locally so the same stages run without a forge.
|
|
4. 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
|
|
|
|
1. Create `pipelines/<name>.yml` using the structure above.
|
|
2. Create or extend the schema in `schemas/` for the new pipeline shape.
|
|
3. Create byte-identical workflow YAMLs in `.gitea/workflows/<name>.yml` and `.github/workflows/<name>.yml`.
|
|
4. Extend `scripts/run_ci.sh` if a local mirror of the new pipeline is needed.
|
|
5. Write or extend tests in `tests/test_pipeline_contract.py` to assert schema validity and workflow conformance. |