From aca5cd2e2678eacf0416c6275919e26b575a6957 Mon Sep 17 00:00:00 2001 From: Joshua Temple Date: Fri, 12 Jun 2026 23:41:14 -0400 Subject: [PATCH] docs: clarify env names are configurable, roles are positional Signed-off-by: Joshua Temple --- README.md | 2 ++ docs/src/content/docs/configuration.md | 18 ++++++++++++++++++ docs/src/content/docs/workflows.md | 2 +- 3 files changed, 21 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 95a817e7..79e5db27 100644 --- a/README.md +++ b/README.md @@ -214,6 +214,8 @@ Promotions are triggered via `workflow_dispatch` on the generated `promote.yaml` | `dev-to-prod` | Full cascade through all environments | | `uat-to-prod` | Partial cascade from uat onward | +These modes are generated from your configured environment names (`dev`, `test`, `uat`, `prod` shown here as an example); roles are positional, with the last environment as the release stage. + The same artifacts built on the first merge are promoted through the chain; nothing is rebuilt. --- diff --git a/docs/src/content/docs/configuration.md b/docs/src/content/docs/configuration.md index 4e8d37f7..f3bc7631 100644 --- a/docs/src/content/docs/configuration.md +++ b/docs/src/content/docs/configuration.md @@ -53,6 +53,24 @@ ci: | `manifest_key` | string | No | `ci` | Top-level key inside the manifest file | | `action_folder` | string | No | `manage-release` | Folder name for the manage-release action | +:::note[Environment names are yours; roles are positional] +The `environments` list is fully configurable. cascade attaches no meaning to specific +labels: `dev`, `test`, `uat`, `staging`, and `prod` are illustrative examples used +throughout these docs, not reserved names. Roles are decided by position in the list, not +by name. The last environment is the release stage (prod), the second-to-last is the +prerelease environment, and the publish boundary is the final crossing into the last +environment. The count is structural too: zero environments is release-only, one +environment generates a single-environment Release workflow, and two or more enable the +full promote cascade. + +**Naming.** Environment, build, and deploy names become GitHub Actions job IDs and +output-variable keys, so keep them identifier-safe: use letters, digits, and underscores +(hyphens are read as subtraction in GitHub Actions expressions). The reserved +generator-owned names `environment` and `dry_run` cannot be used as `dispatch_inputs`. Any +`gha_environment` value maps to a real GitHub Environment, so GitHub's own naming rules +apply there. +::: + ### cli_version Controls which CLI version the generated workflows install via setup-cli: diff --git a/docs/src/content/docs/workflows.md b/docs/src/content/docs/workflows.md index f0909413..f249d6de 100644 --- a/docs/src/content/docs/workflows.md +++ b/docs/src/content/docs/workflows.md @@ -213,7 +213,7 @@ This prevents unnecessary deploys (e.g., don't redeploy CDK if only services cha ### Promotion Modes -The mode dropdown is generated from the configured `environments` list. +The mode dropdown is generated from the configured `environments` list. The env names and the resulting `-to-` modes come from your own configuration, not from fixed names; roles are positional (last = release stage, second-to-last = prerelease). **Default mode** advances the chain by one logical step (next env, or release/prod at the boundary).