Files

T

Jon Chery d830357230 docs(P21): restructure docs/ into Jekyll Pages site (REQ-54, REQ-55, REQ-56)

---ci---
project: acdl
phase: 21
milestone: v1.6
status: execute
---/ci---

Restructure docs/ into a Jekyll-style GitHub Pages site:
- docs/_config.yml (Pages config + nav, excludes internal/)
- docs/index.md (landing: platform + consumer model, Features, Roadmap)
- docs/modules/index.md (catalog: primitives + modules, normalized terms)
- docs/contracts/index.md (schema, fields, sample, multi-contract)
- docs/pipeline/index.md (CI + deploy pipeline, stages mermaid, streaming)
- docs/pipeline/versioning.md (module + deploy-pipeline versioning)
- docs/environments/index.md (platform-managed envs + onboarding, REQ-61)
- docs/consumer-guide.md (renamed from CONSUMER_GUIDE.md; GitHub-only,
  no .gitea, forge->platform runners, L2->modules, composition->pattern,
  updated mermaid with security-checks + infrastructure-apply)
- docs/architecture.md (consolidated from architecture.md +
  architecture-v1.0.md, current-architecture only, normalized terms:
  primitives/modules, platform runners, no L1/L2/forge/gitea in prose)
- Removed docs/architecture-v1.0.md (consolidated) + docs/CONSUMER_GUIDE.md
  (renamed).

No .ciagent/ or .gitea/ references in docs/. Consumer-facing terminology
normalized (L2->modules, L1->primitives, composition->pattern, forge->
platform runners).

2026-07-22 18:22:58 +00:00

2.3 KiB

Raw Permalink Blame History

Contracts

A consumer declares intent in a contract — a small YAML file that references the central deploy pipeline, names a module, selects an environment, and supplies module-specific inputs. The platform validates, resolves, and deploys it.

The contract file

A consumer repo keeps its contract at .acdl/contract.yaml. A minimal example (the static-asset module):

uses: acdl/pipelines/deploy.yaml@v1.4
module: static-asset
environment: dev
inputs:
  bucket_name: my-static-site-assets
  region: us-east-1

A microservice example:

uses: acdl/pipelines/deploy.yaml@v1.4
module: microservice
environment: dev
inputs:
  image: my-registry/my-microservice:latest
  port: 8080
  env:
    LOG_LEVEL: info

Fields

Field	Type	Required	Description
`uses`	string	yes	Reference to the central deploy pipeline, versioned with a floating MAJOR+MINOR tag (e.g. `acdl/pipelines/deploy.yaml@v1.4`). Bare or `@main` references are discouraged. See Versioning.
`module`	string	yes	Module name from the registry — any primitive or module (e.g. `static-asset`, `microservice`, `s3`). See the module catalog.
`environment`	string	yes	The platform-managed environment to deploy to (e.g. `dev`). See Environments.
`inputs`	object	yes	Module-specific inputs (see the module's README).

Validation

The contract is validated against schemas/contract.schema.json. An invalid contract (missing field, unknown module, wrong type) fails at the validate-contract stage with a clear error.

Sample contract

The reference example is contracts/static-asset.yaml, which uses @v1.4 as the canonical versioned uses: reference.

Multiple contracts

A consumer repo may contain more than one contract (e.g. one per service or one per environment). Each contract is a separate deployment; each is referenced by a CI definition in .github/workflows/ that invokes the central reusable workflow with the contract path. See the Consumer Guide for the multi-contract pattern.

2.3 KiB Raw Permalink Blame History