Clarify cpflow production secret docs

Author: justin808

.controlplane/controlplane.yml

@@ -52,7 +52,7 @@ apps:
 
   react-webpack-rails-tutorial-staging:
     <<: *common
-  # QA Apps are like Heroku review apps, but the use `prefix` so you can run a commmand like
+  # QA Apps are like Heroku review apps, but they use `prefix` so you can run a command like
   # this to create a QA app for the tutorial app.
   # `cpflow setup gvc postgres redis rails -a qa-react-webpack-rails-tutorial-1234`
   qa-react-webpack-rails-tutorial:

.controlplane/readme.md

@@ -71,9 +71,11 @@ For production promotion, configure a protected GitHub Environment named
 Protect the `production` environment with required reviewers, enable prevent
 self-review, and consider disabling administrator bypass. Only release managers
 or similarly trusted maintainers should be able to approve the promotion job.
-The promotion workflow uses that environment before it can access
-`CPLN_TOKEN_PRODUCTION`, so the production token is not exposed to ordinary
-review-app or staging runs.
+The generated caller passes `production_environment: production`; the upstream
+reusable workflow runs its production job in that environment, so GitHub injects
+`CPLN_TOKEN_PRODUCTION` only after the environment approval gate passes. The
+production token is not exposed to ordinary review-app or staging runs.
+
 Generated caller workflows pass only the named secrets each upstream workflow
 needs. They do not use `secrets: inherit`; `CPLN_TOKEN_PRODUCTION` is supplied
 only by the protected `production` Environment after approval.
@@ -502,7 +504,11 @@ The GitHub settings and Control Plane resources must match the app names in
 `REVIEW_APP_PREFIX` unset and let the workflow infer
 `qa-react-webpack-rails-tutorial`; generated review apps are named
 `qa-react-webpack-rails-tutorial-<PR number>`.
-If you have older review apps from the previous `qa-react-webpack-rails-tutorial-pr-<PR number>` naming, delete them manually after this flow lands; cleanup targets the current prefix convention.
+If you have older review apps from the previous `qa-react-webpack-rails-tutorial-pr-<PR number>` naming, delete them manually after this flow lands; cleanup targets the current prefix convention. To inventory old apps, run:
+
+```sh
+cpln gvc query --org shakacode-open-source-examples-staging -o yaml --prop name~qa-react-webpack-rails-tutorial-pr-
+```
 
 This allows teams to:
 - Preview changes in a production-like environment

.controlplane/shakacode-team.md

@@ -54,7 +54,11 @@ Production promotion uses a protected GitHub Environment named `production`:
 
 Protect the `production` environment with required reviewers, enable prevent
 self-review, and consider disabling administrator bypass. Do not store
-`CPLN_TOKEN_PRODUCTION` as a repository or organization secret.
+`CPLN_TOKEN_PRODUCTION` as a repository or organization secret. The caller
+passes `production_environment: production`; the upstream reusable workflow runs
+its production job in that environment, and GitHub injects the production token
+only after approval.
+
 Generated caller workflows pass only the named secrets each upstream workflow
 needs. They do not use `secrets: inherit`; `CPLN_TOKEN_PRODUCTION` is supplied
 only by the protected `production` Environment after approval.

.github/cpflow-help.md

@@ -35,13 +35,15 @@ You asked for review app help. These commands are generated by [cpflow](https://
 | Name | Required | Notes |
 | --- | --- | --- |
 | `CPLN_TOKEN_STAGING` | yes | Service-account token scoped to the staging Control Plane org on controlplane.com. |
-| `CPLN_TOKEN_PRODUCTION` | yes for promote, as an environment secret | Store this as a secret on the protected `production` GitHub Environment, not as a repository or organization secret. |
+| `CPLN_TOKEN_PRODUCTION` | yes for promote, as a production environment secret | Store this as a secret on the protected `production` GitHub Environment, not as a repository or organization secret. |
 | `DOCKER_BUILD_SSH_KEY` | optional | Private SSH key used when Docker builds fetch private deps via `RUN --mount=type=ssh`. |
 
 For normal generated review apps, `CPLN_TOKEN_STAGING` is the only required
 GitHub setting. The review app prefix and staging org are inferred from
 `.controlplane/controlplane.yml` when it defines exactly one app with
 `match_if_app_name_starts_with: true`.
+If more than one app has that flag, set `CPLN_ORG_STAGING` and
+`REVIEW_APP_PREFIX` explicitly to disambiguate.
 
 Those inferred values come from `.controlplane/controlplane.yml`: `cpln_org`
 selects the Control Plane org and the app key with
@@ -52,8 +54,10 @@ expose a different public workload. Leave them unset for the standard setup.
 
 For production promotion, create a GitHub Environment named `production`, add
 required reviewers, enable prevent self-review, and store
-`CPLN_TOKEN_PRODUCTION` as an environment secret there. The generated promotion
-workflow uses that environment before it can access production secrets.
+`CPLN_TOKEN_PRODUCTION` as an environment secret there. The generated caller
+passes `production_environment: production`; the upstream reusable workflow
+runs its production job in that environment, so GitHub injects
+`CPLN_TOKEN_PRODUCTION` only after the environment approval gate passes.
 Generated caller workflows pass only the named secrets each upstream workflow
 needs. They do not use `secrets: inherit`; the production token is supplied by
 the protected `production` Environment after approval.
@@ -63,9 +67,9 @@ the protected `production` Environment after approval.
 | Name | Required | Notes |
 | --- | --- | --- |
 | `CPLN_ORG_STAGING` | optional for review apps; yes for staging | Override the staging/review Control Plane org inferred from `controlplane.yml`. |
-| `CPLN_ORG_PRODUCTION` | yes for promote, preferably as environment variable | Control Plane org on controlplane.com for production. Prefer a `production` environment variable. |
+| `CPLN_ORG_PRODUCTION` | yes for promote, preferably as production environment variable | Control Plane org on controlplane.com for production. Prefer a `production` environment variable. |
 | `STAGING_APP_NAME` | yes | App name in `controlplane.yml` used as the staging deploy target. |
-| `PRODUCTION_APP_NAME` | yes for promote, preferably as environment variable | App name in `controlplane.yml` used as the production deploy target. Prefer a `production` environment variable. |
+| `PRODUCTION_APP_NAME` | yes for promote, preferably as production environment variable | App name in `controlplane.yml` used as the production deploy target. Prefer a `production` environment variable. |
 | `REVIEW_APP_PREFIX` | optional | Override the review-app app key inferred from the `match_if_app_name_starts_with: true` entry in `controlplane.yml`. |
 | `REVIEW_APP_DEPLOYING_ICON_URL` | optional, advanced | Cosmetic custom image URL for the animated deploying icon in review-app PR comments. Set to `none` to use the text fallback icon. |
 | `STAGING_APP_BRANCH` | optional | Custom staging branch. Custom branches must also appear in `cpflow-deploy-staging.yml`'s push filter. |
@@ -81,7 +85,15 @@ the protected `production` Environment after approval.
 Generated review app names use `<review-app-prefix>-<PR number>`, for example
 `my-app-review-123`. If you are migrating from older local workflow glue that
 created names like `<review-app-prefix>-pr-123`, delete those old review apps
-manually after merging this flow.
+manually after merging this flow. To inventory old apps, run:
+
+```sh
+cpln gvc query --org <staging-org> -o yaml --prop name~<review-app-prefix>-pr-
+```
+
+The PR-open help workflow posts the short command reference whenever the
+generated wrapper exists. Remove `.github/workflows/cpflow-review-app-help.yml`
+or add a wrapper-level `if:` guard if a repo should not advertise review apps.
 
 <details>
 <summary>Advanced: testing unreleased control-plane-flow changes</summary>

.github/workflows/cpflow-promote-staging-to-production.yml

@@ -22,8 +22,9 @@ jobs:
     with:
       control_plane_flow_ref: b0c5759050c5c79a05826cd7a5d3ae711cd22a40
       # Keep CPLN_TOKEN_PRODUCTION as a secret on this protected GitHub
-      # Environment. Required reviewers approve the job before GitHub exposes
-      # environment secrets to the upstream reusable workflow.
+      # Environment. The caller passes the environment name, the upstream
+      # reusable workflow runs its production job in that environment, and
+      # GitHub exposes environment secrets only after required reviewers approve.
       production_environment: production
     # Only pass the staging token explicitly. CPLN_TOKEN_PRODUCTION must live on
     # the protected production Environment, where GitHub exposes it only after

bin/test-cpflow-github-flow

@@ -43,6 +43,7 @@ bin/conductor-exec ruby <<'RUBY'
 require "yaml"
 
 CONTROL_PLANE_FLOW_WORKFLOW = %r{\Ashakacode/control-plane-flow/\.github/workflows/[^@\s]+@([^\s]+)\z}
+PROMOTE_WORKFLOW = "/.github/workflows/cpflow-promote-staging-to-production.yml@"
 
 refs = Hash.new { |hash, key| hash[key] = [] }
 
@@ -68,6 +69,17 @@ Dir[".github/workflows/cpflow-*.yml"].sort.each do |path|
     uses_ref = uses_match[1]
     refs[uses_ref] << "#{path}:#{job_name}"
 
+    if job["uses"].to_s.include?(PROMOTE_WORKFLOW)
+      if with["production_environment"].to_s.strip.empty?
+        abort "#{path}:#{job_name} must set production_environment so GitHub can expose production environment secrets after approval"
+      end
+
+      secrets = job["secrets"].is_a?(Hash) ? job["secrets"] : {}
+      if secrets.key?("CPLN_TOKEN_PRODUCTION")
+        abort "#{path}:#{job_name} must not pass CPLN_TOKEN_PRODUCTION as a caller secret; store it on the protected production environment"
+      end
+    end
+
     if input_ref
       refs[input_ref] << "#{path}:#{job_name}"
       abort "#{path}:#{job_name} mismatched cpflow refs: #{uses_ref}, #{input_ref}" if uses_ref != input_ref