Jon Chery
d830357230
---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).
63 lines
2.3 KiB
Markdown
63 lines
2.3 KiB
Markdown
# 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):
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
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](../pipeline/versioning). |
|
|
| `module` | string | yes | Module name from the registry — any primitive or module (e.g. `static-asset`, `microservice`, `s3`). See the [module catalog](../modules/). |
|
|
| `environment` | string | yes | The platform-managed environment to deploy to (e.g. `dev`). See [Environments](../environments/). |
|
|
| `inputs` | object | yes | Module-specific inputs (see the module's README). |
|
|
|
|
## Validation
|
|
|
|
The contract is validated against
|
|
[`schemas/contract.schema.json`](https://github.com/acdl/acdl/blob/main/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`](https://github.com/acdl/acdl/blob/main/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](../consumer-guide/) for the multi-contract pattern. |