cpflow 5.0.0 → 5.0.1

data/docs/ci-automation.md

@@ -150,29 +150,98 @@ apps:
 
 Important points:
 
-- `REVIEW_APP_PREFIX` in GitHub Actions must match the review config key prefix, for example `my-app-review`.
 - `match_if_app_name_starts_with: true` is what allows a single config entry to back `my-app-review-123`, `my-app-review-456`, and cleanup commands like `cpflow cleanup-stale-apps -a my-app-review`.
+- Review-app deploy, delete, and cleanup workflows infer the review app prefix from the single app entry with `match_if_app_name_starts_with: true`.
+- Review-app workflows infer the staging Control Plane org from that review app entry's `cpln_org`.
 - `upstream: my-app-staging` is what lets the production promotion workflow copy the exact staging artifact.
 - If your main web workload is not named `rails`, set the optional `PRIMARY_WORKLOAD` repository variable described below.
 
 ## Required GitHub Repository Settings
 
-Configure these repository secrets:
+For a normal generated review-app setup, configure one repository secret:
 
 - `CPLN_TOKEN_STAGING`: token for the staging Control Plane org
-- `CPLN_TOKEN_PRODUCTION`: token for the production Control Plane org
 
-Configure these repository variables:
+No GitHub repository variables are required for review apps when `.controlplane/controlplane.yml`
+has exactly one review app entry with `match_if_app_name_starts_with: true` and
+that entry has a `cpln_org`. The inferred values come from that config file:
+the review-app prefix is the app key with `match_if_app_name_starts_with: true`,
+and the staging org is that app's `cpln_org` value. Set these variables only
+when you need to test a fork or clone against a different Control Plane org,
+choose a different review-app prefix, expose a different public workload, or
+disambiguate generated review-app config:
+
+- `CPLN_ORG_STAGING`: override the staging/review org inferred from `cpln_org`, for example `company-staging`
+- `REVIEW_APP_PREFIX`: override the inferred review-app prefix; required only when multiple review app prefixes exist in `controlplane.yml`
+- `PRIMARY_WORKLOAD`: override the public workload used to discover the public endpoint and do production health checks; defaults to `rails`
+
+If `controlplane.yml` defines more than one app with
+`match_if_app_name_starts_with: true`, inference intentionally fails. Set
+`CPLN_ORG_STAGING` and `REVIEW_APP_PREFIX` to tell the workflow which review-app
+family to manage.
+
+For staging deploys, also configure:
 
 - `CPLN_ORG_STAGING`: staging org name, for example `company-staging`
-- `CPLN_ORG_PRODUCTION`: production org name, for example `company-production`
 - `STAGING_APP_NAME`: staging GVC name, for example `my-app-staging`
-- `PRODUCTION_APP_NAME`: production GVC name, for example `my-app-production`
-- `REVIEW_APP_PREFIX`: review-app prefix, for example `my-app-review`
 - `STAGING_APP_BRANCH`: optional branch that auto-deploys staging. If you use a custom branch, either pass it to `cpflow generate-github-actions --staging-branch BRANCH` during generation or edit `cpflow-deploy-staging.yml` so its `on.push.branches` list includes the same branch.
-- `PRIMARY_WORKLOAD`: optional workload name used to discover the public endpoint and do production health checks; defaults to `rails`
-- `DOCKER_BUILD_EXTRA_ARGS`: optional newline-delimited single `docker build` tokens passed through to `cpflow build-image`, for example `--build-arg=FOO=bar` or `--secret=id=npmrc,src=.npmrc`
-- `DOCKER_BUILD_SSH_KNOWN_HOSTS`: optional multi-line `known_hosts` content used with `DOCKER_BUILD_SSH_KEY` when the build needs SSH access to hosts other than GitHub.com
+
+For production promotion, also configure:
+
+- a GitHub Environment named `production`
+- required reviewers on that environment, limited to the people or team allowed to promote production
+- "Prevent self-review" on that environment, so the person who starts the promotion cannot approve it
+- optionally disable administrator bypass and restrict deployment branches/tags to your protected release branch
+- `CPLN_TOKEN_PRODUCTION` as an environment secret on `production`, not as a repository or organization secret
+- `CPLN_ORG_PRODUCTION` as a production environment variable, for example `company-production`
+- `PRODUCTION_APP_NAME` as a production environment variable, for example `my-app-production`
+
+Do not put `CPLN_TOKEN_PRODUCTION` in repository or organization secrets for
+sensitive production systems. The generated promotion reusable workflow declares
+`environment: production`; the generated caller passes that environment name
+through `production_environment`. GitHub waits for the `production`
+environment's protection rules before injecting `CPLN_TOKEN_PRODUCTION` into
+the upstream production job.
+
+GitHub's reusable-workflow syntax still requires the upstream workflow to
+declare `CPLN_TOKEN_PRODUCTION` as an optional `workflow_call` secret so static
+validation accepts `secrets.CPLN_TOKEN_PRODUCTION`, but the generated caller
+must not pass it. GitHub uses the secret from the reusable workflow job's
+`production` environment when that environment is configured.
+
+Generated caller workflows pass only the named secrets each reusable workflow
+needs. They do not use `secrets: inherit`; the production token is supplied by
+the protected `production` Environment after approval, not forwarded from a
+repository secret.
+
+### Production Promotion Safety
+
+`CPLN_TOKEN_PRODUCTION` can change live production workloads, images, releases,
+and rollback state. Treat it differently from review-app and staging credentials.
+The standard path is:
+
+1. Create the `production` GitHub Environment before setting the production token.
+2. Add a small required-reviewer list or team with production authority.
+3. Enable prevent self-review.
+4. Disable administrator bypass if your org policy requires two-person control.
+5. Restrict deployable branches or tags to the protected release branch.
+6. Store `CPLN_TOKEN_PRODUCTION` only as a `production` environment secret.
+7. Store `CPLN_ORG_PRODUCTION` and `PRODUCTION_APP_NAME` as `production`
+   environment variables, or as repository variables only when those names are
+   intentionally non-sensitive.
+
+GitHub only exposes environment secrets to jobs that reference the environment
+after configured protection rules pass. GitHub also does not allow a caller job
+that directly invokes a reusable workflow to set `environment`; for that reason,
+the reusable promotion workflow itself declares `environment: production`. See
+GitHub's docs for [managing environments](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments),
+[deployment protection rules](https://docs.github.com/en/actions/reference/workflows-and-actions/deployments-and-environments),
+and [reusable workflow limitations](https://docs.github.com/en/actions/reference/reusable-workflows-reference#supported-keywords-for-jobs-that-call-a-reusable-workflow).
+
+Application runtime secrets such as `SECRET_KEY_BASE`, API keys, or private
+license keys belong in Control Plane secret dictionaries referenced by
+`controlplane.yml`. They are not GitHub repository variables unless your
+Docker build itself needs them.
 
 Recommended org layout:
 
@@ -183,6 +252,17 @@ Optional repository secret for private dependency builds:
 
 - `DOCKER_BUILD_SSH_KEY`: private SSH key used when the Dockerfile needs `RUN --mount=type=ssh` to fetch private GitHub dependencies during image build
 
+Optional repository variables for private dependency builds:
+
+- `DOCKER_BUILD_EXTRA_ARGS`: optional newline-delimited single `docker build` tokens passed through to `cpflow build-image`, for example `--build-arg=FOO=bar` or `--secret=id=npmrc,src=.npmrc`
+- `DOCKER_BUILD_SSH_KNOWN_HOSTS`: optional multi-line `known_hosts` content used with `DOCKER_BUILD_SSH_KEY` when the build needs SSH access to hosts other than GitHub.com
+
+Advanced optional repository variables:
+
+- `REVIEW_APP_DEPLOYING_ICON_URL`: custom image URL for the animated icon in review-app PR comments. Ignore this for the standard setup; it is cosmetic only.
+- `CPLN_CLI_VERSION`: pin only when Control Plane CLI compatibility requires it.
+- `CPFLOW_VERSION`: pin a published RubyGems version only when intentionally overriding the default build-from-ref behavior.
+
 ## Docker Builds with Private Dependencies
 
 Some apps need extra Docker build configuration before the generated workflows are turnkey. Common examples are:
@@ -212,6 +292,9 @@ The action will start an SSH agent, add the key, write `known_hosts`, and pass `
 `cpflow-review-app-help.yml`
 
 - Posts a quick reference when a pull request opens, including on fork-based PRs.
+- This is an onboarding comment only; it does not checkout PR code or receive
+  Control Plane secrets. Remove this wrapper if a repo does not want automatic
+  review-app command help on every new PR.
 
 `cpflow-help-command.yml`
 
@@ -242,6 +325,7 @@ The action will start an SSH agent, add the key, write `known_hosts`, and pass `
 `cpflow-promote-staging-to-production.yml`
 
 - Manually promotes the staging artifact to production with a confirmation input.
+- Runs the production job in the `production` GitHub Environment, so configured reviewers approve the job before production environment secrets are available.
 - Verifies that production has the env var names staging expects.
 - Runs a health check against `PRIMARY_WORKLOAD`.
 - Attempts a rollback of every configured application workload if the new production image does not come up healthy.
@@ -252,6 +336,25 @@ The action will start an SSH agent, add the key, write `known_hosts`, and pass `
 - Runs nightly and on demand.
 - Deletes stale review apps using `cpflow cleanup-stale-apps`.
 
+Generated review app names use `<review-app-prefix>-<PR number>`, for example
+`my-app-review-123`. If an existing repository is migrating from older local
+workflow glue that created names like `<review-app-prefix>-pr-123`, delete those
+old review apps manually after merging the generated flow; the cleanup workflow
+only targets the current prefix convention.
+
+To inventory old-prefix review apps before cleanup, 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. That is intentional for configured demo repos. Forks
+or clones that copy the workflow before configuring Control Plane can remove
+`.github/workflows/cpflow-review-app-help.yml` or uncomment and adapt the
+wrapper-level `if:` guard shown in that file, for example
+`vars.REVIEW_APP_PREFIX != '' || vars.CPLN_ORG_STAGING != ''`.
+
 ## Upstream Reusable Workflows
 
 The generated workflows are intentionally small wrappers. The deployment logic,
@@ -271,18 +374,26 @@ GitHub ref:
 
 ```yaml
 uses: shakacode/control-plane-flow/.github/workflows/cpflow-deploy-review-app.yml@<ref>
-with:
-  control_plane_flow_ref: <ref>
 ```
 
-Those two pins must stay in sync:
+That single `uses:` ref is the downstream lock. GitHub exposes the reusable
+workflow's own repository, ref, and SHA to the called job, so the upstream
+workflow checks out the matching `control-plane-flow` source automatically from
+that context. Downstream wrappers should not pass `control_plane_flow_ref`; if
+you see that input in generated wrappers, regenerate with a newer `cpflow`.
+
+There are two locks, and they protect different things:
 
-- `uses: ...@<ref>` chooses the upstream reusable workflow file.
-- `control_plane_flow_ref: <ref>` tells that reusable workflow which
-  `control-plane-flow` checkout to use for shared composite actions and, when
-  `CPFLOW_VERSION` is empty, for building and installing the `cpflow` gem.
+- The GitHub ref locks the reusable workflow and composite action code that
+  GitHub runs.
+- The RubyGems version locks the `cpflow` CLI/runtime code only when you install
+  or run that gem. It does not make GitHub load reusable workflow YAML from the
+  gem.
 
-The stable release path is still gem-driven:
+That means a downstream app cannot rely on the gem alone for GitHub Actions
+behavior. The safe stable path is still gem-driven for generation, but
+developers must commit generated wrappers that reference the matching upstream
+release tag:
 
 1. Publish a `cpflow` gem.
 2. Install or bundle that released gem in the downstream project.
@@ -297,9 +408,26 @@ feature-branch refs.
 `CPFLOW_VERSION` is a runtime override. If a downstream repository sets the
 `CPFLOW_VERSION` variable, the setup action runs `gem install cpflow -v
 <version>`. If it is unset, the setup action builds `cpflow` from the checked-out
-`control-plane-flow` ref. For normal releases, leave `CPFLOW_VERSION` unset while
-pinning the wrappers to the matching `v<version>` tag, or set
-`CPFLOW_VERSION` to that same released gem version without the leading `v`.
+`control-plane-flow` source selected by the reusable workflow's own SHA. For
+normal releases, leave `CPFLOW_VERSION` unset while pinning the wrappers to the
+matching `v<version>` tag, or set `CPFLOW_VERSION` to that same released gem
+version without the leading `v`.
+When setting `CPFLOW_VERSION`, use RubyGems version syntax, for example
+`5.0.0` or `5.0.0.rc.1`; do not use `v5.0.0` or dash-separated prereleases
+because the value is passed directly to `gem install cpflow -v`.
+
+The setup action fails early when `CPFLOW_VERSION` and the reusable workflow tag
+are out of sync. `CPFLOW_VERSION=5.0.0` is accepted only when the wrapper uses a
+release tag such as `@v5.0.0` (or GitHub resolves it to `refs/tags/v5.0.0`).
+Release tags may use dot- or dash-separated prerelease suffixes, such as
+`v5.0.0.rc.1` or `v5.0.0-rc.1`; the gem version should still use dots. The
+action also checks the remote `control-plane-flow` tag and the checked-out
+action commit, so a moving branch named like `v5.0.0` cannot be used with
+`CPFLOW_VERSION=5.0.0`. That tag check uses outbound HTTPS to GitHub; restricted
+runners that cannot reach GitHub should leave `CPFLOW_VERSION` unset and build
+`cpflow` from the checked-out ref instead. When testing an unreleased upstream
+commit SHA, leave `CPFLOW_VERSION` unset so the workflow builds `cpflow` from the
+same source that supplies the reusable workflow and composite actions.
 
 ## Testing Unreleased Upstream Changes Downstream
 
@@ -319,7 +447,10 @@ releasing it. Use an immutable commit SHA from the upstream PR branch:
    local experiments that should not be committed.
 
 3. Keep `CPFLOW_VERSION` unset so the workflow builds `cpflow` from the same
-   upstream SHA that supplies the reusable workflow and composite actions.
+   upstream SHA that supplies the reusable workflow and composite actions. If
+   `CPFLOW_VERSION` is set while the wrapper is pinned to a SHA, the setup
+   action fails before deployment because the gem and action code cannot be
+   proven to match.
 4. Run:
 
    ```sh
@@ -343,8 +474,10 @@ releasing it. Use an immutable commit SHA from the upstream PR branch:
 6. Verify the deploy logs show the expected upstream commit SHA, the setup step
    prints the expected `cpflow` source/version, and the review app URL returns
    HTTP 200.
-7. After the upstream PR merges and a gem is released, regenerate or repin the
-   downstream wrappers to the release tag.
+7. After the upstream PR merges and a gem is released, regenerate the downstream
+   wrappers from that released gem and commit the release tag. Use
+   `bin/pin-cpflow-github-ref vX.Y.Z` only for a ref-only update when the
+   generated templates are already current.
 
 This tests the real reusable workflow, shared composite actions, and source-built
 `cpflow` gem from one immutable upstream commit. It avoids merging upstream blind
@@ -360,9 +493,12 @@ bin/test-cpflow-github-flow
 
 The helper runs `cpflow github-flow-readiness`, parses generated workflow YAML,
 checks composite action metadata for literal GitHub expressions in descriptions,
-checks that all generated wrappers use one upstream ref consistently, requires
-secret-inheriting reusable workflows to pass `control_plane_flow_ref`, and runs
-`actionlint -ignore "SC2129" .github/workflows/cpflow-*.yml`.
+checks that all generated wrappers use one upstream ref consistently, rejects
+broad `secrets: inherit` usage in generated cpflow wrappers, rejects obsolete
+`control_plane_flow_ref` wrapper inputs, and runs
+`actionlint` against `.github/workflows/cpflow-*.yml`. Its `actionlint` command
+keeps the existing shellcheck ignore and also ignores stale local `actionlint`
+false positives for GitHub's newer reusable-workflow `job.workflow_*` fields.
 
 ## Applying This to React on Rails Demo Apps
 
@@ -397,7 +533,7 @@ In practice, porting the flow into a demo app usually follows five phases.
 
 **Wire up GitHub secrets, variables, and private builds:**
 
-11. Make sure the repo variables and secrets line up with the configured app names.
+11. Make sure the repo variables and secrets line up with the configured app names. For production promotion, store `CPLN_TOKEN_PRODUCTION` only on a protected `production` GitHub Environment with required reviewers.
 12. If the Dockerfile pulls private dependencies over SSH, configure `DOCKER_BUILD_SSH_KEY`, add `DOCKER_BUILD_SSH_KNOWN_HOSTS` when the host is not GitHub.com, and validate that the image can build with `RUN --mount=type=ssh`.
 
 **Validate and push:**
@@ -417,7 +553,7 @@ current prompt with that repo's default app prefix already filled in.
 Short version:
 
 ```text
-Set up Control Plane GitHub Flow for this repo. Start with `cpflow github-flow-readiness` and stop on any reported blockers. The repo must be deployable from a clean clone, with published package versions and a production Dockerfile that can really build the app. Stop and report blockers for unpublished packages, inaccessible private dependencies, legacy toolchains, or missing production build paths instead of generating workflows blindly. Then run `cpflow generate` if `.controlplane/` is missing, run `cpflow generate-github-actions`, adapt the generated scaffold to the real workloads, document the required GitHub secrets and variables, validate the real build path locally, push the branch, and check the GitHub Actions results.
+Set up Control Plane GitHub Flow for this repo. Start with `cpflow github-flow-readiness` and stop on any reported blockers. The repo must be deployable from a clean clone, with published package versions and a production Dockerfile that can really build the app. Stop and report blockers for unpublished packages, inaccessible private dependencies, legacy toolchains, or missing production build paths instead of generating workflows blindly. Then run `cpflow generate` if `.controlplane/` is missing, run `cpflow generate-github-actions`, adapt the generated scaffold to the real workloads, document the required GitHub secrets and variables, validate the real build path locally, push the branch, and check the GitHub Actions results. Keep production promotion safe by documenting `CPLN_TOKEN_PRODUCTION` as a protected `production` GitHub Environment secret, not a repository or organization secret.
 ```
 
 Expand that prompt with app-specific requirements before editing files:

data/lib/command/ai_github_flow_prompt.rb

@@ -32,7 +32,7 @@ module Command
       <<~PROMPT
         Set up Control Plane GitHub Flow for this repo. Start with `cpflow github-flow-readiness` and stop on any reported blockers. The repo must be deployable from a clean clone: published package versions, complete runtime scaffold, and a production Dockerfile that can build the app. If any package version is unpublished, inaccessible from CI, or requires credentials that are not already modeled in the repo or GitHub settings, stop and report the blocker instead of generating workflow files. If the repo is a legacy sample pinned to an obsolete Ruby or Bundler toolchain, if it does not even have a production Dockerfile yet, or if it is a monorepo without an already-decided single app boundary for this flow, stop and report that as a prerequisite instead of forcing the rollout.
 
-        If `.controlplane/` is missing, run `cpflow generate`. Treat the generated app names as the repo-name default (`#{inferred_app_prefix}`) and rename them only if the project needs a different prefix. Then run `cpflow generate-github-actions` (or `cpflow generate-github-actions --staging-branch BRANCH` when staging should deploy from a branch other than `main`/`master`), keep review apps opt-in via `+review-app-deploy`, make sure any `STAGING_APP_BRANCH` repository variable is also present in the generated staging workflow's `on.push.branches` filter, and list the GitHub secrets and variables that must be configured.
+        If `.controlplane/` is missing, run `cpflow generate`. Treat the generated app names as the repo-name default (`#{inferred_app_prefix}`) and rename them only if the project needs a different prefix. Then run `cpflow generate-github-actions` (or `cpflow generate-github-actions --staging-branch BRANCH` when staging should deploy from a branch other than `main`/`master`), keep review apps opt-in via `+review-app-deploy`, make sure any `STAGING_APP_BRANCH` repository variable is also present in the generated staging workflow's `on.push.branches` filter, and list the GitHub secrets and variables that must be configured. Do not hand-edit duplicated upstream refs into the generated wrappers: the only downstream Control Plane Flow pin should be the reusable workflow `uses: ...@vX.Y.Z` value generated from the installed `cpflow` gem version, and upstream workflows load their matching shared actions automatically. Keep the standard path simple: review apps require only `CPLN_TOKEN_STAGING` when the generated review app config can be inferred. For production promotion, document a protected `production` GitHub Environment with required reviewers, prevent self-review, and `CPLN_TOKEN_PRODUCTION` stored as an environment secret, not as a repository or organization secret.
 
         Keep Node available in the final image if asset compilation or SSR depends on ExecJS, Yarn, `pnpm`, or npm after the main install layer. Make sure the generated Dockerfile uses a Ruby base image compatible with the app's declared Ruby requirement. Preserve repo-defined frontend build hooks: if `config/shakapacker.yml` defines a `precompile_hook`, or React on Rails enables `config.auto_load_bundle = true`, confirm the generated Dockerfile runs that codegen step before `rails assets:precompile`. If `config/database.yml` shows SQLite in production, confirm that the generated scaffold uses persistent `db` and `storage` volumes plus a release script that runs `rails db:prepare`; otherwise keep the default Postgres workload. If the public workload is not named `rails`, set `PRIMARY_WORKLOAD` or adjust the generated workflows. Inspect the Dockerfile and package sources for private GitHub dependencies or `RUN --mount=type=ssh`; if present, wire `DOCKER_BUILD_SSH_KEY`, optionally set `DOCKER_BUILD_SSH_KNOWN_HOSTS` for non-GitHub SSH hosts, and keep `DOCKER_BUILD_EXTRA_ARGS` to newline-delimited single tokens such as `--build-arg=FOO=bar`.
 

data/lib/cpflow/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Cpflow
-  VERSION = "5.0.0"
+  VERSION = "5.0.1"
   MIN_CPLN_VERSION = "3.1.0"
 end

data/lib/generator_templates/Dockerfile

@@ -78,6 +78,7 @@ RUN rails assets:precompile
 
 # add entrypoint
 COPY .controlplane/entrypoint.sh ./
+RUN chmod +x /app/entrypoint.sh
 ENTRYPOINT ["/app/entrypoint.sh"]
 
 CMD ["rails", "s"]

data/lib/generator_templates/entrypoint.sh

@@ -1,8 +1,48 @@
 #!/bin/sh
+set -e
 # Runs before the main command
 
-echo " -- Preparing database"
-rails db:prepare
+is_rails_server_command() {
+  if [ "${1:-}" = "env" ]; then
+    shift
+    while [ "$#" -gt 0 ]; do
+      case "${1}" in
+        *=*) shift ;;
+        --) shift; break ;;
+        -*) return 1 ;;
+        *) break ;;
+      esac
+    done
+  fi
+
+  if [ "${1:-}" = "bundle" ] && [ "${2:-}" = "exec" ]; then
+    shift 2
+  fi
+
+  # Matches generated, optionally env-prefixed, flag-free Thruster invocations.
+  # Hand-edited commands with env flags or Thruster flags before rails skip
+  # generated DB prep.
+  if [ "${1:-}" = "thrust" ] || [ "${1:-}" = "bin/thrust" ] || [ "${1:-}" = "./bin/thrust" ]; then
+    shift
+  fi
+
+  # Thruster may be wrapped with its own `bundle exec`, and the Rails command
+  # it proxies may also be wrapped with `bundle exec`.
+  if [ "${1:-}" = "bundle" ] && [ "${2:-}" = "exec" ]; then
+    shift 2
+  fi
+
+  { [ "${1:-}" = "rails" ] || [ "${1:-}" = "bin/rails" ] || [ "${1:-}" = "./bin/rails" ]; } &&
+    { [ "${2:-}" = "server" ] || [ "${2:-}" = "s" ]; }
+}
+
+# Match generated Rails server commands; workers and renderers skip DB prep.
+# Generated Dockerfiles use WORKDIR /app; adjust this path if your hand-edited
+# image runs the entrypoint from a different working directory.
+if is_rails_server_command "$@"; then
+  echo " -- Preparing database"
+  ./bin/rails db:prepare
+fi
 
 echo " -- Finishing entrypoint.sh, executing command"
 exec "$@"

data/lib/github_flow_templates/.github/cpflow-help.md

@@ -1,102 +1,98 @@
-# Review app help
+# Review App Commands
 
-You asked for review app help. These commands are generated by [cpflow](https://github.com/shakacode/control-plane-flow).
+These commands are generated by [cpflow](https://github.com/shakacode/control-plane-flow).
+For full setup, version-pinning, and troubleshooting details, see the upstream
+[CI automation guide](https://github.com/shakacode/control-plane-flow/blob/__CPFLOW_GITHUB_ACTIONS_REF__/docs/ci-automation.md).
 
-## PR commands
+## Pull Request Commands
 
-`+review-app-deploy`
-- Creates the review app if it does not exist
-- Builds the PR commit image
-- Deploys the image and comments with the review URL
-- Comment body must be exactly `+review-app-deploy`, with no surrounding text or trailing spaces. A single trailing newline from GitHub's comment editor is accepted. Comments like `please +review-app-deploy now` or `+review-app-deploy ` (with a trailing space) silently no-op.
+Comment with exactly one command, with no surrounding text or trailing spaces.
+A single trailing newline from GitHub's comment editor is accepted.
 
-`+review-app-delete`
-- Deletes the review app when the PR is done
-- This also runs automatically when the PR closes
-- Comment body must be exactly `+review-app-delete`, with no surrounding text or trailing spaces. A single trailing newline from GitHub's comment editor is accepted. Same command-match rule as `+review-app-deploy`.
+| Command | What it does |
+| --- | --- |
+| `+review-app-deploy` | Builds the PR image, creates the review app if needed, deploys, and comments with the review URL. |
+| `+review-app-delete` | Deletes the review app. This also runs automatically when the PR closes. |
+| `+review-app-help` | Posts this help message on the PR. |
 
-`+review-app-help`
-- Posts this message on the PR.
-- Comment body must be exactly `+review-app-help`, with no surrounding text or trailing spaces. A single trailing newline from GitHub's comment editor is accepted. Same command-match rule as `+review-app-deploy`.
+## Standard Setup
 
-## Workflow behavior
+For the normal generated review-app path, GitHub needs one repository secret:
 
-- Review apps are opt-in and created with `+review-app-deploy`
-- New commits redeploy existing review apps automatically
-- Pushes to the staging branch deploy staging automatically
-- Promotion to production is manual via the Actions tab
-- A nightly workflow removes stale review apps
-
-<details>
-<summary>Advanced: GitHub Actions secrets and variables</summary>
-
-### GitHub Actions secrets
-
-| Name | Required | Notes |
+| Name | Where | Notes |
 | --- | --- | --- |
-| `CPLN_TOKEN_STAGING` | yes | Service-account token scoped to the staging Control Plane org on controlplane.com. |
-| `CPLN_TOKEN_PRODUCTION` | yes (for promote) | Service-account token scoped to the production Control Plane org on controlplane.com. |
-| `DOCKER_BUILD_SSH_KEY` | optional | Private SSH key used when Docker builds fetch private deps via `RUN --mount=type=ssh`. |
+| `CPLN_TOKEN_STAGING` | Repository secret | Control Plane service-account token for the staging/review org. |
 
-### GitHub Actions variables
+No repository variables are required for the standard review-app path when
+`.controlplane/controlplane.yml` has exactly one review app entry with
+`match_if_app_name_starts_with: true`. cpflow infers the review-app prefix and
+staging org from that config.
 
-| Name | Required | Notes |
-| --- | --- | --- |
-| `CPLN_ORG_STAGING` | yes | Control Plane org on controlplane.com for staging and review apps. |
-| `CPLN_ORG_PRODUCTION` | yes (for promote) | Control Plane org on controlplane.com for production. |
-| `STAGING_APP_NAME` | yes | App name in `controlplane.yml` used as the staging deploy target. |
-| `PRODUCTION_APP_NAME` | yes (for promote) | App name in `controlplane.yml` used as the production deploy target. |
-| `REVIEW_APP_PREFIX` | yes | Prefix for per-PR review app names (e.g. `review-app`). |
-| `REVIEW_APP_DEPLOYING_ICON_URL` | optional | 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. |
-| `PRIMARY_WORKLOAD` | optional | Workload polled for health and rollback (defaults to `rails`). |
-| `DOCKER_BUILD_EXTRA_ARGS` | optional | Newline-delimited extra docker build tokens (e.g. `--build-arg=FOO=bar`). |
-| `DOCKER_BUILD_SSH_KNOWN_HOSTS` | optional | SSH known_hosts entries when SSH build hosts are not GitHub.com. |
-| `HEALTH_CHECK_ACCEPTED_STATUSES` | optional | Space-separated HTTP statuses considered healthy on promote (default `200 301 302`). |
-| `CPLN_CLI_VERSION` | optional | Pin a specific `@controlplane/cli` version; falls back to the action default when unset. |
-| `CPFLOW_VERSION` | optional | Pin a published RubyGems version such as `5.0.0`. Leave unset for normal generated workflows so the setup action builds `cpflow` from the same `control-plane-flow` GitHub ref used by the reusable workflow. |
-
-</details>
-
-<details>
-<summary>Advanced: testing unreleased control-plane-flow changes</summary>
-
-Generated workflow wrappers have two related pins:
-
-- The `uses: shakacode/control-plane-flow/...@<ref>` GitHub ref selects the reusable workflow code.
-- The `control_plane_flow_ref: <ref>` input tells the setup action which `control-plane-flow` source to check out and build when `CPFLOW_VERSION` is empty.
-
-For normal releases, point both pins at a release tag such as `v5.0.0`.
-You may leave `CPFLOW_VERSION` unset, or set it to the matching RubyGems version
-without the leading `v`, such as `5.0.0`.
-
-For temporary downstream testing of an upstream PR before a gem is released, pin
-both values to the exact 40-character commit SHA and leave `CPFLOW_VERSION`
-unset:
+Optional overrides exist for forks, clones, and unusual apps:
 
-```sh
-bin/pin-cpflow-github-ref <40-character-control-plane-flow-commit-sha>
-bin/test-cpflow-github-flow ruby /path/to/control-plane-flow/bin/cpflow
-```
+| Name | Notes |
+| --- | --- |
+| `CPLN_ORG_STAGING` | Override the staging/review Control Plane org inferred from `controlplane.yml`. |
+| `REVIEW_APP_PREFIX` | Override the review-app prefix inferred from `controlplane.yml`. |
+| `PRIMARY_WORKLOAD` | Public workload used for review URLs and health checks; defaults to `rails`. |
 
-Do not leave downstream apps pinned to a moving branch such as `main`. A branch
-can pick up beta or work-in-progress changes without a downstream PR changing.
-Use commit SHAs for short-lived PR testing, then switch to the release tag once
-the gem and tag exist.
+## Staging And Production
 
-</details>
+Staging deploys use the same `CPLN_TOKEN_STAGING` secret plus `STAGING_APP_NAME`.
 
-<details>
-<summary>Advanced: testing changes to generated workflows</summary>
+Production promotion is part of the generated flow, but keep it protected:
 
-When iterating on the generated workflow YAML on a PR branch, comment-triggered runs (`+review-app-deploy`, `+review-app-delete`, `+review-app-help`) execute the workflow code from the repository's default branch — not your PR branch. To exercise the PR-branch workflow code before merging, dispatch the workflow manually with `gh`:
+| Name | Where | Notes |
+| --- | --- | --- |
+| `CPLN_TOKEN_PRODUCTION` | `production` GitHub Environment secret | Do not store this as a repository or organization secret. |
+| `CPLN_ORG_PRODUCTION` | Prefer `production` Environment variable | Production Control Plane org. |
+| `PRODUCTION_APP_NAME` | Prefer `production` Environment variable | Production app name from `controlplane.yml`. |
+
+Configure the `production` GitHub Environment with required reviewers and
+prevent self-review. The generated promotion wrapper passes only the staging
+token from repository secrets; GitHub injects `CPLN_TOKEN_PRODUCTION` only after
+the environment approval gate passes.
+
+## Version Locking
+
+Generated wrappers pin Control Plane Flow once with the reusable workflow
+`uses:` ref, for example `@__CPFLOW_GITHUB_ACTIONS_REF__`. For stable releases,
+this ref should be a release tag. The upstream reusable workflow automatically
+loads its matching shared actions from GitHub's workflow context, so downstream
+wrappers should not pass a duplicate Control Plane Flow ref input. If your
+generated wrappers still include a `with:` block whose only purpose is to repeat
+the same ref, regenerate them with a newer `cpflow`.
+
+Leave `CPFLOW_VERSION` unset so the workflow builds cpflow from the same
+checked-out upstream source. If you set `CPFLOW_VERSION`, it must match the
+release tag, for example `CPFLOW_VERSION=5.0.1` with a wrapper pinned to
+`uses: ...@v5.0.1`.
+
+Do not leave downstream apps pinned to a moving branch such as `main`. For a
+short-lived test of an unreleased upstream PR, pin to a full 40-character commit
+SHA and leave `CPFLOW_VERSION` unset:
 
 ```sh
-gh workflow run cpflow-deploy-review-app.yml --ref <your-pr-branch> -f pr_number=<pr-number>
-gh workflow run cpflow-delete-review-app.yml --ref <your-pr-branch> -f pr_number=<pr-number>
-gh workflow run cpflow-help-command.yml      --ref <your-pr-branch> -f pr_number=<pr-number>
+bin/pin-cpflow-github-ref <40-character-control-plane-flow-commit-sha>
+bin/test-cpflow-github-flow ruby /path/to/control-plane-flow/bin/cpflow
 ```
 
-`workflow_dispatch` runs use the workflow file from the `--ref` you pass, so this is the supported way to test PR-branch workflow edits before merge. After merge, comment triggers go back to running the default-branch workflow code as usual.
-
-</details>
+## Advanced Variables
+
+Most apps do not need these:
+
+| Name | Notes |
+| --- | --- |
+| `DOCKER_BUILD_EXTRA_ARGS` | Newline-delimited extra Docker build tokens. |
+| `DOCKER_BUILD_SSH_KEY` | Private SSH key for Docker builds that fetch private dependencies. |
+| `DOCKER_BUILD_SSH_KNOWN_HOSTS` | SSH known_hosts entries when SSH build hosts are not GitHub.com. |
+| `REVIEW_APP_DEPLOYING_ICON_URL` | Cosmetic custom image URL for the animated deploying icon. Set to `none` to use the text fallback icon. |
+| `STAGING_APP_BRANCH` | Custom staging branch. The branch must also appear in `cpflow-deploy-staging.yml`'s push filter. |
+| `CPLN_CLI_VERSION` | Pin a specific `@controlplane/cli` version; normally leave unset. |
+
+The PR-open help workflow posts a short command reference whenever the generated
+wrapper exists. That is intentional for configured demo repos. Forks or clones
+that copy the workflow before configuring Control Plane can remove
+`.github/workflows/cpflow-review-app-help.yml` or uncomment and adapt the
+wrapper-level `if:` guard shown in that file, for example
+`vars.REVIEW_APP_PREFIX != '' || vars.CPLN_ORG_STAGING != ''`.

data/lib/github_flow_templates/.github/workflows/cpflow-cleanup-stale-review-apps.yml

@@ -10,13 +10,8 @@ permissions:
 
 jobs:
   cleanup:
-    # Keep the @ref in `uses:` and `control_plane_flow_ref` below in sync: the
-    # first selects the reusable workflow, the second selects its shared actions.
+    # Cleanup targets the current inferred review-app prefix. If you changed
+    # naming conventions, manually delete review apps under the old prefix.
     uses: shakacode/control-plane-flow/.github/workflows/cpflow-cleanup-stale-review-apps.yml@__CPFLOW_GITHUB_ACTIONS_REF__
-    with:
-      control_plane_flow_ref: __CPFLOW_GITHUB_ACTIONS_REF__
-    # `secrets: inherit` passes all caller repository secrets to the trusted
-    # upstream workflow. The upstream workflow only reads the named secrets it
-    # references, but GitHub does not enforce that boundary. Strict consumers can
-    # set CPFLOW_GITHUB_ACTIONS_REF to an immutable commit SHA.
-    secrets: inherit
+    secrets:
+      CPLN_TOKEN_STAGING: ${{ secrets.CPLN_TOKEN_STAGING }}

data/lib/github_flow_templates/.github/workflows/cpflow-delete-review-app.yml

@@ -31,13 +31,6 @@ jobs:
       github.event_name == 'workflow_dispatch'
     # This `if:` mirrors the upstream job guard to avoid a billable workflow_call
     # when the event does not match. Keep both conditions in sync.
-    # Keep the @ref in `uses:` and `control_plane_flow_ref` below in sync: the
-    # first selects the reusable workflow, the second selects its shared actions.
     uses: shakacode/control-plane-flow/.github/workflows/cpflow-delete-review-app.yml@__CPFLOW_GITHUB_ACTIONS_REF__
-    with:
-      control_plane_flow_ref: __CPFLOW_GITHUB_ACTIONS_REF__
-    # `secrets: inherit` passes all caller repository secrets to the trusted
-    # upstream workflow. The upstream workflow only reads the named secrets it
-    # references, but GitHub does not enforce that boundary. Strict consumers can
-    # set CPFLOW_GITHUB_ACTIONS_REF to an immutable commit SHA.
-    secrets: inherit
+    secrets:
+      CPLN_TOKEN_STAGING: ${{ secrets.CPLN_TOKEN_STAGING }}

data/lib/github_flow_templates/.github/workflows/cpflow-deploy-review-app.yml

@@ -30,13 +30,7 @@ jobs:
        github.event.issue.pull_request &&
        contains(fromJson('["+review-app-deploy","+review-app-deploy\n","+review-app-deploy\r\n"]'), github.event.comment.body) &&
        contains(fromJson('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association))
-    # Keep the @ref in `uses:` and `control_plane_flow_ref` below in sync: the
-    # first selects the reusable workflow, the second selects its shared actions.
     uses: shakacode/control-plane-flow/.github/workflows/cpflow-deploy-review-app.yml@__CPFLOW_GITHUB_ACTIONS_REF__
-    with:
-      control_plane_flow_ref: __CPFLOW_GITHUB_ACTIONS_REF__
-    # `secrets: inherit` passes all caller repository secrets to the trusted
-    # upstream workflow. The upstream workflow only reads the named secrets it
-    # references, but GitHub does not enforce that boundary. Strict consumers can
-    # set CPFLOW_GITHUB_ACTIONS_REF to an immutable commit SHA.
-    secrets: inherit
+    secrets:
+      CPLN_TOKEN_STAGING: ${{ secrets.CPLN_TOKEN_STAGING }}
+      DOCKER_BUILD_SSH_KEY: ${{ secrets.DOCKER_BUILD_SSH_KEY }}

data/lib/github_flow_templates/.github/workflows/cpflow-deploy-staging.yml

@@ -16,14 +16,9 @@ permissions:
 
 jobs:
   deploy-staging:
-    # Keep the @ref in `uses:` and `control_plane_flow_ref` below in sync: the
-    # first selects the reusable workflow, the second selects its shared actions.
     uses: shakacode/control-plane-flow/.github/workflows/cpflow-deploy-staging.yml@__CPFLOW_GITHUB_ACTIONS_REF__
     with:
-      control_plane_flow_ref: __CPFLOW_GITHUB_ACTIONS_REF__
       staging_app_branch_default: "__STAGING_BRANCH_DEFAULT__"
-    # `secrets: inherit` passes all caller repository secrets to the trusted
-    # upstream workflow. The upstream workflow only reads the named secrets it
-    # references, but GitHub does not enforce that boundary. Strict consumers can
-    # set CPFLOW_GITHUB_ACTIONS_REF to an immutable commit SHA.
-    secrets: inherit
+    secrets:
+      CPLN_TOKEN_STAGING: ${{ secrets.CPLN_TOKEN_STAGING }}
+      DOCKER_BUILD_SSH_KEY: ${{ secrets.DOCKER_BUILD_SSH_KEY }}