cpflow 5.3.0 → 6.0.0.rc.0

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

@@ -10,7 +10,7 @@ first.
 ```text
 Set up Control Plane GitHub Flow for this repo. First make sure the `cpflow` CLI is available: use the repo's existing `bundle exec cpflow` if present, otherwise install the published `cpflow` Ruby gem with `gem install cpflow`; if neither is possible, stop and report that blocker. Use the same `cpflow` invocation for the rest of the rollout. 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 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. When bumping the `cpflow` gem in a downstream repo, run `cpflow update-github-actions` (or `bundle exec cpflow update-github-actions`) and validate with `bin/test-cpflow-github-flow` in the same PR so the checked-in wrappers move to the matching release tag. Keep the normal generated review-app setup simple: review apps require only `CPLN_TOKEN_STAGING` when the generated review app config can be inferred. For public demos, starter staging apps, and long-lived review apps, keep the app workload `type: standard` with one warm replica, set its autoscaling metric to `disabled`, and enable `capacityAI: true` so Control Plane can right-size CPU and memory allocation at that fixed replica count. Shared Postgres and other stateful workloads are the usual exceptions and should stay manually sized; Capacity AI is for supported stateless app/service workloads. If true idle scale-to-zero is explicitly required, create a separate `serverless` workload before first deploy or plan a delete/recreate migration because Control Plane will not change an existing `standard` workload to `serverless` in place. For shared review-app resources such as one staging database, use `shared_secret_grants` and `{{SHARED_SECRET_DATABASE}}` placeholders instead of hardcoding the base app secret name; this keeps review-app policy binding and cleanup automatic while avoiding per-PR database cost. Document the one-time Control Plane bootstrap command for persistent staging and production apps with `cpflow setup-app --skip-post-creation-hook`; for existing apps or later template updates, document `cpflow apply-template` and the need for the app identity to have `reveal` on the app secret policy. Do not imply the staging deploy or promotion workflows create those persistent GVCs. 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.
+If `.controlplane/` is missing, run `cpflow generate`. Treat the generated app names as the repo-name default 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. Keep every generated Control Plane Flow source pin synchronized at the same `vX.Y.Z`: each reusable-workflow `uses: ...@vX.Y.Z` ref, the production promotion `.cpflow` checkout ref, and its `control_plane_flow_ref` setup input. By default, `cpflow generate-github-actions` derives these values from the installed `cpflow` gem version; temporary explicit ref overrides are for unreleased testing and must keep all three values synchronized. Keep the generated `.github/actions/cpflow-*` files from that same gem unchanged; upstream reusable workflows invoke those checked-in local actions and separately check out the matching runtime source at `.cpflow`. When bumping the `cpflow` gem in a downstream repo, run `cpflow update-github-actions` (or `bundle exec cpflow update-github-actions`) and validate with `bin/test-cpflow-github-flow` in the same PR so the checked-in workflows and local actions move together. Keep the normal generated review-app setup simple: review apps require only `CPLN_TOKEN_STAGING` when the generated review app config can be inferred. For public demos, starter staging apps, and long-lived review apps, keep the app workload `type: standard` with one warm replica, set its autoscaling metric to `disabled`, and enable `capacityAI: true` so Control Plane can right-size CPU and memory allocation at that fixed replica count. Shared Postgres and other stateful workloads are the usual exceptions and should stay manually sized; Capacity AI is for supported stateless app/service workloads. If true idle scale-to-zero is explicitly required, create a separate `serverless` workload before first deploy or plan a delete/recreate migration because Control Plane will not change an existing `standard` workload to `serverless` in place. For shared review-app resources such as one staging database, use `shared_secret_grants` and `{{SHARED_SECRET_DATABASE}}` placeholders instead of hardcoding the base app secret name; this keeps review-app policy binding and cleanup automatic while avoiding per-PR database cost. Document the one-time Control Plane bootstrap command for persistent staging and production apps with `cpflow setup-app --skip-post-creation-hook`; for existing apps or later template updates, document `cpflow apply-template` and the need for the app identity to have `reveal` on the app secret policy. Do not imply the staging deploy or promotion workflows create those persistent GVCs. 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`.
 
@@ -46,7 +46,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/cpflow-help.md` and `.github/workflows/cpflow-*` wrappers are in place
+- `.github/cpflow-help.md`, `.github/workflows/cpflow-*`, and `.github/actions/cpflow-*` 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/ci-automation.md

@@ -23,7 +23,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 `cpflow-*` workflow wrappers. Review-app, staging, cleanup, and helper workflows call upstream reusable workflows; production promotion is a normal caller-repo job so it can own the protected production Environment.
+3. `cpflow generate-github-actions` — adds `cpflow-*` workflow wrappers and `.github/actions/cpflow-*` composite actions. Review-app, staging, cleanup, and helper workflows call upstream reusable workflows; production promotion is a normal caller-repo job so it can own the protected production Environment.
 4. Configure the [GitHub Actions secrets and variables](#github-actions-secrets-and-variables) the workflows expect.
 5. Push the branch, then comment `+review-app-deploy` on a PR to spin up a review environment.
 
@@ -69,6 +69,7 @@ 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`
+- `.github/actions/cpflow-*` (the local composite actions used by those workflows)
 - `bin/pin-cpflow-github-ref`
 - `bin/test-cpflow-github-flow`
 
@@ -214,7 +215,8 @@ 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
+- disable administrator bypass if your organization requires two-person control
+- 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`
@@ -473,7 +475,12 @@ The generated flow uses these defaults:
   makes the newest intent fail closed instead of falling back to an older operation. This permission gate applies to every
   `+review-app-deploy` comment, whether or not a review app already exists. Later pushes to a base-repository branch PR
   redeploy automatically without another approval because the auto-push path (`pull_request` event) does not use the
-  comment permission gate;
+  comment permission gate. The reusable deploy workflow loads generated local actions through `actions/checkout`'s
+  default with no `ref:` override, which resolves to the commit GitHub recorded for the triggering event: the
+  pull-request merge revision for automatic same-repository deploys, the selected ref for manual dispatch, or the
+  default-branch revision for comment triggers. This keeps the wrapper and generated actions synchronized during an
+  upgrade or first-installation PR. Preserve the same-repository caller guard because pull-request workflow and action
+  code run with staging/review credentials;
 - fork pull requests cannot deploy via the generated `pull_request` path because the caller workflow's job-level `if:`
   condition explicitly skips fork-originated runs. For `issue_comment` events, the caller `if:` restricts invocation to
   the exact command shape; the reusable workflow resolves repository permission before its deploy job runs, then its
@@ -510,13 +517,16 @@ generated staging/review org and make that token disposable and unable to access
 The PR-close teardown workflow runs trusted base-branch workflow code with repository secret access so it can delete fork
 PR review apps. The generated `cpflow-delete-control-plane-app` composite action script refuses to call `cpflow delete`
 on any app whose name does not match the review-app prefix. This shell-level guard is effective because the generated
-delete workflow checks out base/default-branch code, not PR or fork code: its repository checkout has no `ref:` override,
-so `pull_request_target` runs use the base branch. If you customize this workflow, never check out PR or fork code in the
-same job as the delete step; doing so could let a PR replace the guard script itself and would also make
-`hooks.pre_deletion` come from the PR's `controlplane.yml`. This is still not a token policy, so use a scoped staging
-service account limited to review/staging operations. A configured `hooks.pre_deletion` command still runs through the
-latest PR-built image on all delete paths: PR-close teardown, `+review-app-delete` comments, manual dispatch, and
-scheduled cleanup. Review-app credentials must remain disposable even during deletion.
+delete workflow loads generated actions through `actions/checkout`'s default with no `ref:` override, which resolves to
+the commit GitHub recorded for the triggering event (`GITHUB_SHA`, the base-branch tip under `pull_request_target`). Its
+separate app checkout has no `ref:` override either, so `pull_request_target` teardown uses base-branch code for both
+paths rather than PR or fork code. If you customize this
+workflow, never check out PR or fork code in the same job as the delete step; doing so could let a PR replace the guard
+script itself and would also make `hooks.pre_deletion` come from the PR's `controlplane.yml`. This is still not a token
+policy, so use a scoped staging service account limited to review/staging operations. A configured
+`hooks.pre_deletion` command still runs through the latest PR-built image on all delete paths: PR-close teardown,
+`+review-app-delete` comments, manual dispatch, and scheduled cleanup. Review-app credentials must remain disposable
+even during deletion.
 
 If you customize the generated `pull_request_target` workflow, never pass `github.event.pull_request.head.sha` or another
 fork-controlled ref to `actions/checkout`, `git fetch`, `git merge`, `git cherry-pick`, or any other step that fetches,
@@ -698,11 +708,13 @@ wrapper-level `if:` guard shown in that file, for example
 ## Upstream Workflows And Actions
 
 Most 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. Production promotion is expanded into the caller repository so
-it can own `environment: production`, but it still checks out the same upstream
-ref for shared composite actions.
+logic and comment formatting live in upstream reusable workflows. The canonical
+composite actions live in this repository and the gem copies them into each
+downstream repository at `.github/actions/cpflow-*`; the reusable workflows use
+those regular local action paths. They separately check out the matching
+upstream ref at `.cpflow` for the `cpflow` runtime source. Production promotion
+is expanded into the caller repository so it can own `environment: production`,
+but follows the same local-action and `.cpflow` source split.
 
 - `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 `control-plane-flow` 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
@@ -727,37 +739,51 @@ reusable-workflow wrappers should not pass `control_plane_flow_ref`; if you see
 that input outside the production promotion setup step, regenerate with a newer
 `cpflow`.
 
-There are two locks, and they protect different things:
+There are two coordinated inputs, and they protect different things:
 
-- 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 GitHub ref locks the reusable workflow and the `.cpflow` runtime source
+  checkout that GitHub runs.
+- The installed Ruby gem supplies the generated local composite actions and
+  wrappers. `CPFLOW_VERSION`, when configured, separately locks the published
+  `cpflow` runtime installed by the setup action.
 
 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:
+developers must commit the generated wrappers and local actions from the gem
+that matches the upstream release tag:
 
 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`.
+4. Commit the generated wrappers and `.github/actions/cpflow-*` files; the
+   wrappers should 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.
 
+Generated cross-repository reusable-workflow calls deliberately use an exact
+release tag such as `v5.0.0`. This is the intentional downstream exception to
+the repository's full-SHA external-action policy: it keeps the installed gem,
+generated wrappers, generated local actions, and upstream workflow on one
+reviewed release update contract. It does not extend to external actions inside
+those workflows, which remain pinned to full commit SHAs with readable release
+comments. Unreleased downstream validation temporarily replaces the exact tag
+with the upstream PR's full commit SHA as described below; moving version
+aliases and branches remain forbidden.
+
 ## Updating Generated GitHub Actions After Gem Updates
 
-Whenever a downstream repo updates the `cpflow` gem, update the checked-in
-GitHub Actions wrappers in the same PR. The gem version does not make GitHub load
-new reusable workflow YAML by itself; GitHub loads the `uses:` ref committed in
-`.github/workflows/cpflow-*.yml`.
+Whenever a downstream repo updates the `cpflow` gem, update all checked-in
+GitHub Actions files in the same PR. The gem version does not make GitHub load
+new reusable workflow YAML or local action files by itself; GitHub uses the
+workflow ref and `.github/actions/cpflow-*` files committed in the repository.
+
+For a new repository that does not have generated wrappers yet, run
+`cpflow generate-github-actions` first. Use the update command below for later
+gem upgrades.
 
-Use the installed gem to refresh the generated wrappers:
+Use the installed gem to refresh the generated workflows and actions:
 
 ```sh
 cpflow update-github-actions
@@ -771,11 +797,11 @@ bundle exec cpflow update-github-actions
 bin/test-cpflow-github-flow bundle exec cpflow
 ```
 
-`cpflow update-github-actions` regenerates the generated wrapper and helper
-files from the installed gem, pins the wrapper `uses:` refs to `v<gem-version>`,
-and preserves a single custom staging branch from the existing generated staging
-workflow. Pass `--staging-branch BRANCH` when changing or restoring a custom
-staging branch explicitly.
+`cpflow update-github-actions` regenerates the workflow wrappers, local
+composite actions, and helper files from the installed gem, pins the wrapper
+`uses:` refs to `v<gem-version>`, and preserves a single custom staging branch
+from the existing generated staging workflow. Pass `--staging-branch BRANCH`
+when changing or restoring a custom staging branch explicitly.
 
 When keeping `cpflow` in an app Gemfile, leave a comment next to the gem entry
 so future dependency bumps include the wrapper update:
@@ -809,7 +835,8 @@ action commit, so a moving branch named like `v5.0.0` cannot be used with
 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.
+same source that supplies the reusable workflow. Refresh the generated local
+actions from that checkout before testing as described below.
 
 ## Testing Unreleased Upstream Changes Downstream
 
@@ -817,24 +844,26 @@ 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:
+2. In a downstream test branch, regenerate from the upstream checkout and then
+   pin the wrappers to its exact SHA:
 
    ```sh
+   ruby /path/to/control-plane-flow/bin/cpflow update-github-actions
    bin/pin-cpflow-github-ref <upstream-pr-sha>
    ```
 
-   The helper updates every generated reusable-workflow `uses:` ref plus the
-   production workflow's pinned `control-plane-flow` checkout and setup
-   validation ref. 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. 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.
+   The update command copies the PR checkout's canonical composite actions into
+   `.github/actions/cpflow-*`. The pin helper then updates every generated
+   reusable-workflow `uses:` ref plus the production workflow's pinned
+   `control-plane-flow` checkout and setup validation ref. 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 pinned
+   upstream SHA. If `CPFLOW_VERSION` is set while the wrapper is pinned to a
+   SHA, the setup action fails before deployment because the published gem and
+   upstream source cannot be proven to match.
 4. Run:
 
    ```sh
@@ -848,25 +877,48 @@ releasing it. Use an immutable commit SHA from the upstream PR branch:
    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:
+5. Push the downstream test branch, then choose the remote validation path that
+   matches the repository's installation state.
+
+   For an existing installation, where `cpflow-deploy-review-app.yml` is already
+   present on the default branch, dispatch the workflow definition and generated
+   local actions from the unmerged downstream test branch against a suitable open
+   base-repository PR:
 
-   ```text
-   +review-app-deploy
+   ```sh
+   gh workflow run cpflow-deploy-review-app.yml --ref <downstream-test-branch> -f pr_number=<pr-number>
+   ```
+
+   The `--ref` selects the downstream wrapper and local-action commit under test;
+   `pr_number` selects the application source to deploy. Do not use a
+   `+review-app-deploy` comment for this pre-merge validation: `issue_comment`
+   always loads the workflow definition from the default branch, so it cannot
+   validate unmerged wrappers or local actions.
+
+   For a first installation, GitHub will not dispatch a workflow that does not
+   yet exist on the default branch, even when `--ref` names the installation
+   branch. Treat the rollout as staged: run the local contract before merging,
+   review the generated diff, merge it, and dispatch the merged workflow
+   immediately afterward against a suitable open base-repository PR:
+
+   ```sh
+   gh workflow run cpflow-deploy-review-app.yml --ref <default-branch> -f pr_number=<pr-number>
    ```
 
-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.
+6. Verify the dispatched 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. After merge, `+review-app-deploy` remains the normal
+   maintainer-facing trigger for subsequent review apps.
 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 workflows, the production workflow's checked-out
-shared composite actions, and the source-built `cpflow` gem from one immutable
-upstream commit. It avoids merging upstream blind and avoids running production
-automation against a moving branch.
+For an existing installation, this tests the real reusable workflows, the
+unmerged regenerated local composite actions, and the source-built `cpflow` gem
+against one immutable upstream commit. A first installation gets the same remote
+proof immediately after its locally validated files reach the default branch.
+Both paths avoid testing against a moving upstream branch.
 
 ## Local Generated-Flow Checks
 

data/docs/commands.md

@@ -85,7 +85,7 @@ cpflow cleanup-images -a $APP_NAME
 
 - 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 and any configured `shared_secret_grants` policies as long as both the identity and each 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`
+- With `--mode=stop`: suspends configured workloads that exist in the live GVC through Control Plane — 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
@@ -232,6 +232,9 @@ Creates GitHub Actions templates for a Heroku Flow style Control Plane pipeline:
 - manual promotion from staging to production
 - nightly cleanup and PR help workflows
 
+It also copies cpflow's composite actions into `.github/actions/cpflow-*`
+so every local `uses:` target is checked in and can be audited directly.
+
 Pass `--staging-branch BRANCH` when staging should auto-deploy from a branch
 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.
@@ -240,13 +243,13 @@ Pass `--force` to overwrite existing generated files. Prefer
 repo.
 
 ```sh
-# Creates thin .github/workflows wrappers for the Control Plane flow
+# Creates workflow wrappers, local composite actions, and validation helpers
 cpflow generate-github-actions
 
 # Creates the flow with staging deploys triggered from develop
 cpflow generate-github-actions --staging-branch develop
 
-# Overwrites existing generated wrappers from the installed cpflow gem
+# Overwrites existing generated GitHub Actions files from the installed cpflow gem
 cpflow generate-github-actions --force
 ```
 
@@ -483,6 +486,12 @@ timeout 300 cpflow ps:wait -a $APP_NAME
   (can be configured though `runner_job_timeout` in `controlplane.yml`)
 - Waiting for a runner replica is limited to the smaller of `runner_job_timeout` and 1000 seconds.
   A terminal cron status fails immediately, and reaching the observation deadline reports the last safe status
+- With non-interactive log methods 2 and 3, after a command prints its completion marker, Control Plane
+  has up to 20 minutes to reconcile the cron job to a terminal status. This can be configured through
+  `runner_job_status_reconciliation_timeout` in `controlplane.yml`; timing out exits nonzero and reports
+  the job, replica, and last observed status
+- Log method 1 does not emit a completion marker, so its job-status polling is not covered by the
+  post-command reconciliation timeout
 - Non-interactive jobs return the Control Plane cron job status even when the job finishes before
   Control Plane exposes a runner replica to attach logs to
 - Injects `CPFLOW_GVC_ID` and `CPFLOW_GVC_CREATED` into the job, exposing the app's immutable GVC
@@ -579,17 +588,18 @@ cpflow terraform import
 
 ### `update-github-actions`
 
-Regenerates the generated cpflow GitHub Actions wrappers and helper files
-from the currently installed cpflow gem. Use this after updating the
-cpflow gem so checked-in workflow wrappers move to the matching upstream
-release tag, for example `v5.2.0`.
+Regenerates the cpflow workflow wrappers, local composite actions, and
+helper files from the currently installed cpflow gem. Use this after
+updating the cpflow gem so checked-in workflow wrappers move to the
+matching upstream release tag, for example `v5.3.0`, and the
+generated action implementations move with them.
 
 If the existing generated staging workflow uses a custom single staging
 branch, the command preserves it. Pass `--staging-branch BRANCH` to set or
 replace the generated staging branch explicitly.
 
 ```sh
-# After updating the cpflow gem, refresh generated GitHub Actions wrappers
+# After updating the cpflow gem, refresh every generated GitHub Actions file
 cpflow update-github-actions
 
 # When running cpflow through Bundler

data/docs/rds-private-networking.md

@@ -6,13 +6,14 @@ path — not the public internet.
 
 This guide covers the recommended setup: **CPLN Cloud Wormhole via an Agent**.
 
-> **Sourcing note — verify field casing before you apply.** Field names, schema, and limits in this guide
-> are sourced from the public Control Plane documentation at <https://shakadocs.controlplane.com> as of
-> May 2026 and have **not** been end-to-end verified against a live org. This matters because a casing
-> mismatch **fails silently**: `cpln apply` accepts the file, ignores the unrecognized field, and the
-> workload then can't reach the database — with no error pointing back to the YAML. Before applying in
-> production, diff your edited files against a fresh `cpln identity get <name> -o yaml-slim` (and
-> `cpln agent get <name> -o yaml`) export to confirm the exact field names, and consult
+> **Field casing verified.** Sanitized `cpln identity get <name> -o yaml-slim` exports from live orgs
+> confirmed the `networkResources` nesting and the common `name`, `agentLink`, `FQDN`, and `ports` field casing.
+> The current Control Plane [Identity reference](https://shakadocs.controlplane.com/reference/identity) and
+> [Identity API](https://shakadocs.controlplane.com/api-reference/identity/get-an-identity-by-gvc-and-name)
+> confirm the alternative `IPs` form and optional `resolverIP` spelling; neither appeared in the inspected
+> live resources. Field names are case-sensitive: `cpln apply` can accept an unrecognized field while omitting
+> the intended route, without pointing back to the identity YAML. Before applying in production, check the new
+> block against these casing sources, diff your edited file against a fresh identity export, and consult
 > `cpln <command> --help` for the latest CLI flags.
 
 ## Why private networking
@@ -234,11 +235,10 @@ cpln identity get my-app-production-identity \
 Edit `identity-db.yaml` and **add** the `networkResources` block — keep every other apply-safe field
 exactly as exported:
 
-> ⚠️ **Verify field casing against your org before applying.** The field names below (`FQDN`, `IPs`,
-> `agentLink`, `resolverIP`) are sourced from public CPLN docs. If the live API uses different casing,
-> `cpln apply` will accept the file but silently ignore the resource — workloads will hit
-> `could not translate host name` with no obvious link to the identity YAML. Diff your edited file
-> against the original `yaml-slim` export from `cpln identity get` to confirm.
+> **Apply-safe editing:** start from a fresh `yaml-slim` export and diff your edited file against the
+> original before applying. This helps detect unintended changes to exported fields, but it does not validate
+> the newly added `networkResources` block. Check every key in that block, including `agentLink`, `FQDN`/`IPs`,
+> `resolverIP`, and `ports`, against the verified casing sources above.
 
 ```yaml
 # identity-db.yaml (after edit — abbreviated, your file will have more fields)

data/docs/releasing.md

@@ -23,6 +23,11 @@ Always update `CHANGELOG.md` before running the release task.
    - Fixes, improvements, deprecations, removals, or security updates: patch
 4. Merge the changelog PR before releasing.
 
+A minimum Ruby version change is a breaking change. Merge the gemspec floor,
+CI coverage for each supported Ruby minor, and an `Unreleased` breaking-change
+entry together. Keep `Cpflow::VERSION` unchanged in that implementation PR.
+The release task applies the required major version when the change ships.
+
 If updating the changelog manually, move the relevant `Unreleased` entries into
 a versioned header:
 
@@ -49,9 +54,13 @@ With no arguments, `rake release`:
 
 1. Reads the first versioned `CHANGELOG.md` header, such as `## [4.2.0]`.
 2. Uses that version when it is newer than the current gem version.
-3. Uses the current version if the changelog version matches the gem version
-   but has not been tagged yet.
-4. Falls back to a patch bump if no new changelog version is found.
+3. Keeps using that version when it matches the current gem version, including
+   on a retry after a release attempt created the version commit or tag.
+4. Lets the existing-tag policy stop an incomplete retry instead of silently
+   selecting a different version.
+5. Falls back to a patch bump only from a stable current version when the
+   changelog does not name the current or a newer version. Prereleases require
+   an explicit target if the changelog cannot supply one.
 
 Other supported forms:
 
@@ -152,4 +161,6 @@ bundle exec rake "sync_github_release[4.2.0]"
 ```
 
 If the tag was pushed but the gem was not published, delete or correct the tag
-and version commit intentionally before trying again.
+and version commit intentionally before trying again. A no-argument retry keeps
+the changelog version authoritative and refuses to reinterpret a prerelease as
+its stable version.

data/examples/controlplane.yml

@@ -104,6 +104,11 @@ aliases:
     # If not specified, defaults to 21600 (6 hours).
     runner_job_timeout: 1000
 
+    # Sets how long `cpflow run` waits for Control Plane to reconcile a cron job status
+    # after the non-interactive command prints its completion marker.
+    # If not specified, defaults to 1200 (20 minutes).
+    runner_job_status_reconciliation_timeout: 1200
+
     # Apps with a deployed image 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

data/lib/command/ai_github_flow_prompt.rb

@@ -32,7 +32,7 @@ module Command
       <<~PROMPT
         Set up Control Plane GitHub Flow for this repo. First make sure the `cpflow` CLI is available: use the repo's existing `bundle exec cpflow` if present, otherwise install the published `cpflow` Ruby gem with `gem install cpflow`; if neither is possible, stop and report that blocker. Use the same `cpflow` invocation for the rest of the rollout. 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. 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. When bumping the `cpflow` gem in a downstream repo, run `cpflow update-github-actions` (or `bundle exec cpflow update-github-actions`) and validate with `bin/test-cpflow-github-flow` in the same PR so the checked-in wrappers move to the matching release tag. Keep the normal generated review-app setup simple: review apps require only `CPLN_TOKEN_STAGING` when the generated review app config can be inferred. For public demos, starter staging apps, and long-lived review apps, keep the app workload `type: standard` with one warm replica, set its autoscaling metric to `disabled`, and enable `capacityAI: true` so Control Plane can right-size CPU and memory allocation at that fixed replica count. Shared Postgres and other stateful workloads are the usual exceptions and should stay manually sized; Capacity AI is for supported stateless app/service workloads. If true idle scale-to-zero is explicitly required, create a separate `serverless` workload before first deploy or plan a delete/recreate migration because Control Plane will not change an existing `standard` workload to `serverless` in place. For shared review-app resources such as one staging database, use `shared_secret_grants` and `{{SHARED_SECRET_DATABASE}}` placeholders instead of hardcoding the base app secret name; this keeps review-app policy binding and cleanup automatic while avoiding per-PR database cost. Document the one-time Control Plane bootstrap command for persistent staging and production apps with `cpflow setup-app --skip-post-creation-hook`; for existing apps or later template updates, document `cpflow apply-template` and the need for the app identity to have `reveal` on the app secret policy. Do not imply the staging deploy or promotion workflows create those persistent GVCs. 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.
+        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. Keep every generated Control Plane Flow source pin synchronized at the same `vX.Y.Z`: each reusable-workflow `uses: ...@vX.Y.Z` ref, the production promotion `.cpflow` checkout ref, and its `control_plane_flow_ref` setup input. By default, `cpflow generate-github-actions` derives these values from the installed `cpflow` gem version; temporary explicit ref overrides are for unreleased testing and must keep all three values synchronized. Keep the generated `.github/actions/cpflow-*` files from that same gem unchanged; upstream reusable workflows invoke those checked-in local actions and separately check out the matching runtime source at `.cpflow`. When bumping the `cpflow` gem in a downstream repo, run `cpflow update-github-actions` (or `bundle exec cpflow update-github-actions`) and validate with `bin/test-cpflow-github-flow` in the same PR so the checked-in workflows and local actions move together. Keep the normal generated review-app setup simple: review apps require only `CPLN_TOKEN_STAGING` when the generated review app config can be inferred. For public demos, starter staging apps, and long-lived review apps, keep the app workload `type: standard` with one warm replica, set its autoscaling metric to `disabled`, and enable `capacityAI: true` so Control Plane can right-size CPU and memory allocation at that fixed replica count. Shared Postgres and other stateful workloads are the usual exceptions and should stay manually sized; Capacity AI is for supported stateless app/service workloads. If true idle scale-to-zero is explicitly required, create a separate `serverless` workload before first deploy or plan a delete/recreate migration because Control Plane will not change an existing `standard` workload to `serverless` in place. For shared review-app resources such as one staging database, use `shared_secret_grants` and `{{SHARED_SECRET_DATABASE}}` placeholders instead of hardcoding the base app secret name; this keeps review-app policy binding and cleanup automatic while avoiding per-PR database cost. Document the one-time Control Plane bootstrap command for persistent staging and production apps with `cpflow setup-app --skip-post-creation-hook`; for existing apps or later template updates, document `cpflow apply-template` and the need for the app identity to have `reveal` on the app secret policy. Do not imply the staging deploy or promotion workflows create those persistent GVCs. 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/command/cleanup_stale_apps.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Command
-  class CleanupStaleApps < Base
+  class CleanupStaleApps < Base # rubocop:disable Metrics/ClassLength
     CLEANUP_MODE_OPTION = {
       name: :mode,
       params: {
@@ -24,7 +24,7 @@ module Command
     LONG_DESCRIPTION = <<~DESC
       - 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 and any configured `shared_secret_grants` policies as long as both the identity and each 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`
+      - With `--mode=stop`: suspends configured workloads that exist in the live GVC through Control Plane — 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
@@ -101,14 +101,38 @@ module Command
     def process_app(app)
       if mode == "stop"
         progress.puts("Stopping app '#{app}'")
-        run_cpflow_command("ps:stop", "-a", app)
+        stop_configured_live_workloads(app)
       else
         run_cpflow_command("delete", "-a", app, "--yes")
       end
     end
 
+    def stop_configured_live_workloads(app)
+      app_config = config.find_app_config(app)
+      raise "Can't find config for stale app '#{app}'." unless app_config
+
+      configured_workloads = required_app_option(app_config, app, :app_workloads) +
+                             required_app_option(app_config, app, :additional_workloads)
+      live_workloads = (cp.fetch_workloads(app)&.fetch("items", []) || []).map { |workload| workload.fetch("name") }
+
+      (configured_workloads & live_workloads).each do |workload|
+        step("Stopping workload '#{workload}'") do
+          cp.set_workload_suspend(workload, true, app, missing_ok: true)
+        end
+      end
+    end
+
+    def required_app_option(app_config, app, option)
+      raise "Can't find option '#{option}' for app '#{app}' in 'controlplane.yml'." unless app_config.key?(option)
+
+      value = app_config.fetch(option)
+      raise "Option '#{option}' for app '#{app}' in 'controlplane.yml' must be an array." unless value.is_a?(Array)
+
+      value
+    end
+
     def action_description
-      mode == "stop" ? "suspend all workloads in" : "delete"
+      mode == "stop" ? "suspend configured workloads in" : "delete"
     end
 
     def mode

data/lib/command/copy_image_from_upstream.rb

@@ -80,6 +80,9 @@ module Command
         upstream_image = cp.latest_image(@upstream, @upstream_org) if !upstream_image || upstream_image == "latest"
         @commit = cp.extract_image_commit(upstream_image)
         @upstream_image_url = "#{@upstream_org}.registry.cpln.io/#{upstream_image}"
+      rescue ControlplaneApiDirect::ForbiddenError => e
+        Shell.write_to_tmp_stderr(e.message)
+        false
       end
     end