cpflow 5.0.4 → 5.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 51e0566b72525c5e975b384c12930f95ad5f13faaf1691ccbcca27b0c50a13b4
-  data.tar.gz: 91560ebafb43692488b8996ef5e05799a5621bc6066329a71636b3677d1c63e5
+  metadata.gz: 44479e287fa1f7366a4df86ee7f68176c00f2b6cd2fe59c786e5de6f1143d2b3
+  data.tar.gz: acbf5149907b43cc628d2af8c19572d0ffb5de6d1bae630cb98c14c5ca46d4cc
 SHA512:
-  metadata.gz: 89ec31dcc8d5b6b53ee62246ec8b514513101466c2f3751297583a540fad6ac99b4579ff6d13dbd332080313e3c8fb25df527b55d69a3e1037ce35a0625f98a4
-  data.tar.gz: 2f3c85b15e050142703328aa6ef5b24bfd5c6ca32d386c6c2918dee0d1ee4b1a34092980781195f65ca59bacc095d57df24a85a26a5be5e719fd79d6cb205748
+  metadata.gz: 1bf64792213761b8e5af2f44bf18c90c32c2ceeef36c23082afbc34def70d7059bb36747dc696e7bb4236538f3670dc177c9d2b06de68459d1e80634604e088a
+  data.tar.gz: 3c789100969a47e6d7b29efa75fb1b99b799074b89e8cf276dbdf505bab36adec20e010700366e36fc12063426ca80cacf58db3f17253f3dbc241a6533485104

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

@@ -39,6 +39,8 @@ env:
   # expose a dedicated health endpoint (e.g. "200" for a plain /health, or "200 401 403"
   # for apps that auth-gate / without redirecting).
   HEALTH_CHECK_ACCEPTED_STATUSES: ${{ vars.HEALTH_CHECK_ACCEPTED_STATUSES || '200 301 302' }}
+  COPY_IMAGE_RETRIES: ${{ vars.COPY_IMAGE_RETRIES || '3' }}
+  COPY_IMAGE_RETRY_INTERVAL: ${{ vars.COPY_IMAGE_RETRY_INTERVAL || '20' }}
   ROLLBACK_READINESS_RETRIES: 24
   ROLLBACK_READINESS_INTERVAL: 15
 
@@ -317,14 +319,56 @@ jobs:
       - name: Copy image from staging
         env:
           # Pass the upstream token via env rather than `-t` so it doesn't appear in /proc/<pid>/cmdline.
+          CPLN_TOKEN_STAGING: ${{ secrets.CPLN_TOKEN_STAGING }}
           CPLN_UPSTREAM_TOKEN: ${{ secrets.CPLN_TOKEN_STAGING }}
           PRODUCTION_APP_NAME: ${{ vars.PRODUCTION_APP_NAME }}
+          CPLN_ORG_STAGING: ${{ vars.CPLN_ORG_STAGING }}
           CPLN_ORG_PRODUCTION: ${{ vars.CPLN_ORG_PRODUCTION }}
           STAGING_IMAGE: ${{ steps.staging-image.outputs.image }}
         shell: bash
         run: |
           set -euo pipefail
-          cpflow copy-image-from-upstream -a "${PRODUCTION_APP_NAME}" --org "${CPLN_ORG_PRODUCTION}" --image "${STAGING_IMAGE}"
+
+          if ! [[ "${COPY_IMAGE_RETRIES}" =~ ^[0-9]+$ ]]; then
+            echo "::error::COPY_IMAGE_RETRIES must be a non-negative integer."
+            exit 1
+          fi
+
+          if ! [[ "${COPY_IMAGE_RETRY_INTERVAL}" =~ ^[0-9]+$ ]]; then
+            echo "::error::COPY_IMAGE_RETRY_INTERVAL must be a non-negative integer."
+            exit 1
+          fi
+
+          copy_image_retries=$((10#${COPY_IMAGE_RETRIES}))
+          copy_image_attempts=$((copy_image_retries + 1))
+          copy_image_retry_interval=$((10#${COPY_IMAGE_RETRY_INTERVAL}))
+
+          if ! CPLN_TOKEN="${CPLN_TOKEN_STAGING}" cpln image get "${STAGING_IMAGE}" --org "${CPLN_ORG_STAGING}" -o json >/dev/null; then
+            echo "::error::Staging image '${STAGING_IMAGE}' was not found in org '${CPLN_ORG_STAGING}'; aborting promotion."
+            exit 1
+          fi
+
+          copy_status=1
+          for attempt in $(seq 1 "${copy_image_attempts}"); do
+            if cpflow copy-image-from-upstream -a "${PRODUCTION_APP_NAME}" --org "${CPLN_ORG_PRODUCTION}" --image "${STAGING_IMAGE}"; then
+              copy_status=0
+              break
+            else
+              copy_status=$?
+            fi
+
+            if [[ "${attempt}" -lt "${copy_image_attempts}" ]]; then
+              echo "::warning::Image copy attempt ${attempt}/${copy_image_attempts} failed with exit ${copy_status}; retrying in ${copy_image_retry_interval}s."
+              sleep "${copy_image_retry_interval}"
+            else
+              echo "::warning::Image copy attempt ${attempt}/${copy_image_attempts} failed with exit ${copy_status}; no attempts remain."
+            fi
+          done
+
+          if [[ "${copy_status}" -ne 0 ]]; then
+            echo "::error::Could not copy staging image '${STAGING_IMAGE}' from '${CPLN_ORG_STAGING}' to '${CPLN_ORG_PRODUCTION}' after ${copy_image_attempts} attempt(s)."
+            exit "${copy_status}"
+          fi
 
       - name: Deploy image to production
         env:
@@ -391,19 +435,14 @@ jobs:
               continue
             fi
 
-            if ! rollback_container_entries="$(
-              jq -r \
-                --argjson current_names "${current_names}" \
-                '.[] as $container | ($current_names | index($container.name)) as $index | "\($index)\t\($container.image)"' \
-                <<< "${previous_containers}"
-            )"; then
+            if ! rollback_container_entries="$(jq -r '.[] | "\(.name)\t\(.image)"' <<< "${previous_containers}")"; then
               echo "::warning::Could not build rollback image list for workload '${workload_name}'; skipping rollback for this workload." >&2
               rollback_failures=$((rollback_failures + 1))
               continue
             fi
 
-            while IFS=$'\t' read -r index image; do
-              rollback_args+=(--set "spec.containers[${index}].image=${image}")
+            while IFS=$'\t' read -r container_name image; do
+              rollback_args+=(--set "spec.containers.${container_name}.image=${image}")
             done <<< "${rollback_container_entries}"
 
             if ! cpln workload update "${workload_name}" \

data/CHANGELOG.md

@@ -12,6 +12,18 @@ In addition to the standard keepachangelog.com categories, this project uses a l
 
 ## [Unreleased]
 
+## [5.1.0] - 2026-06-02
+
+### Added
+
+- **Added `shared_secret_grants` configuration so apps can reference org-level Control Plane secrets by name instead of hardcoding them in templates.** [PR 354](https://github.com/shakacode/control-plane-flow/pull/354) by [Justin Gordon](https://github.com/justin808). Each grant validates a unique placeholder, a safe Control Plane resource name, and a secret policy that targets exactly that secret; templates gain `{{SHARED_SECRET_<NAME>}}` substitution, and the shared-policy lifecycle is wired through `setup-app`, `deploy-image`, `delete`, and `cleanup-stale-apps`. Enables the shared staging-database pattern for cheaper review apps.
+
+### Fixed
+
+- **Fixed `cpflow generate-github-actions` so the generated `.github/cpflow-help.md` version-locking example derives a `CPFLOW_VERSION=<major>.<minor>.x` placeholder from the installed gem version instead of a hardcoded release that goes stale against the `@v<version>` wrapper refs in the same file.** [PR 343](https://github.com/shakacode/control-plane-flow/pull/343) by [Justin Gordon](https://github.com/justin808). Fixes [issue 341](https://github.com/shakacode/control-plane-flow/issues/341).
+- **Fixed generated production promotion so `cpflow-promote-staging-to-production.yml` runs as a caller-owned job with `environment: production`, letting GitHub inject the `CPLN_TOKEN_PRODUCTION` environment secret after the protected gate instead of failing because a cross-repo reusable workflow cannot receive caller environment secrets.** [PR 353](https://github.com/shakacode/control-plane-flow/pull/353) by [Justin Gordon](https://github.com/justin808). The job checks out the pinned `control-plane-flow` ref into `.cpflow`, and generated help plus `docs/ci-automation.md` now explain why a same-named repository or organization secret can mask a missing environment secret.
+- **Hardened generated production promotion image copy to preflight the staging image, retry the copy via configurable `COPY_IMAGE_RETRIES` and `COPY_IMAGE_RETRY_INTERVAL` repo vars, and roll back failed deploys using `spec.containers.<name>.image` paths instead of unsupported array-index paths.** [PR 355](https://github.com/shakacode/control-plane-flow/pull/355) by [Justin Gordon](https://github.com/justin808).
+
 ## [5.0.4] - 2026-05-27
 
 ### Fixed
@@ -398,7 +410,8 @@ Deprecated `cpl` gem. New gem is `cpflow`.
 
 First release.
 
-[Unreleased]: https://github.com/shakacode/control-plane-flow/compare/v5.0.4...HEAD
+[Unreleased]: https://github.com/shakacode/control-plane-flow/compare/v5.1.0...HEAD
+[5.1.0]: https://github.com/shakacode/control-plane-flow/compare/v5.0.4...v5.1.0
 [5.0.4]: https://github.com/shakacode/control-plane-flow/compare/v5.0.3...v5.0.4
 [5.0.3]: https://github.com/shakacode/control-plane-flow/compare/v5.0.2...v5.0.3
 [5.0.2]: https://github.com/shakacode/control-plane-flow/compare/v5.0.1...v5.0.2

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cpflow (5.0.4)
+    cpflow (5.1.0)
       dotenv (~> 3.1)
       jwt (~> 3.1)
       psych (~> 5.2)

data/README.md

@@ -241,6 +241,18 @@ aliases:
     #   it would be 'my-app-review-secrets-policy'
     secrets_policy_name: my-secrets-policy
 
+    # Optional: grant each app identity access to shared org-level secrets
+    # without hardcoding shared secret names in workload templates.
+    #
+    # This is useful for review apps that share one staging database secret
+    # instead of provisioning a database per PR. Create the shared secret and
+    # policy once, then reference the secret in templates with
+    # {{SHARED_SECRET_DATABASE}}.
+    # shared_secret_grants:
+    #   - name: database
+    #     secret_name: my-shared-database-secrets
+    #     policy_name: my-shared-database-secrets-policy
+
     # Configure the workload name used as a template for one-off scripts, like a Heroku one-off dyno.
     one_off_workload: rails
 
@@ -500,6 +512,11 @@ aws-rds-single-pg-instance
   mydb-review-333
 ```
 
+For production, you'll typically want RDS or Aurora in private subnets, reached from your Control Plane workloads
+over a private network path rather than the public internet. See
+[Connecting Control Plane workloads to a private AWS RDS/Aurora database](./docs/rds-private-networking.md) for the
+full Cloud Wormhole + Agent setup.
+
 If you want to run PostgreSQL on Control Plane instead of keeping a Heroku add-on or moving to RDS, review the
 [Control Plane PostgreSQL Template Catalog page](https://shakadocs.controlplane.com/template-catalog/templates/postgres). It includes
 persistent storage and optional scheduled backups. Additionally, we provide a default `postgres` template in this
@@ -565,17 +582,21 @@ cpflow --help
 
 ## Mapping of Heroku Commands to `cpflow` and `cpln`
 
-| Heroku Command                                                                                                 | `cpflow` or `cpln`                 |
-| -------------------------------------------------------------------------------------------------------------- | ------------------------------- |
-| [heroku ps](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-ps-type-type)                     | `cpflow ps`                        |
-| [heroku config](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-config)                       | ?                               |
-| [heroku maintenance](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-maintenance)             | `cpflow maintenance`               |
-| [heroku logs](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-logs)                           | `cpflow logs`                      |
-| [heroku pg](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-pg-database)                      | ?                               |
-| [heroku pipelines:promote](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-pipelines-promote) | `cpflow promote-app-from-upstream` |
-| [heroku psql](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-psql-database)                  | ?                               |
-| [heroku redis](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-redis-database)                | ?                               |
-| [heroku releases](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-releases)                   | ?                               |
+| Heroku Command                                                                                                 | `cpflow` or `cpln`                                                                                                                                                                    |
+| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [heroku ps](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-ps-type-type)                     | `cpflow ps`                                                                                                                                                                           |
+| [heroku config](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-config)                       | `cpflow env -a APP_NAME` displays Control Plane app environment variables; `cpflow config -a APP_NAME` displays local `.controlplane/controlplane.yml` settings                     |
+| [heroku maintenance](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-maintenance)             | `cpflow maintenance`, `cpflow maintenance:on`, `cpflow maintenance:off`, and `cpflow maintenance:set-page`                                                                            |
+| [heroku logs](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-logs)                           | `cpflow logs -a APP_NAME`; add `-w WORKLOAD_NAME` to filter by workload, or `-w WORKLOAD_NAME -r REPLICA_NAME` to narrow to a specific replica                                        |
+| [heroku pg](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-pg-database)                      | No direct `cpflow` add-on wrapper. Use an external Postgres provider, the Control Plane Template Catalog, or project templates such as `.controlplane/templates/postgres.yml`.        |
+| [heroku pipelines:promote](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-pipelines-promote) | `cpflow promote-app-from-upstream`                                                                                                                                                    |
+| [heroku psql](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-psql-database)                  | No direct `cpflow` equivalent. Connect with your provider's `psql` flow, or run `cpflow run -a APP_NAME -- psql "$DATABASE_URL"` when `psql` is available in the application image. |
+| [heroku redis](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-redis-database)                | No direct `cpflow` add-on wrapper. Use an external Redis provider, the Control Plane Template Catalog, or project templates such as `.controlplane/templates/redis.yml`.              |
+| [heroku releases](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-releases)                   | `cpflow latest-image -a APP_NAME` for the latest image tag; `cpflow deploy-image -a APP_NAME` deploys that image. No `cpflow` equivalent for browsing full release history.          |
+
+Unlike Heroku add-ons, Control Plane database and cache services are usually managed as provider resources or workload
+templates. `cpflow` focuses on the application deployment flow and leaves provider-specific database administration to
+the provider tooling, Control Plane templates, or direct `cpln` operations.
 
 ## Examples
 

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

@@ -20,7 +20,7 @@ prompt tells the agent to stop on.
 ```text
 Set up Control Plane GitHub Flow for this repo. Start with `cpflow github-flow-readiness` and stop on any reported blockers. The repo must be deployable from a clean clone: 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 standard path simple: review apps require only `CPLN_TOKEN_STAGING` when the generated review app config can be inferred. 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: 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 standard path simple: review apps require only `CPLN_TOKEN_STAGING` when the generated review app config can be inferred. 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/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 thin `cpflow-*` workflow wrappers that call upstream reusable workflows.
+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.
 5. Push the branch, then comment `+review-app-deploy` on a PR to spin up a review environment.
 
@@ -197,22 +197,37 @@ For production promotion, also configure:
 - `PRODUCTION_APP_NAME` as a production environment variable, for example `my-app-production`
 
 Do not put `CPLN_TOKEN_PRODUCTION` in repository or organization secrets for
-sensitive production systems. The generated promotion reusable workflow declares
-`environment: production`; the generated caller passes that environment name
-through `production_environment`. GitHub waits for the `production`
-environment's protection rules before injecting `CPLN_TOKEN_PRODUCTION` into
-the upstream production job.
-
-GitHub's reusable-workflow syntax still requires the upstream workflow to
-declare `CPLN_TOKEN_PRODUCTION` as an optional `workflow_call` secret so static
-validation accepts `secrets.CPLN_TOKEN_PRODUCTION`, but the generated caller
-must not pass it. GitHub uses the secret from the reusable workflow job's
-`production` environment when that environment is configured.
-
-Generated caller workflows pass only the named secrets each reusable workflow
-needs. They do not use `secrets: inherit`; the production token is supplied by
-the protected `production` Environment after approval, not forwarded from a
-repository secret.
+sensitive production systems. Production promotion intentionally runs as a
+normal caller-repo workflow job with `environment: production`, then checks out
+the pinned `control-plane-flow` release for shared actions. GitHub exposes the
+production token to that job only after the `production` environment gate.
+GitHub does not expose which secret scope supplied a nonempty value at runtime,
+so a broader repository or organization secret with the same name can mask a
+missing environment secret. Keep the production token absent from broader secret
+scopes.
+
+Do not move production promotion behind a cross-repo reusable workflow. GitHub
+does not expose the caller repository's environment secrets to that called
+workflow, so `secrets.CPLN_TOKEN_PRODUCTION` remains empty even when the
+`production` Environment contains the secret. Generated reusable-workflow
+callers still pass only the named secrets each upstream workflow needs and do
+not use `secrets: inherit`; production promotion is the caller-owned exception.
+
+If promotion fails in the `Validate production token` step with
+`CPLN_TOKEN_PRODUCTION is not set. Add it as a secret on the 'production' GitHub Environment.`,
+check the environment scope first. Also verify that the `promote-to-production`
+job declares `environment: production` and that no same-named repository or
+organization secret exists. Create or verify the environment secret with:
+You need permission to manage repository environments and secrets to run these
+commands.
+
+```sh
+gh secret set CPLN_TOKEN_PRODUCTION --repo OWNER/REPO --env production
+# Paste the token value when prompted.
+gh secret list --repo OWNER/REPO --env production
+gh secret list --repo OWNER/REPO
+gh secret list --org OWNER | grep '^CPLN_TOKEN_PRODUCTION[[:space:]]' || true
+```
 
 ## First-Time Control Plane Bootstrap
 
@@ -264,6 +279,28 @@ templates, and the staging token must have access to create and update
 review-app GVCs, workloads, images, identities, policies, and secrets in the
 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.
+
+```yaml
+apps:
+  my-app-review:
+    match_if_app_name_starts_with: true
+    shared_secret_grants:
+      - name: database
+        secret_name: my-app-review-database-secrets
+        policy_name: my-app-review-database-secrets-policy
+```
+
+Then reference `cpln://secret/{{SHARED_SECRET_DATABASE}}.DATABASE_URL` from the
+workload template.
+
 ### Production Promotion Safety
 
 `CPLN_TOKEN_PRODUCTION` can change live production workloads, images, releases,
@@ -281,10 +318,12 @@ The standard path is:
    intentionally non-sensitive.
 
 GitHub only exposes environment secrets to jobs that reference the environment
-after configured protection rules pass. GitHub also does not allow a caller job
-that directly invokes a reusable workflow to set `environment`; for that reason,
-the reusable promotion workflow itself declares `environment: production`. See
-GitHub's docs for [managing environments](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments),
+after configured protection rules pass. GitHub does not allow a caller job that
+directly invokes a reusable workflow to set `environment`, and cross-repo
+reusable workflows do not receive the caller repository's environment secrets.
+For that reason, generated production promotion stays as a normal caller-repo
+job with `environment: production`. See GitHub's docs for
+[managing environments](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments),
 [deployment protection rules](https://docs.github.com/en/actions/reference/workflows-and-actions/deployments-and-environments),
 and [reusable workflow limitations](https://docs.github.com/en/actions/reference/reusable-workflows-reference#supported-keywords-for-jobs-that-call-a-reusable-workflow).
 
@@ -405,32 +444,37 @@ or clones that copy the workflow before configuring Control Plane can remove
 wrapper-level `if:` guard shown in that file, for example
 `vars.REVIEW_APP_PREFIX != '' || vars.CPLN_ORG_STAGING != ''`.
 
-## Upstream Reusable Workflows
+## Upstream Workflows And 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.
+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.
 
-- `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-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
 - `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:
+Generated `cpflow-*` workflow files pin `shakacode/control-plane-flow` from
+GitHub, not from the Ruby gem. Reusable workflow wrappers pin that source with
+an upstream `uses:` ref:
 
 ```yaml
 uses: shakacode/control-plane-flow/.github/workflows/cpflow-deploy-review-app.yml@<ref>
 ```
 
-That single `uses:` ref is the downstream lock. GitHub exposes the reusable
-workflow's own repository, ref, and SHA to the called job, so the upstream
-workflow checks out the matching `control-plane-flow` source automatically from
-that context. Downstream wrappers should not pass `control_plane_flow_ref`; if
-you see that input in generated wrappers, regenerate with a newer `cpflow`.
+Production promotion pins the same source in its `Checkout control-plane-flow
+actions` step because it is a caller-owned job, not a reusable workflow caller.
+Those refs are the downstream lock. GitHub exposes a reusable workflow's own
+repository, ref, and SHA to called jobs, so reusable upstream workflows check out
+matching `control-plane-flow` source automatically from that context. Downstream
+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:
 
@@ -528,10 +572,12 @@ releasing it. Use an immutable commit SHA from the upstream PR branch:
    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.
+   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
@@ -566,9 +612,10 @@ releasing it. Use an immutable commit SHA from the upstream PR branch:
    `bin/pin-cpflow-github-ref vX.Y.Z` only for a ref-only update when the
    generated templates are already current.
 
-This tests the real reusable workflow, shared composite actions, and source-built
-`cpflow` gem from one immutable upstream commit. It avoids merging upstream blind
-and avoids running production automation against a moving branch.
+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.
 
 ## Local Generated-Flow Checks
 
@@ -580,9 +627,11 @@ 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, rejects
-broad `secrets: inherit` usage in generated cpflow wrappers, rejects obsolete
-`control_plane_flow_ref` wrapper inputs, and runs
+checks that all generated wrappers and the production `control-plane-flow`
+checkout use one upstream ref consistently, rejects broad `secrets: inherit`
+usage in generated cpflow wrappers, rejects obsolete `control_plane_flow_ref`
+wrapper inputs, verifies production promotion remains a caller-owned
+`environment: production` job, and runs
 `actionlint` against `.github/workflows/cpflow-*.yml`. Its `actionlint` command
 keeps the existing shellcheck ignore and also ignores stale local `actionlint`
 false positives for GitHub's newer reusable-workflow `job.workflow_*` fields.

data/docs/commands.md

@@ -41,6 +41,9 @@ cpflow ai-github-flow-prompt
 {{APP_IMAGE_LINK}}    - full link for latest app image, ready to be used for the value of `containers[].image` in the templates
 {{APP_IDENTITY}}      - default identity
 {{APP_IDENTITY_LINK}} - full link for identity, ready to be used for the value of `identityLink` in the templates
+{{APP_SECRETS}}       - app secret dictionary name
+{{APP_SECRETS_POLICY}} - app secret policy name
+{{SHARED_SECRET_<NAME>}} - shared secret dictionary name from `shared_secret_grants`
 ```
 
 ```sh
@@ -79,7 +82,7 @@ cpflow cleanup-images -a $APP_NAME
 ### `cleanup-stale-apps`
 
 - 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=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`
 - `--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
@@ -128,7 +131,8 @@ cpflow copy-image-from-upstream -a $APP_NAME --upstream-token $UPSTREAM_TOKEN --
 ### `delete`
 
 - Deletes the whole app (GVC with all workloads, all volumesets and all images) or a specific workload
-- Also unbinds the app from the secrets policy, as long as both the identity and the policy exist (and are bound)
+- Also 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)
+- For the app-specific secrets policy, removes every permission held by the app identity; for `shared_secret_grants`, removes only `reveal`
 - Will ask for explicit user confirmation
 - Runs a pre-deletion hook before the app is deleted if `hooks.pre_deletion` 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
@@ -149,6 +153,7 @@ cpflow delete -a $APP_NAME -w $WORKLOAD_NAME
 - 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
 - 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
+- Repairs missing `shared_secret_grants` policy bindings before running a release phase or updating workloads
 
 ```sh
 cpflow deploy-image -a $APP_NAME
@@ -513,6 +518,7 @@ cpflow run -a $APP_NAME --entrypoint /app/alternative-entrypoint.sh -- rails db:
 - Configures app to have org-level secrets with default name `"{APP_PREFIX}-secrets"`
   using org-level policy with default name `"{APP_PREFIX}-secrets-policy"` (names can be customized, see docs)
 - Creates identity for secrets if it does not exist
+- Binds the app identity to any configured `shared_secret_grants` policies as part of the secrets setup flow; skipped when `--skip-secrets-setup` or `--skip-secret-access-binding` is provided, or `skip_secrets_setup` is set
 - Use `--skip-secrets-setup` to prevent the automatic setup of secrets,
   or set it through `skip_secrets_setup` in the `.controlplane/controlplane.yml` file
 - Runs a post-creation hook after the app is created if `hooks.post_creation` is specified in the `.controlplane/controlplane.yml` file
@@ -544,7 +550,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.0.3`.
+release tag, for example `v5.0.4`.
 
 If the existing generated staging workflow uses a custom single staging
 branch, the command preserves it. Pass `--staging-branch BRANCH` to set or

data/docs/postgres.md

@@ -1,5 +1,11 @@
 # Migrating Postgres database from Heroku infrastructure
 
+> **Networking note.** This guide is written against a *publicly reachable* RDS instance for simplicity of the
+> Bucardo migration steps. For production, you almost certainly want RDS/Aurora in private subnets reached from
+> Control Plane workloads via the Cloud Wormhole agent — see
+> [Connecting Control Plane workloads to a private AWS RDS/Aurora database](./rds-private-networking.md). The
+> Bucardo migration here still works against a private RDS once the network path is set up.
+
 If you are replacing Heroku Postgres or another pre-provisioned database service, also review the
 [Control Plane PostgreSQL Template Catalog page](https://shakadocs.controlplane.com/template-catalog/templates/postgres). The
 catalog template covers a single-instance PostgreSQL workload with persistent storage, optional PgBouncer, and optional