Path · Product teams
Own a product
Your product repository says what the product is made of and where it goes. Five CD workflows turn every change into a tested, approved product version and move approved versions on.
What you own
| File | What it says |
|---|---|
product.yaml | The components: the application's service charts, the data-pipeline package, the Databricks bundles |
configurations/helm.yaml | Product-wide settings for every landscape: web prefixes, constants, the list of allowed secret names, one key per service chart |
configurations/adf.yaml, databricks.yaml | Product-wide settings for the other components |
pipeline.config.yaml | The delivery ladder: landscapes in promotion order and their environments. For the first product it lists only dev/app01 today |
.github/workflows/cd-*.yml | Five thin workflows, one per process; the logic lives in the shared templates |
Each file, line by line: Reference: the product repo and the real files. One-time setup (secrets, approval gates, the GitHub App): Reference: settings both pipelines need.
The five workflows
| Workflow | Starts on | Does | Status |
|---|---|---|---|
| CD · Detect | every 30 minutes, or by hand | Did a build or the product files change since the latest approved version? Then it starts Development. | built |
| CD · Development | a merge to main, Detect, by hand; pull requests run dry | Makes a candidate, deploys it to the first landscape (dev/app01) and approves it automatically when every deploy is healthy. | built |
| CD · Release | by hand | Gives an approved version a release number such as 1.4.0, behind the QA gate; nothing is rebuilt. | built, stops at its first step today (no qa) · deploy to qa planned |
| CD · Promote | by hand (qa or prod) | Writes an approved version into every environment of that landscape in cloud-config, then checks it runs. | built, not live |
| CD · Retention | weekly, or by hand | Lists approved versions past the policy (keep the 20 newest or 60 days, and anything in use). | built, not live report only |
Why Promote is not live
Only dev/app01 exists today. Promotion to qa and prod is not possible until greenfield IaC creates those environments: CD · Promote and CD · Release stop at their first step.
When qa and prod exist, it also needs the CD GitHub App's two secrets in the product repository, which do not exist yet, and the environment pipeline it hands over to is failing (status). It also does not yet check that a version went through the earlier landscape first, and the approval gates have no reviewers yet.
Steps: ship a version
- Merge a change to the product files, or let a service build land. Development starts straight away (product files) or within 30 minutes (Detect).
- Watch CD · Development. It composes the candidate, waits for dev/app01 to be healthy, then approves it and creates a GitHub pre-release.
- Give it a release number (optional) with CD · Release, behind the QA gate.
- Promote it to qa, then prod, with CD · Promote built, not live. Not possible today: there are no qa or prod environments yet.
Onboarding a new service: add its chart to product.yaml, its product-wide settings under its key in configurations/helm.yaml, and its secret names to the list (and the vaults). See Build a service for the service side.
See the product workflows
What can stop you
| You see | It means | Fix |
|---|---|---|
| The plan step fails | A typo or unknown name in pipeline.config.yaml; nothing was published | Fix pipeline.config.yaml (landscape and environment names are cloud-config folders) |
| Promote or Release stops in the plan step: "no landscape 'qa'" or "no landscape after the candidate stage" | The ladder has no qa or prod yet, because those environments do not exist | Nothing to fix today; wait until greenfield IaC creates qa and prod and they are added back |
| Secret not in the pool | A service asks for a name your list does not have | Add it to global.secrets in configurations/helm.yaml and to each environment's vault |
| Key outside the allowed list | An environment tried to set a product-only setting | Move it to configurations/helm.yaml |
| Digest mismatch at deploy | The chart pulled is not the one the composition recorded | Deploy a version made by compose; never re-tag a chart by hand |
| "run cloud-config's Environments workflow for this environment first" | The environment has not been set up | Ask the environment owner to apply it (Run environments) |
| Promote stops at the GitHub App step | The CD App secrets are missing | Install the App and add its two secrets (settings) |
Symptoms and commands: Deep dive: runbook.