cpflow 5.1.1 → 5.3.0

data/docs/ci-automation.md

@@ -10,6 +10,13 @@ The goal is to bring the Heroku Flow model into any `cpflow` project:
 4. Promote the already-built staging artifact to production from the Actions tab.
 5. Let a nightly workflow clean up stale review apps.
 
+For public repositories, review apps are intentionally limited to branches in the base repository. Fork pull requests can
+receive help comments, but generated deploy workflows skip fork heads because review-app deployment builds Docker images
+with repository secrets. The skip is enforced by complementary guards on different trigger axes; see
+[Review app security for repositories with external contributors](#review-app-security-for-repositories-with-external-contributors)
+before customizing these workflows. If a forked change needs a review app, a maintainer should first review the code and
+move the change into a trusted branch in the base repository.
+
 ## Quick Start
 
 End-to-end rollout in one view:
@@ -17,9 +24,11 @@ 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.
-4. Configure the GitHub [repository secrets and variables](#required-github-repository-settings) the workflows expect.
+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.
 
+AI rollout: copy the [AI rollout prompt](./ai-github-flow-prompt.md) when you want an agent to run this setup. The prompt works whether `cpflow` is already installed or the agent needs to install it first. If `cpflow` is already available in the target repo, `cpflow ai-github-flow-prompt` prints the same prompt with the default app prefix filled in.
+
 See [Bootstrap a Project](#bootstrap-a-project) for command details, [Repo Readiness Checklist](#repo-readiness-checklist) for what "ready" means, and [AI Playbook](#ai-playbook) to run the rollout through an agent.
 
 ## Bootstrap a Project
@@ -137,7 +146,8 @@ apps:
     match_if_app_name_starts_with: true
     hooks:
       post_creation: bundle exec rails db:prepare
-      pre_deletion: bundle exec rails db:drop
+      # pre_deletion intentionally omitted for shared databases: `cpflow delete` runs it before removing the workloads,
+      # so live connections can block the drop. Prefer admin-side cleanup. See docs/tips.md ("Share One Control Plane Postgres").
 
   my-app-production:
     <<: *common
@@ -155,14 +165,23 @@ Important points:
 - 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.
+- For public demos, starter staging apps, and long-lived review apps, prefer `capacityAI: true` with one warm replica
+  and the workload's autoscaling metric disabled, so Control Plane can right-size CPU and memory allocation at that
+  fixed replica count. See
+  [Enable Capacity AI for Demo and Starter Staging Apps](tips.md#enable-capacity-ai-for-demo-and-starter-staging-apps).
+
+## GitHub Actions Secrets and Variables
 
-## Required GitHub Repository Settings
+### GitHub Actions Secrets
 
-For a normal generated review-app setup, configure one repository secret:
+For a normal generated review-app setup, configure one GitHub Actions secret:
 
-- `CPLN_TOKEN_STAGING`: token for the staging Control Plane org
+- `CPLN_TOKEN_STAGING`: service-account token scoped to the staging Control Plane org on controlplane.com. Its policies
+  should allow only review/staging CI operations; it must not read production secrets or manage production workloads.
 
-No GitHub repository variables are required for review apps when `.controlplane/controlplane.yml`
+### GitHub Actions Variables
+
+No GitHub Actions 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`,
@@ -171,9 +190,13 @@ 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`
+- `CPLN_ORG_STAGING`: Control Plane org on controlplane.com for staging and review apps. Overrides the 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`
+- `PRIMARY_WORKLOAD`: override the public workload used to discover the public endpoint and do review/production health checks; defaults to `rails`
+- `REVIEW_APP_HEALTH_CHECK_RETRIES`: override review-app health polling attempts; defaults to `24`
+- `REVIEW_APP_HEALTH_CHECK_INTERVAL`: override seconds between review-app health attempts; defaults to `15`
+- `REVIEW_APP_HEALTH_CHECK_ACCEPTED_STATUSES`: override space-separated healthy HTTP statuses for review apps; defaults to `200 301 302`
+- `REVIEW_APP_HEALTH_CHECK_CURL_MAX_TIME`: override per-request review-app curl timeout in seconds; defaults to `10`
 
 If `controlplane.yml` defines more than one app with
 `match_if_app_name_starts_with: true`, inference intentionally fails. Set
@@ -304,6 +327,20 @@ the run early instead of deploying an image that cannot boot.
 
 Review apps are different: the generated `+review-app-deploy` workflow creates
 temporary PR apps as needed, including the identity and secret policy binding.
+For an existing review app, each deployment runs
+`cpflow setup-app --refresh-templates` before building and deploying the new
+image. Refresh mode reapplies the configured `setup_app_templates` without
+deleting the GVC or running `hooks.post_creation`, answers template replacement
+prompts noninteractively, preserves each matching workload container's exact
+configured app-image reference even when the app is unhealthy or workloads use
+different image versions, and repairs the configured app and shared-secret
+policy bindings. A missing or invalid workload image uses only an unambiguous
+app image from ready workloads; refresh fails closed rather than selecting the
+registry's newest image. Preserving image references keeps release-phase and
+ordered-deploy gates in control of image rollout; a template failure stops the
+workflow before the image build or deployment. Existing secret templates are skipped
+as whole resources, so refresh neither changes existing values nor adds newly templated
+keys; provision required new keys separately before deployment.
 You still need the shared review-app runtime secret values described by your
 templates, and the staging token must have access to create and update
 review-app GVCs, workloads, images, identities, policies, and secrets in the
@@ -311,12 +348,13 @@ staging org.
 
 If review apps share an existing staging database or another existing secret,
 declare it with `shared_secret_grants` on the review app config entry. The
-deploy workflow runs `setup-app` for new review apps and `deploy-image` for
-image updates; those commands bind or repair the review app identity's `reveal`
-permission on each configured shared policy. The delete and cleanup workflows
-call `cpflow delete`, which removes those bindings as review apps go away. This
-lets one shared database or license secret serve many short-lived review apps
-without granting every review identity access to unrelated app secrets.
+deploy workflow runs `setup-app` for new review apps, refreshes templates for
+existing review apps, and then runs `deploy-image`; those commands bind or
+repair the review app identity's `reveal` permission on each configured shared
+policy. The delete and cleanup workflows call `cpflow delete`, which removes
+those bindings as review apps go away. This lets one shared database or license
+secret serve many short-lived review apps without granting every review
+identity access to unrelated app secrets.
 
 ```yaml
 apps:
@@ -356,7 +394,11 @@ The standard path is:
    references are copied by digest, commit-suffixed tags keep the commit suffix,
    and plain numeric tags remain valid.
 11. Expect production health and rollback readiness polling to require Control
-   Plane `status.ready` and `status.readyLatest` before checking the endpoint.
+   Plane `status.ready` and `status.readyLatest` before checking the standard
+   workload endpoint. If that endpoint is unavailable, as it can be on BYOK
+   locations, the health check waits until every reported deployment location
+   is ready and not deploying, then tries their endpoints sequentially. Each
+   additional location can add up to `curl_max_time` to an attempt.
 
 GitHub only exposes environment secrets to jobs that reference the environment
 after configured protection rules pass. GitHub does not allow a caller job that
@@ -377,6 +419,9 @@ Recommended org layout:
 
 - keep review apps and staging in a staging org that developers can access
 - keep production in a separate org with tighter access controls
+- for public repositories, use a staging/review token generated from a service account whose policies only allow
+  review/staging CI operations; use a dedicated review-app org only if you also customize the generated
+  workflow/configuration to target that org separately
 
 Optional repository secret for private dependency builds:
 
@@ -393,6 +438,115 @@ Advanced optional repository variables:
 - `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.
 
+## Review App Security for Repositories with External Contributors
+
+Review-app deployment and teardown can execute pull request code. Even when the workflow itself is trusted, the
+Dockerfile, package scripts, Rails initializers, server-rendering code, application runtime, any `release_script` or
+`hooks.post_creation` defined in the PR's `.controlplane/controlplane.yml`, and `.controlplane/templates/*.yaml` identity
+and policy templates applied by `cpflow setup-app` at first deploy with `CPLN_TOKEN_STAGING` can all be changed by the
+pull request being deployed. Teardown can also run a `hooks.pre_deletion` command through the latest PR-built image, even
+when the hook command comes from the base-branch config. A PR author can embed malicious code in that image; at runtime
+the code executes inside the review app workload and can read any secrets mounted into the workload environment.
+The generated setup action also exports `CPLN_TOKEN_STAGING` as `CPLN_TOKEN` via `GITHUB_ENV`, making it available in the
+process environment of every subsequent runner step for the rest of the job, so keep any custom runner steps after setup
+trusted. PR-controlled `release_script` and hook commands normally run through `cpflow run` in remote Control Plane
+containers from the latest image, not as runner shell steps, so they do not read that runner token directly unless a
+custom workflow passes a local token through. Inside the Control Plane workload, a separate runtime `CPLN_TOKEN` is
+available only when the workload spec has an `identityLink`; `skip_secrets_setup` skips automatic identity creation and
+binding, but templates can still attach an identity. Because `cpflow setup-app` reads `controlplane.yml` from the PR
+checkout, a PR can also set `skip_secrets_setup: false` or omit it to re-enable automatic identity binding unless the
+trusted workflow passes `--skip-secrets-setup` as a CLI flag. Do not treat `skip_secrets_setup` in `controlplane.yml` as
+a token-removal control or reliable security boundary. This is why workload-mounted secrets and the staging
+service-account token must remain disposable and scoped to minimum permissions.
+
+The generated flow uses these defaults:
+
+- same-repository pull requests can update existing review apps automatically on each push; creating the first review app
+  requires either a `+review-app-deploy` comment from someone whose current repository permission is `write`, `maintain`,
+  or `admin`, or a manual workflow dispatch by a repository collaborator with write access. GitHub's
+  collaborator-permission API resolves comment permissions when the command runs; `read` and `triage` access are not
+  sufficient, and an API lookup failure denies the command. Accepted triggers are recorded in a hidden, bot-authored
+  intent comment before queue admission. The mutating job authenticates the newest marker against its originating
+  Actions run and successful POST-only recording step, then rechecks the manual actor's current permission after it
+  acquires the per-PR queue. Editing or deleting
+  the original command comment therefore cannot reorder accepted work, and a permission revoked while the job waits
+  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;
+- 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
+  source-validation step checks fork status before checking out or building PR code. These complementary guards cover
+  different axes, so preserve both. Even a write-authorized comment on a fork PR cannot deploy that fork head.
+  Removing the source-validation guard opens a path to deploy untrusted code with repository-secret access,
+  because `issue_comment` events execute with base-repository secret access. Removing the `pull_request` guard still
+  lets untrusted fork code into the staging environment even though GitHub withholds repository secrets from fork
+  `pull_request` runs. Keep both workflow guards in place because the workflow builds Docker images with repository
+  secrets;
+- review apps are also deleted automatically when the pull request closes; that PR-close path uses `pull_request_target`
+  so it runs in the base-repository context and has repository-secret access for teardown. That is also why you must
+  never check out PR or fork code in this job; see the customization guidance below. The PR-close path does not require a
+  comment permission check. The generated `cpflow-delete-review-app.yml` pins `GITHUB_TOKEN` permissions to the minimum it needs
+  (`actions: write`, `contents: read`, `deployments: write`, `issues: write`, `pull-requests: write`). `actions: write` is used
+  only to redispatch the newest accepted deploy/delete operation when GitHub replaces the corresponding pending run;
+  if you customize this workflow, preserve that `permissions:` block because omitting it can fall back to broader
+  repository defaults;
+- manual workflow dispatch by a repository collaborator can also delete a review app without a `+review-app-delete`
+  comment. It is recorded in the same intent order as comment and automatic triggers, and the actor's current repository
+  permission is rechecked after queue admission;
+- write-authorized comments on fork PRs still do not deploy the fork head; the workflow posts no PR comment or command
+  reaction in this case. The authorization job records no accepted intent, and the skip appears in its
+  `Prepare accepted review app intent` log. Review the fork code
+  carefully, then move the change to a branch in the base repository if it needs a generated review app. That build will
+  run with repository-secret access;
+- production promotion is manual and uses production environment secrets separately from review and staging.
+
+The generated review-app workflow targets the staging/review Control Plane org inferred from `cpln_org` in
+`controlplane.yml`, or overridden by `CPLN_ORG_STAGING`, and uses the token from `CPLN_TOKEN_STAGING`. A fully separate
+review-app org or token requires workflow/configuration customization; otherwise, keep review apps and staging in the
+generated staging/review org and make that token disposable and unable to access production resources.
+
+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.
+
+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,
+materializes, or executes the ref. Those operations run untrusted fork code with repository secret access. Referencing the
+SHA as an opaque identifier for deployment status updates, comments, or API calls is safe because SHA values are hex-only
+and cannot contain shell metacharacters. Do not apply that reasoning to other attacker-controlled PR event fields such as
+`head.ref`, `head.label`, `title`, `body`, `head.repo.full_name`, or repository descriptions; pass user-controlled strings
+through environment variables instead of interpolating them directly into `run:` steps.
+
+These defaults protect repository secrets from direct fork PR execution, but they do not make deployed PR code harmless.
+For repositories with external contributors, keep review-app credentials and runtime values disposable:
+
+- do not mount production secrets, staging customer data, package-publishing tokens, payment keys, or monitoring tokens
+  into review apps;
+- do not use `DOCKER_BUILD_SSH_KEY` with a long-lived personal key or broad deploy key; see
+  [Docker Builds with Private Dependencies](#docker-builds-with-private-dependencies) for the minimum-access deploy-key
+  requirements;
+- do not use broad Control Plane `superusers` tokens for review-app CI; use a review/staging service account scoped only to
+  review/staging CI operations;
+- keep review databases, Redis instances, object stores, and renderer credentials separate from staging and production;
+- rotate any credential that may have been exposed to a malicious review-app build;
+- use scheduled cleanup so stale review apps stop consuming compute and secrets access. Cleanup deletes apps through
+  `cpflow delete`, so any configured `hooks.pre_deletion` still runs through the latest PR-built image; review-app
+  credentials must remain disposable for this path too.
+
+Secret indirection such as `cpln://secret/...` protects values in Control Plane configuration. It does not protect a
+value after that secret is mounted into a workload that runs pull request code. See
+[Secrets and ENV Values - Review app secrets](./secrets-and-env-values.md#review-app-secrets) for review-app secret
+handling guidance.
+
 ## Docker Builds with Private Dependencies
 
 Some apps need extra Docker build configuration before the generated workflows are turnkey. Common examples are:
@@ -417,8 +571,24 @@ DOCKER_BUILD_EXTRA_ARGS=--build-arg=BUNDLE_WITHOUT=development:test
 
 The action will start an SSH agent, add the key, write `known_hosts`, and pass `--ssh=default` to `cpflow build-image`. When `DOCKER_BUILD_SSH_KNOWN_HOSTS` is unset, the generated action uses pinned GitHub.com host keys by default. If your Dockerfile relies on `RUN --mount=type=ssh`, validate the build locally with `cpflow build-image -a <app> --ssh=default` before relying on CI.
 
+Do not configure `DOCKER_BUILD_SSH_KEY` unless the Dockerfile truly needs it. When configured, it is available to all
+review-app and staging Docker builds; follow the review-app security guidance above by using a read-only, revocable
+deploy key scoped to the minimum private dependency access, and never use a personal SSH key.
+
 ## Generated Workflow Behavior
 
+The deploy and delete workflows share a per-PR concurrency group, but GitHub keeps at most one running and one pending
+member of a group and may replace the pending member without FIFO ordering. Each authorized trigger therefore records a
+hidden `github-actions[bot]` intent marker containing its operation and originating workflow-run identity before it joins
+the queue. Whichever job survives reads the complete marker ledger, authenticates the newest marker against the Actions
+run API and the source run's successful POST-only recording step, revalidates a manual actor's current permission, and either performs that operation or redispatches the matching
+generated workflow on the default branch. Internal redispatches reuse the existing marker only through a bot-owned
+handoff bound to the returned workflow-run ID and the exact successful source dispatch step; the superseded source job
+then stops before mutable work, and values entered manually in the internal handoff field are rejected. This convergence
+covers automatic PR events, manual dispatches, mixed-case comment admission, authorization
+completion in a different order from event creation, and edits or deletion of the original command comment. Invalid,
+forged, missing, or permission-revoked newest intents fail closed and never fall back to older work.
+
 `cpflow-review-app-help.yml`
 
 - Posts a quick reference when a pull request opens, including on fork-based PRs.
@@ -432,18 +602,52 @@ The action will start an SSH agent, add the key, write `known_hosts`, and pass `
 
 `cpflow-deploy-review-app.yml`
 
-- Creates a review app when someone comments `+review-app-deploy`.
+- Creates a review app when someone comments `+review-app-deploy` or via manual workflow dispatch by a repository
+  collaborator.
+- For manual dispatch, provide the PR number; the workflow rejects fork PRs at runtime because it builds Docker images
+  with repository secrets.
 - Redeploys an existing review app automatically on later PR pushes.
-- Creates a GitHub deployment and comments with the review URL and logs.
+- Creates a transient, non-production GitHub deployment and comments with the review URL and logs.
 - Leaves PR pushes alone until the first review app is explicitly requested, which keeps demo-app costs down.
-- Accepts `+review-app-deploy` only from trusted commenters (`OWNER`, `MEMBER`, or `COLLABORATOR`).
-- Skips fork-based PR deploys because the workflow builds Docker images with repository secrets.
+- When that no-app PR path succeeds without building or deploying, writes a prominent `Docker image not built` job
+  summary and returns the reusable-workflow output `image_built=false`. A downstream job can inspect
+  `needs.deploy.outputs.image_built`; a green deploy job with `false` is not Docker-image validation.
+- Repositories that require production-image validation before merge should add a separate required build job when
+  Dockerfile, runtime-version, or dependency files change. The cost-saving review-app path intentionally does not create
+  an app or build an image until `+review-app-deploy` is requested.
+- Supports cost-conscious review apps when paired with one warm replica, Capacity AI, and a disabled autoscaling
+  metric for public demos, starter staging apps, and long-lived review apps; see
+  [Enable Capacity AI for Demo and Starter Staging Apps](tips.md#enable-capacity-ai-for-demo-and-starter-staging-apps).
+- Accepts `+review-app-deploy` only when GitHub reports the commenter has `write`, `maintain`, or `admin` repository
+  permission. `read` and `triage` are denied, permission is checked again after queue admission, and lookup failures fail
+  closed. Manual dispatch follows the same post-queue permission rule.
+- Skips fork-based PR deploys because the workflow builds Docker images with repository secrets. An authorized comment on a
+  fork PR still does not deploy the fork head, and manual dispatch must use a base-repository PR number. A fork-targeted
+  request records no accepted intent and skips the mutating job. To give a fork PR a review app, review the code carefully first, then
+  move the change to a branch in the base repository. The build will then run with repository-secret access.
+- Rejects comment, manual, and internal deploy requests for a closed pull request before recording a durable intent, then
+  rechecks that the pull request is still open after queue admission. A doomed deploy therefore cannot supersede the
+  automatic close-triggered deletion that cleans up an existing review app.
 
 `cpflow-delete-review-app.yml`
 
 - Deletes the review app on `+review-app-delete`.
-- Also deletes it automatically when the pull request closes.
-- Accepts `+review-app-delete` only from trusted commenters (`OWNER`, `MEMBER`, or `COLLABORATOR`).
+- Also supports manual workflow dispatch by a repository collaborator. The comment-time permission gate does not apply,
+  but the dispatching actor's repository permission is rechecked after queue admission.
+- Also deletes it automatically when the pull request closes through a `pull_request_target` event, so repository secrets
+  are available for teardown; `hooks.pre_deletion` still executes through the latest PR-built image on this path, so
+  review-app credentials must remain disposable.
+- After Control Plane deletion succeeds, marks every GitHub deployment for the exact `review/<app-name>` environment
+  inactive so the repository does not retain a stale active review deployment, while skipping deployments whose latest
+  status is already inactive so repeated teardown is idempotent. Deploy and delete workflows share one per-PR
+  concurrency queue; the accepted-intent reconciliation described above compensates for GitHub replacing pending runs,
+  ensuring the newest accepted operation eventually wins and an older deploy cannot publish the final state after a
+  newer deletion. If GitHub deployment cleanup fails after Control Plane deletion, the workflow reports
+  that partial outcome accurately and still fails so the cleanup can be retried.
+- Accepts `+review-app-delete` only when GitHub reports the commenter has `write`, `maintain`, or `admin` repository
+  permission. `read` and `triage` are denied, permission is checked again after queue admission, and lookup failures fail
+  closed. Manual dispatch uses the same post-queue actor check; automatic PR-close teardown does not use a manual actor
+  permission check.
 
 `cpflow-deploy-staging.yml`
 
@@ -461,6 +665,12 @@ The action will start an SSH agent, add the key, write `known_hosts`, and pass `
 - Attempts a rollback of every configured application workload if the new production image does not come up healthy.
 - Creates a GitHub release after a successful promotion.
 
+`cpflow-deploy-review-app.yml`
+
+- Builds and deploys the pull request image after the review app exists or is created.
+- Waits for `PRIMARY_WORKLOAD` to report `readyLatest=true` and return an accepted HTTP status before marking the GitHub deployment successful.
+- Uses `REVIEW_APP_HEALTH_CHECK_*` repository variables to tune review-app health checks independently from production promotion.
+
 `cpflow-cleanup-stale-review-apps.yml`
 
 - Runs nightly and on demand.
@@ -717,15 +927,17 @@ In practice, porting the flow into a demo app usually follows five phases.
 
 13. Validate the real production Docker build before relying on the workflows, especially if asset compilation or SSR requires Node, extra system packages, multiple processes, extra Docker build flags, or persistent writable paths.
 14. Expect review app deploys to run only for branches in the base repository; fork PRs still get help comments, but deploys are skipped because the workflow uses repository secrets.
+15. For public repositories, confirm that review-app secrets are disposable and that `CPLN_TOKEN_STAGING` cannot access production resources.
 
 ## AI Playbook
 
-If you want an AI agent to apply this flow to another project, start with
-`cpflow github-flow-readiness`, then use the standalone
-[AI rollout prompt](./ai-github-flow-prompt.md). It captures the exact wording,
-hard stop conditions, and definition of done for this workflow. You can also
-run `cpflow ai-github-flow-prompt` from inside the target repo to print the
-current prompt with that repo's default app prefix already filled in.
+If you want an AI agent to apply this flow to another project, use the
+standalone [AI rollout prompt](./ai-github-flow-prompt.md). It captures the
+exact wording, hard stop conditions, and definition of done for this workflow,
+and it works whether `cpflow` is already installed or the agent needs to install
+it first. When `cpflow` is already available in the target repo,
+`cpflow ai-github-flow-prompt` prints the same prompt with that repo's default
+app prefix already filled in.
 
 Short version:
 

data/docs/commands.md

@@ -29,6 +29,8 @@ cpflow ai-github-flow-prompt
 - Publishes (creates or updates) those at Control Plane infrastructure
 - Picks templates from the `.controlplane/templates` directory
 - Templates are ordinary Control Plane templates but with variable preprocessing
+- Use `--preserve-existing-runtime` to retain each workload container's configured app image, even when the workload is unready, and skip existing secret resources entirely while applying other template changes
+- Missing or invalid workload images use only an unambiguous app image from ready workloads; refresh fails before applying templates when no safe fallback exists
 
 **Preprocessed template variables:**
 
@@ -149,6 +151,9 @@ cpflow delete -a $APP_NAME -w $WORKLOAD_NAME
 ### `deploy-image`
 
 - Deploys the latest image to app workloads
+- Use `--workload`/`-w` one or more times to deploy only selected app workloads
+- If `deploy_order` is configured and no `--workload` is provided, deploys ordered workload groups one at a time and waits for each group to be ready before continuing
+- Workloads listed in `app_workloads` but omitted from `deploy_order` deploy last as an implicit final group
 - Runs a release script before deploying if `release_script` is specified in the `.controlplane/controlplane.yml` file and `--run-release-phase` is provided
 - The release script is run in the context of `cpflow run` with the latest image
 - If the release script exits with a non-zero code, the command will stop executing and also exit with a non-zero code
@@ -156,7 +161,14 @@ cpflow delete -a $APP_NAME -w $WORKLOAD_NAME
 - Repairs missing `shared_secret_grants` policy bindings before running a release phase or updating workloads
 
 ```sh
+# Deploys the latest image to all app workloads.
 cpflow deploy-image -a $APP_NAME
+
+# Deploys only one app workload.
+cpflow deploy-image -a $APP_NAME -w node-renderer
+
+# Deploys only selected app workloads.
+cpflow deploy-image -a $APP_NAME -w node-renderer -w sidekiq
 ```
 
 ### `doctor`
@@ -374,6 +386,7 @@ cpflow open-console -a $APP_NAME
 - It performs the following steps:
   - Runs `cpflow copy-image-from-upstream` to copy the latest image from upstream
   - Runs `cpflow deploy-image` to deploy the image
+  - Honors `deploy_order` from `.controlplane/controlplane.yml` through `cpflow deploy-image`
   - If `.controlplane/controlplane.yml` includes the `release_script`, `cpflow deploy-image` will use the `--run-release-phase` option
   - If the release script exits with a non-zero code, the command will stop executing and also exit with a non-zero code
   - If `use_digest_image_ref` is `true` in the `.controlplane/controlplane.yml` file or `--use-digest-image-ref` option is provided, deployed image's reference will include its digest
@@ -468,8 +481,21 @@ timeout 300 cpflow ps:wait -a $APP_NAME
   and also overridden per job through `--cpu` and `--memory`)
 - By default, the job is stopped if it takes longer than 6 hours to finish
   (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
 - 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
+  identity, so that a command such as a release script can tell which GVC incarnation it is running in.
+  These change when a GVC is deleted and recreated under the same name, and only then, unlike
+  `CPLN_GVC_ALIAS`, which is also embedded in mutable derived values such as the app domain and so
+  cannot be attributed to recreation alone
+- `CPFLOW_GVC_CREATED` is the GVC's creation timestamp as returned by the Control Plane API and passed
+  through unmodified, currently an ISO 8601 UTC timestamp with millisecond precision and a `Z` suffix
+  (e.g. `2026-08-28T00:54:48.648Z`)
+- Both variables are always set, and are empty when the GVC cannot be read, so that a consumer can
+  fail closed. They are never omitted, because the runner inherits the original workload's
+  environment and an omitted variable could otherwise expose a stale inherited value
 
 ```sh
 # Opens shell (bash by default).
@@ -493,7 +519,8 @@ cpflow run -a $APP_NAME -- rails db:migrate
 # - stop the job
 cpflow run -a $APP_NAME --detached -- rails db:migrate
 
-# The command needs to be quoted if setting an env variable or passing args.
+# Quote the whole command to intentionally opt into shell syntax such as an env assignment.
+# Separately supplied command arguments are passed literally.
 cpflow run -a $APP_NAME -- 'SOME_ENV_VAR=some_value rails db:migrate'
 
 # Uses a different image (which may not be promoted yet).
@@ -528,6 +555,7 @@ cpflow run -a $APP_NAME --entrypoint /app/alternative-entrypoint.sh -- rails db:
 - Runs a post-creation hook after the app is created if `hooks.post_creation` is specified in the `.controlplane/controlplane.yml` file
 - If the hook exits with a non-zero code, the command will stop executing and also exit with a non-zero code
 - Use `--skip-post-creation-hook` to skip the hook if specified in `controlplane.yml`
+- Use `--refresh-templates` to apply configured templates noninteractively to an existing app while preserving each workload's configured app image even when workloads are unready or use mixed image versions, skipping existing secret resources entirely, repairing secrets access bindings, and skipping the post-creation hook
 
 ```sh
 cpflow setup-app -a $APP_NAME
@@ -554,7 +582,7 @@ cpflow terraform import
 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.1.0`.
+release tag, for example `v5.2.0`.
 
 If the existing generated staging workflow uses a custom single staging
 branch, the command preserves it. Pass `--staging-branch BRANCH` to set or