- **1. App code** — the consumer's service, at the top level of the repo
- **2. A contract** — a single YAML file: module, environment, inputs
```yaml
uses: acdl/pipelines/deploy.yaml@v1.6
module: microservice
environment: dev
inputs:
cpu: 256
memory: 512
desired_count: 2
port: 8080
```
- **3. A one-line CI definition** — a thin `uses:` wrapper pointing at a versioned platform workflow
- The developer does **not**: write infrastructure modules, clone the platform repo, hold cloud credentials, or maintain a state backend
---
# The Developer Feedback Loop
Story beat: Once you push, here's what you see — in real time, in your own logs.
Developers see **what the platform is doing**, in real time. Testing
- **Streamed output by default** — the infrastructure plan, policy-check results, and each check record flow to stdout
- **PR comments after every successful pipeline stage** — a developer always knows where they stand without refreshing a dashboard
- **Clear, explainable halt reasons** — a policy violation, an insufficient confidence signal, or a missing attestation. **Never an opaque debugging exercise.**
- **Connection strings posted as PR comments** — human-readable, no hunting
- **Runtime secrets in encrypted Parameter Store** — KMS-encrypted, namespaced, **no raw secrets in logs**
- **Errors become GitHub issues, automatically** — a failed deploy opens an issue on the platform repo
---
# Versioned, Predictable Releases
Story beat: You control when you absorb platform improvements — no surprise upgrades.
Consumers control **when** they absorb platform improvements. Testing
- **Floating MAJOR + MINOR tags** (e.g. `@v1.6`) — a consumer automatically receives patch updates within the line
- **Semantic versioning with a clear contract:** interface → MAJOR, behavior → MINOR, lifecycle → PATCH
- **A consumer can pin to an exact version** for maximum stability, or float on MAJOR only (`@v1`) to absorb new features on their own cadence
- **Unversioned references (`@main`, bare) are discouraged** — the versioned tag is the only immutability lever
- **Automated release job** computes the next semver on merge to main, creates the tag, and updates the floating tags
---
# Friendly Onboarding
Story beat: First impressions matter — the platform fails gracefully, not opaquely.
First impressions of a platform are made **when it fails for the first time.** The platform fails gracefully. Testing
When no environment is bound, the platform emits a **user-friendly onboarding prompt** instead of failing opaquely:
1. That no environment is bound to their repo yet
2. What the platform will provision on their behalf (account, network, state, role)
3. The expected turnaround for the platform team to grant the environment
4. How to request an environment
The pipeline then **exits without attempting a deployment** — no partial state, no confusing errors.
Citizen developer onboarding path: planned
---
# Safe Promotion Path
Story beat: Promotion is a workflow choice, not a contract edit — and the bar rises automatically.
The contract is environment-agnostic. The platform raises the bar automatically.
| **Approach A — One contract, one job per environment.** Environment passed by each job. ```yaml jobs: dev: uses: acdl/.github/workflows/deploy.yml@v1.6 with: { contract: .acdl/contract.yaml, environment: dev } qa: needs: dev uses: acdl/.github/workflows/deploy.yml@v1.6 with: { contract: .acdl/contract.yaml, environment: qa } ``` | **Approach B — Environment-specific contracts.** When inputs differ per environment. ```yaml jobs: dev: uses: acdl/.github/workflows/deploy.yml@v1.6 with: { contract: .acdl/contract-dev.yaml } qa: needs: dev uses: acdl/.github/workflows/deploy.yml@v1.6 with: { contract: .acdl/contract-qa.yaml } ``` |