cpflow 5.0.0.rc.1 → 5.0.0

data/.github/workflows/trigger-docs-site.yml

@@ -0,0 +1,90 @@
+name: Trigger docs site rebuild
+run-name: Docs dispatch (${{ github.event_name == 'workflow_dispatch' && inputs.reason || github.event_name }}) @ ${{ github.sha }}
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - README.md
+      - CHANGELOG.md
+      - CONTRIBUTING.md
+      - docs/**
+  workflow_dispatch:
+    inputs:
+      reason:
+        description: "Reason for forcing a docs rebuild"
+        required: false
+        default: "manual"
+    # Non-main manual dispatches are skipped by the job guard below.
+    # Only use this for forcing a rebuild from main.
+
+concurrency:
+  # Include the ref so accidental non-main manual runs cannot cancel a main dispatch
+  # before the job guard skips them.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  # Only the most recent docs dispatch for the same ref matters.
+  # See CONTRIBUTING.md for manual cancellation/retry guidance.
+  cancel-in-progress: true
+
+jobs:
+  notify-docs-site:
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'  # skip non-main workflow_dispatch runs
+    permissions: {}
+    timeout-minutes: 5
+    steps:
+      - name: Generate GitHub App token
+        uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1.12.0
+        id: app-token
+        with:
+          app-id: ${{ secrets.DOCS_DISPATCH_APP_ID }}
+          private-key: ${{ secrets.DOCS_DISPATCH_APP_KEY }}
+          owner: shakacode
+          repositories: controlplaneflow-com
+
+      - name: Dispatch docs-updated event
+        id: dispatch
+        uses: peter-evans/repository-dispatch@ff45666b9427631e3450c54a1bcbee4d9ff4d7c0 # v3.0.0
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          repository: shakacode/controlplaneflow-com
+          event-type: docs-updated
+          client-payload: |
+            {
+              "sha": ${{ toJSON(github.sha) }},
+              "ref": ${{ toJSON(github.ref) }},
+              "reason": ${{ toJSON(inputs.reason || github.event_name) }}
+            }
+
+      - name: Summarize docs dispatch
+        if: always()
+        env:
+          DISPATCH_OUTCOME: ${{ steps.dispatch.outcome }}
+          DISPATCH_REASON: ${{ inputs.reason || github.event_name }}
+          DISPATCH_REF: ${{ github.ref }}
+          DISPATCH_SHA: ${{ github.sha }}
+        run: |
+          safe_dispatch_reason=${DISPATCH_REASON//[^a-zA-Z0-9 _.\/-]/}
+          # Ref and SHA come from GitHub; the job guard restricts ref to main,
+          # and the SHA is the triggering commit id.
+          {
+            echo "### Docs site dispatch"
+            echo "- Target repository: \`shakacode/controlplaneflow-com\`"
+            echo "- Event type: \`docs-updated\`"
+            echo "- Source ref: \`${DISPATCH_REF}\`"
+            echo "- Source SHA: \`${DISPATCH_SHA}\`"
+            echo "- Reason: \`${safe_dispatch_reason}\`"
+            echo "- Dispatch outcome: \`${DISPATCH_OUTCOME}\`"
+            echo
+            if [ "$DISPATCH_OUTCOME" = "success" ]; then
+              echo "Check the target repository workflow runs for downstream rebuild status."
+            elif [ "$DISPATCH_OUTCOME" = "skipped" ]; then
+              echo "Dispatch was skipped because a prior step did not complete successfully."
+            elif [ "$DISPATCH_OUTCOME" = "failure" ]; then
+              echo "Dispatch step failed. Inspect this job's logs and verify the App token has Contents: Write on the target repo."
+            elif [ "$DISPATCH_OUTCOME" = "cancelled" ]; then
+              echo "Dispatch step was interrupted mid-execution. Check the target repo's workflow runs because the event may or may not have been received."
+            else
+              echo "Dispatch outcome: ${DISPATCH_OUTCOME}. Inspect this job's logs before checking the target repository workflow runs."
+            fi
+          } >> "$GITHUB_STEP_SUMMARY"

data/.rubocop.yml

@@ -4,7 +4,7 @@ plugins:
 
 AllCops:
   TargetRubyVersion: 3.0
-  NewCops: disable
+  NewCops: enable
 
 Metrics/AbcSize:
   Enabled: false
@@ -24,3 +24,16 @@ RSpec/MultipleExpectations:
 RSpec/NestedGroups:
   Enabled: true
   Max: 5
+
+# Test support and Rails dummy app scripts intentionally write to stdout for
+# verbose test output and setup messages — not actual specs.
+RSpec/Output:
+  Exclude:
+    - spec/support/**/*
+    - spec/dummy/**/*
+
+# Empty blocks in this spec are intentional — the DSL must render empty
+# Terraform blocks correctly.
+Lint/EmptyBlock:
+  Exclude:
+    - spec/core/terraform_config/dsl_spec.rb

data/CHANGELOG.md

@@ -12,6 +12,46 @@ In addition to the standard keepachangelog.com categories, this project uses a l
 
 ## [Unreleased]
 
+## [5.0.0] - 2026-05-23
+
+### Breaking Changes
+
+- Promotes the 5.x release-candidate line to stable. The breaking changes introduced during the 5.0.0 prerelease cycle are documented in `5.0.0.rc.1`, including the Ruby 3.0 minimum, `cpflow exists` not-found exit code change, and generated Dockerfile production-group behavior.
+
+### Changed
+
+- Promoted the 5.0.0 release-candidate line to stable. This release includes the generated GitHub Actions flow, upstream reusable workflow model, Node 24 action updates, richer review-app command feedback, generated downstream pin/validation helpers, and cleanup/run/deploy fixes documented in `5.0.0.rc.3`.
+
+### Fixed
+
+- **Fixed packaged `cpflow` gems failing to boot without the development-only `debug` gem installed.** [PR 314](https://github.com/shakacode/control-plane-flow/pull/314) by [Justin Gordon](https://github.com/justin808). The hidden `cpflow test` command no longer requires `debug` while loading the CLI, and coverage now exercises loading `cpflow` with `require "debug"` blocked.
+
+## [5.0.0.rc.3] - 2026-05-23
+
+### Added
+
+- **Added `--mode=stop` to `cleanup-stale-apps` for reversible idle-app handling.** [PR 302](https://github.com/shakacode/control-plane-flow/pull/302) by [Justin Gordon](https://github.com/justin808). Suspends all workloads via `cpflow ps:stop` instead of deleting; restore with `cpflow ps:start`. Default `--mode=delete` preserves existing behavior. Fixes [issue 295](https://github.com/shakacode/control-plane-flow/issues/295).
+- **Added generated local helpers for downstream GitHub Actions ref pinning and validation.** [PR 308](https://github.com/shakacode/control-plane-flow/pull/308) by [Justin Gordon](https://github.com/justin808). `cpflow generate-github-actions` now writes `bin/pin-cpflow-github-ref` and `bin/test-cpflow-github-flow` so downstream repos can safely pin wrappers to release tags or full upstream commit SHAs, validate wrapper ref consistency, and test unreleased upstream workflow changes without using moving branch refs.
+- **Added richer generated review-app command feedback.** [PR 304](https://github.com/shakacode/control-plane-flow/pull/304) by [Justin Gordon](https://github.com/justin808). Generated review-app deploy/delete/help workflows now react promptly to commands, publish structured progress/success/failure comments, and support `REVIEW_APP_DEPLOYING_ICON_URL` or `none` for the deploying indicator.
+
+### Changed
+
+- **Changed generated GitHub Actions output to thin downstream wrappers backed by upstream reusable workflows and shared composite actions.** [PR 305](https://github.com/shakacode/control-plane-flow/pull/305) by [Justin Gordon](https://github.com/justin808). Deployment, deletion, staging, promotion, cleanup, comment formatting, Control Plane setup, and Docker image build logic now live upstream in this repository; `CPFLOW_GITHUB_ACTIONS_REF` controls which upstream ref generated wrappers use.
+- **Documented the downstream testing and release model for reusable GitHub Actions.** [PR 308](https://github.com/shakacode/control-plane-flow/pull/308) by [Justin Gordon](https://github.com/justin808). The CI automation docs now spell out what is tied to the upstream GitHub ref, what is tied to the RubyGems version, how `CPFLOW_VERSION` changes runtime installation, and how to test an unmerged upstream PR from a downstream app.
+- **Updated generated GitHub Actions workflow templates to Node 24-compatible action versions.** [PR 303](https://github.com/shakacode/control-plane-flow/pull/303) by [Justin Gordon](https://github.com/justin808). Uses `actions/checkout@v6` and `actions/github-script@v8`.
+- **Shortened the generated review-app command quick reference.** [PR 290](https://github.com/shakacode/control-plane-flow/pull/290) by [Justin Gordon](https://github.com/justin808). Keeps the three `+review-app-*` commands and the setup-help pointer while reducing repeated wording in the PR-open comment.
+
+### Fixed
+
+- **Relaxed the `thor` runtime dependency from `~> 1.4` to `~> 1.3`.** [PR 291](https://github.com/shakacode/control-plane-flow/pull/291) by [Justin Gordon](https://github.com/justin808). Allows cpflow to be bundled into Rails 8 apps that pull in `solid_queue` 1.1.0, which pins `thor ~> 1.3.1`. Fixes [issue 264](https://github.com/shakacode/control-plane-flow/issues/264).
+- **Fixed `deploy-image` showing container names instead of workload names in deploy progress and endpoint summaries.** [PR 294](https://github.com/shakacode/control-plane-flow/pull/294) by [Justin Gordon](https://github.com/justin808). Also guards against duplicate work per workload by deploying only the first container whose image matches the app-image pattern. Fixes [issue 255](https://github.com/shakacode/control-plane-flow/issues/255).
+- **Fixed `cpflow run` interactive sessions printing a confusing non-zero exit error on command failure or session close.** [PR 301](https://github.com/shakacode/control-plane-flow/pull/301) by [Justin Gordon](https://github.com/justin808). cpflow now prints an actionable `cpflow ps:stop` hint instead; exit code 64 is returned for non-zero exits and 130 for signal termination so scripted callers can still detect failure. Fixes [issue 199](https://github.com/shakacode/control-plane-flow/issues/199).
+- **Fixed `cpflow generate` and generated GitHub Actions edge cases.** [PR 288](https://github.com/shakacode/control-plane-flow/pull/288) by [Justin Gordon](https://github.com/justin808). Detects nested production SQLite configs, normalizes folded Shakapacker precompile hooks, gates delete-review-app steps on config readiness, routes `github-script` values through environment variables, and honors HTTPS proxy settings during registry readiness checks.
+- **Fixed generated `cpflow-setup-environment` Ruby setup when downstream apps do not provide a Ruby version file.** [PR 306](https://github.com/shakacode/control-plane-flow/pull/306) by [Justin Gordon](https://github.com/justin808). The shared action now auto-detects `.ruby-version`, `.tool-versions`, `mise.toml`, `.mise.toml`, or a `Gemfile` Ruby directive and falls back to Ruby 3.2 when none is present.
+- **Fixed `cpflow-detect-release-phase` failing with a raw Ruby traceback when `.controlplane/controlplane.yml` is missing.** [PR 299](https://github.com/shakacode/control-plane-flow/pull/299) by [Justin Gordon](https://github.com/justin808). The generated composite action now exits with a clear missing-config message.
+- **Fixed generated review-app delete workflows running `cpflow delete` from the wrong checkout.** [PR 307](https://github.com/shakacode/control-plane-flow/pull/307) by [Justin Gordon](https://github.com/justin808). The generated workflow checks out the downstream repository into `app/` and runs setup/delete from that working directory so `.controlplane/controlplane.yml` is available.
+- **Fixed `cleanup-stale-apps` skipping image-less GVCs indefinitely.** [PR 310](https://github.com/shakacode/control-plane-flow/pull/310) by [Justin Gordon](https://github.com/justin808). Image-less GVCs now fall back to the GVC `created` timestamp for stale-app detection, while GVCs missing `created` are skipped instead of raising.
+
 ## [5.0.0.rc.1] - 2026-05-11
 
 ### Breaking Changes
@@ -313,7 +353,9 @@ Deprecated `cpl` gem. New gem is `cpflow`.
 
 First release.
 
-[Unreleased]: https://github.com/shakacode/control-plane-flow/compare/v5.0.0.rc.1...HEAD
+[Unreleased]: https://github.com/shakacode/control-plane-flow/compare/v5.0.0...HEAD
+[5.0.0]: https://github.com/shakacode/control-plane-flow/compare/v5.0.0.rc.3...v5.0.0
+[5.0.0.rc.3]: https://github.com/shakacode/control-plane-flow/compare/v5.0.0.rc.1...v5.0.0.rc.3
 [5.0.0.rc.1]: https://github.com/shakacode/control-plane-flow/compare/v4.2.0...v5.0.0.rc.1
 [4.2.0]: https://github.com/shakacode/control-plane-flow/compare/v4.1.1...v4.2.0
 [4.1.1]: https://github.com/shakacode/control-plane-flow/compare/v4.1.0...v4.1.1

data/CONTRIBUTING.md

@@ -27,6 +27,33 @@ gem install overcommit
 overcommit --install
 ```
 
+## Docs Site Dispatch
+
+The `trigger-docs-site.yml` workflow notifies `shakacode/controlplaneflow-com` when docs-related files change on `main`.
+It requires these repository secrets:
+
+- `DOCS_DISPATCH_APP_ID`: the GitHub App ID used to create the dispatch token
+- `DOCS_DISPATCH_APP_KEY`: the GitHub App private key PEM for that app
+
+GitHub's REST docs for the repository dispatch endpoint list **Contents: Write** as the required repository permission for
+GitHub App installation tokens. This is separate from **Actions: Write**, which is used by other workflow APIs. Install
+the app on `shakacode/controlplaneflow-com` with **Contents: Write**. If the dispatch succeeds but the docs site does not
+rebuild, check the target repo's workflow runs for the matching `docs-updated` event.
+
+Manual runs should be started from `main`; non-main manual dispatches are skipped before token generation or docs-site
+notification. The GitHub Actions run can therefore finish without dispatching anything when a non-main ref is selected.
+The workflow deduplicates runs by workflow and ref with `cancel-in-progress: true`, so consecutive `main` runs can
+supersede one another; that is expected because the newest docs state wins.
+
+If the job fails and the summary shows `Dispatch outcome: skipped`, the dispatch step did not run because an earlier step
+failed. Check the `Generate GitHub App token` step first, including the App ID, private key secret, installation, and target
+repository permissions.
+
+If a manual dispatch is canceled and no later successful `main` run replaces it, re-trigger the manual run from `main`. If
+the run is canceled while the dispatch step is already executing, the target repo may already have received the event; check
+the target repo workflow runs before re-triggering. Duplicate dispatches are harmless, but they can rebuild the docs site
+twice.
+
 ## Testing
 
 We use real apps for the tests. You'll need to have full access to a Control Plane org, and then set it as the env var `CPLN_ORG` when running the tests (or in the `.env` file):

data/Gemfile.lock

@@ -1,11 +1,11 @@
 PATH
   remote: .
   specs:
-    cpflow (5.0.0.rc.1)
+    cpflow (5.0.0)
       dotenv (~> 3.1)
       jwt (~> 3.1)
       psych (~> 5.2)
-      thor (~> 1.4)
+      thor (~> 1.3)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -65,6 +65,7 @@ Additionally, the documentation includes numerous examples and practical tips fo
 14. [Migrating Postgres Database from Heroku Infrastructure](https://www.shakacode.com/control-plane-flow/docs/postgres/)
 15. [Migrating Redis Database from Heroku Infrastructure](https://www.shakacode.com/control-plane-flow/docs/redis/)
 16. [Tips](https://www.shakacode.com/control-plane-flow/docs/tips/)
+17. [Thruster HTTP/2 Proxy on Control Plane](https://www.shakacode.com/control-plane-flow/docs/thruster/)
 
 ## Key Features
 
@@ -278,8 +279,8 @@ aliases:
     # If not specified, defaults to 21600 (6 hours).
     runner_job_timeout: 1000
 
-    # Apps with a deployed image created before this amount of days will be listed for deletion
-    # when running the command `cpflow cleanup-stale-apps`.
+    # Apps with a deployed image, or an image-less GVC, created before this amount of days
+    # will be listed for deletion when running the command `cpflow cleanup-stale-apps`.
     stale_app_image_deployed_days: 5
 
     # Images that exceed this quantity will be listed for deletion
@@ -357,9 +358,12 @@ cpflow generate
 
 # Create reusable GitHub Actions for review apps, staging, and production promotion
 cpflow generate-github-actions
+
+# Validate the generated GitHub Actions wrapper refs and metadata
+bin/test-cpflow-github-flow
 ```
 
-`cpflow github-flow-readiness` exits non-zero when it finds blockers such as unpublished exact-pinned packages or a missing production Dockerfile, so use it as the gate before generation. Then review the generated `.controlplane/controlplane.yml` entries, adjust any app-specific workloads, and configure the GitHub repository variables and secrets described in [CI automation](./docs/ci-automation.md), including the optional Docker build settings for private GitHub dependencies and custom SSH known hosts. `cpflow generate` already switches to persistent `db` and `storage` volumes when `config/database.yml` shows SQLite in production and preserves detected frontend precompile hooks, but you should still confirm that the generated Dockerfile picked a Ruby base image compatible with the app's declared Ruby requirement and that the emitted workload set matches the real app. If you want an AI agent to do this end to end, start with the [AI rollout prompt](./docs/ai-github-flow-prompt.md) or run `cpflow ai-github-flow-prompt` in the target repo rather than giving a vague "set up CI" request.
+`cpflow github-flow-readiness` exits non-zero when it finds blockers such as unpublished exact-pinned packages or a missing production Dockerfile, so use it as the gate before generation. Then review the generated `.controlplane/controlplane.yml` entries, adjust any app-specific workloads, and configure the GitHub repository variables and secrets described in [CI automation](./docs/ci-automation.md), including the optional Docker build settings for private GitHub dependencies and custom SSH known hosts. `cpflow generate-github-actions` also writes `bin/test-cpflow-github-flow` for local validation and `bin/pin-cpflow-github-ref` for temporarily pinning downstream wrappers to an upstream commit SHA during pre-release testing. `cpflow generate` already switches to persistent `db` and `storage` volumes when `config/database.yml` shows SQLite in production and preserves detected frontend precompile hooks, but you should still confirm that the generated Dockerfile picked a Ruby base image compatible with the app's declared Ruby requirement and that the emitted workload set matches the real app. If you want an AI agent to do this end to end, start with the [AI rollout prompt](./docs/ai-github-flow-prompt.md) or run `cpflow ai-github-flow-prompt` in the target repo rather than giving a vague "set up CI" request.
 
 For a live example, see the [react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/readme.md) repository.
 

data/cpflow.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "dotenv",   "~> 3.1"
   spec.add_dependency "jwt",      "~> 3.1"
   spec.add_dependency "psych",    "~> 5.2"
-  spec.add_dependency "thor",     "~> 1.4"
+  spec.add_dependency "thor",     "~> 1.3"
 
   spec.files = `git ls-files -z`.split("\x0").reject do |file|
     file.match(%r{^(coverage|pkg|spec|tmp)/})

data/docs/ai-github-flow-prompt.md

@@ -44,7 +44,7 @@ Stop and report the blocker instead of generating `cpflow-*` workflow files when
 The rollout is done when all of the following are true:
 
 - `.controlplane/` exists and matches the actual app shape
-- `.github/actions/cpflow-*` and `.github/workflows/cpflow-*` are in place
+- `.github/cpflow-help.md` and `.github/workflows/cpflow-*` wrappers are in place
 - review apps are opt-in, staging auto-deploys from one branch, and production promotion is manual
 - required GitHub secrets and variables are documented for the repo
 - the production image build path is validated for the real app

data/docs/assets/cpflow-deploying.svg

@@ -0,0 +1,46 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-labelledby="title desc">
+  <title id="title">Deploying</title>
+  <desc id="desc">Animated deployment progress icon for Control Plane Flow review apps.</desc>
+  <defs>
+    <linearGradient id="ring" x1="8" x2="56" y1="8" y2="56" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#3ddc97"/>
+      <stop offset="0.5" stop-color="#4f8cff"/>
+      <stop offset="1" stop-color="#ffb84d"/>
+    </linearGradient>
+    <filter id="soft-shadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="2" stdDeviation="2" flood-color="#233044" flood-opacity="0.22"/>
+    </filter>
+  </defs>
+
+  <circle cx="32" cy="32" r="28" fill="#f7fbff"/>
+  <circle cx="32" cy="32" r="23" fill="none" stroke="#d7e4f2" stroke-width="4"/>
+
+  <g>
+    <animateTransform
+      attributeName="transform"
+      type="rotate"
+      from="0 32 32"
+      to="360 32 32"
+      dur="1.1s"
+      repeatCount="indefinite"/>
+    <circle
+      cx="32"
+      cy="32"
+      r="23"
+      fill="none"
+      stroke="url(#ring)"
+      stroke-linecap="round"
+      stroke-width="4"
+      stroke-dasharray="40 110"/>
+  </g>
+
+  <g filter="url(#soft-shadow)">
+    <path d="M35.7 13.5c-7.8 3.1-13 10-15.8 20.8l9.8 9.8c10.8-2.8 17.7-8 20.8-15.8 1.7-4.4 1.4-9.7-.9-14-4.3-2.2-9.6-2.6-13.9-.8Z" fill="#ffffff"/>
+    <path d="M35.7 13.5c-7.8 3.1-13 10-15.8 20.8l9.8 9.8c10.8-2.8 17.7-8 20.8-15.8 1.7-4.4 1.4-9.7-.9-14-4.3-2.2-9.6-2.6-13.9-.8Z" fill="#4f8cff" opacity="0.18"/>
+    <path d="M35.7 13.5c-7.8 3.1-13 10-15.8 20.8l9.8 9.8c10.8-2.8 17.7-8 20.8-15.8 1.7-4.4 1.4-9.7-.9-14-4.3-2.2-9.6-2.6-13.9-.8Z" fill="none" stroke="#233044" stroke-width="2" stroke-linejoin="round"/>
+    <circle cx="39.7" cy="24.3" r="4.5" fill="#3ddc97" stroke="#233044" stroke-width="2"/>
+    <path d="M20.2 34.1 13.5 36l7.1 7.1 2-6.6-2.4-2.4Z" fill="#ffb84d" stroke="#233044" stroke-width="2" stroke-linejoin="round"/>
+    <path d="M29.9 43.8 28 50.5l-7.1-7.1 6.6-2 2.4 2.4Z" fill="#ff6b6b" stroke="#233044" stroke-width="2" stroke-linejoin="round"/>
+    <path d="M18.8 45.2c-2.4.7-4.1 2.4-5.2 5.2 2.8-1.1 4.5-2.8 5.2-5.2Z" fill="#ffb84d"/>
+  </g>
+</svg>

data/docs/ci-automation.md

@@ -16,7 +16,7 @@ End-to-end rollout in one view:
 
 1. `cpflow github-flow-readiness` — exits non-zero if the repo is not ready to deploy.
 2. `cpflow generate` — creates `.controlplane/` if missing.
-3. `cpflow generate-github-actions` — adds the `cpflow-*` composite actions and workflows.
+3. `cpflow generate-github-actions` — adds thin `cpflow-*` workflow wrappers that call upstream reusable workflows.
 4. Configure the GitHub [repository secrets and variables](#required-github-repository-settings) the workflows expect.
 5. Push the branch, then comment `+review-app-deploy` on a PR to spin up a review environment.
 
@@ -52,10 +52,7 @@ not appear to exist in the public registries.
 
 The second command writes namespaced files so they can coexist with an app's existing CI:
 
-- `.github/actions/cpflow-build-docker-image/action.yml`
-- `.github/actions/cpflow-delete-control-plane-app/action.yml`
-- `.github/actions/cpflow-delete-control-plane-app/delete-app.sh`
-- `.github/actions/cpflow-setup-environment/action.yml`
+- `.github/cpflow-help.md`
 - `.github/workflows/cpflow-review-app-help.yml`
 - `.github/workflows/cpflow-help-command.yml`
 - `.github/workflows/cpflow-deploy-review-app.yml`
@@ -63,6 +60,8 @@ The second command writes namespaced files so they can coexist with an app's exi
 - `.github/workflows/cpflow-deploy-staging.yml`
 - `.github/workflows/cpflow-promote-staging-to-production.yml`
 - `.github/workflows/cpflow-cleanup-stale-review-apps.yml`
+- `bin/pin-cpflow-github-ref`
+- `bin/test-cpflow-github-flow`
 
 `cpflow generate` also infers the app prefix from the repo directory, infers the
 Docker base Ruby version from `.ruby-version`, `.tool-versions`, or the app's
@@ -253,14 +252,118 @@ 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`.
 
-## Composite Actions
+## Upstream Reusable Workflows
 
-The generated workflows share these local composite actions:
+The generated workflows are intentionally small wrappers. The deployment logic,
+comment formatting, Control Plane CLI setup, Docker image build, and cleanup helpers
+live in upstream reusable workflows and composite actions in this repository.
 
-- `cpflow-setup-environment`: installs Ruby, the Control Plane CLI, and the `cpflow` gem, then logs into the target org
+- `cpflow-setup-environment`: installs Ruby, the Control Plane CLI, and `cpflow`, then logs into the target org. By default it builds `cpflow` from the checked-out upstream reusable-workflow ref; set the `CPFLOW_VERSION` repository variable only when you want to force a published RubyGems release.
 - `cpflow-build-docker-image`: builds and pushes the app image with the desired commit SHA
 - `cpflow-delete-control-plane-app`: safely deletes temporary apps and refuses to touch names outside the configured review-app prefix
 
+## Version Pins: GitHub Ref vs RubyGems
+
+The generated `cpflow-*` workflow files are thin wrappers around reusable
+workflows in `shakacode/control-plane-flow`. GitHub loads reusable workflows
+from a repository ref, not from the Ruby gem, so each wrapper has an upstream
+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:
+
+- `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 stable release path is still gem-driven:
+
+1. Publish a `cpflow` gem.
+2. Install or bundle that released gem in the downstream project.
+3. Run `cpflow generate-github-actions`.
+4. Commit the generated wrappers that point to the matching upstream release tag
+   such as `v5.0.0`.
+
+That release tag should point to the same source that produced the RubyGems
+release. Downstream production automation should use release tags, not `main` or
+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`.
+
+## Testing Unreleased Upstream Changes Downstream
+
+You can test a `control-plane-flow` PR in a downstream app before merging or
+releasing it. Use an immutable commit SHA from the upstream PR branch:
+
+1. Push the upstream PR branch and copy its full 40-character head SHA.
+2. In a downstream test branch, run:
+
+   ```sh
+   bin/pin-cpflow-github-ref <upstream-pr-sha>
+   ```
+
+   The helper updates every generated `cpflow-*` workflow wrapper. It accepts
+   release tags and full commit SHAs by default, rejects branch names such as
+   `main` or `feature/foo`, and requires `--allow-moving-ref` for short-lived
+   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.
+4. Run:
+
+   ```sh
+   bin/test-cpflow-github-flow
+   ```
+
+   Pass a local checkout command when you are validating unreleased generator
+   code before it is installed:
+
+   ```sh
+   bin/test-cpflow-github-flow ruby /path/to/control-plane-flow/bin/cpflow
+   ```
+
+5. Open a downstream PR and trigger the real review app with a comment whose body
+   is exactly:
+
+   ```text
+   +review-app-deploy
+   ```
+
+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.
+
+This tests the real reusable workflow, shared composite actions, and source-built
+`cpflow` gem from one immutable upstream commit. It avoids merging upstream blind
+and avoids running production automation against a moving branch.
+
+## Local Generated-Flow Checks
+
+Run this after generation or after changing a downstream wrapper ref:
+
+```sh
+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`.
+
 ## Applying This to React on Rails Demo Apps
 
 This flow is a good fit for the React on Rails demo apps because they already follow the same basic assumptions:

data/docs/commands.md

@@ -78,15 +78,21 @@ cpflow cleanup-images -a $APP_NAME
 
 ### `cleanup-stale-apps`
 
-- Deletes the whole app (GVC with all workloads, all volumesets and all images) for all stale apps
-- Also unbinds the app from the secrets policy, as long as both the identity and the policy exist (and are bound)
-- Stale apps are identified based on the creation date of the latest image
+- Acts on stale apps based on the creation date of the latest image, or the GVC if no images exist
+- With `--mode=delete` (default): deletes the whole app (GVC with all workloads, all volumesets and all images), and unbinds the app from the secrets policy as long as both the identity and the policy exist (and are bound)
+- With `--mode=stop`: suspends all workloads via `cpflow ps:stop` — no GVC, volumeset, or image is removed; resume with `cpflow ps:start`
+- `--mode=stop` only suspends workloads listed in `app_workloads` + `additional_workloads`; workloads present in the live GVC but missing from the config are skipped silently
+- `--mode=stop` returns once each workload is marked suspended; it does not wait for the workload to reach a not-ready state
 - Specify the amount of days after an app should be considered stale through `stale_app_image_deployed_days` in the `.controlplane/controlplane.yml` file
-- If `match_if_app_name_starts_with` is `true` in the `.controlplane/controlplane.yml` file, it will delete all stale apps that start with the name
+- If `match_if_app_name_starts_with` is `true` in the `.controlplane/controlplane.yml` file, it will act on all stale apps that start with the name
 - Will ask for explicit user confirmation
 
 ```sh
+# Deletes stale apps (default).
 cpflow cleanup-stale-apps -a $APP_NAME
+
+# Stops stale apps instead of deleting them; resume with `cpflow ps:start`.
+cpflow cleanup-stale-apps -a $APP_NAME --mode=stop
 ```
 
 ### `config`
@@ -214,7 +220,7 @@ other than `main` or `master`; the generator will bake that branch into the
 GitHub Actions push trigger and use it as the default STAGING_APP_BRANCH.
 
 ```sh
-# Creates .github/actions and .github/workflows files for the Control Plane flow
+# Creates thin .github/workflows wrappers for the Control Plane flow
 cpflow generate-github-actions
 
 # Creates the flow with staging deploys triggered from develop