cpflow 5.0.4 → 5.1.0

data/docs/secrets-and-env-values.md

@@ -29,6 +29,55 @@ You can do this during the initial app setup, like this:
 6. Find the created secret (it will be in the `$APP_PREFIX-secrets` format) and add the secret env vars there
 7. Use `cpln://secret/...` in the app to access the secret env vars (e.g., `cpln://secret/$APP_PREFIX-secrets.SOME_VAR`)
 
+## Shared Secrets for Review Apps
+
+Review apps often need access to a shared staging resource, such as one staging PostgreSQL workload or managed database.
+Creating a database per pull request is expensive and slow, so you can create one shared org-level secret and policy,
+then let each temporary review-app identity reveal that shared secret.
+
+Create the shared dictionary secret and policy once in the staging org. The policy must target exactly the shared secret:
+
+```yaml
+kind: policy
+name: my-app-review-database-secrets-policy
+targetKind: secret
+targetLinks:
+  - //secret/my-app-review-database-secrets
+```
+
+Then declare the grant in the review app entry in `.controlplane/controlplane.yml`:
+
+```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
+```
+
+Use the generated placeholder in templates instead of hardcoding the secret name:
+
+```yaml
+env:
+  - name: DATABASE_URL
+    value: cpln://secret/{{SHARED_SECRET_DATABASE}}.DATABASE_URL
+```
+
+`name` must be lower snake case. It becomes `{{SHARED_SECRET_<NAME>}}`, uppercased, in templates. `secret_name`
+and `policy_name` must be Control Plane resource names: lowercase letters, numbers, and dashes only, starting and ending
+with a letter or number.
+
+`cpflow setup-app` still creates the per-app secret and policy for app-specific values, and also binds the app identity
+to every configured shared policy. `cpflow deploy-image` repairs missing shared policy bindings before workloads are
+updated, which helps existing review apps recover after the config is added. `cpflow delete` and `cpflow cleanup-stale-apps`
+remove those shared policy bindings when a review app is deleted.
+
+For shared databases, keep runtime data isolated by using a per-review-app database name, schema, or tenant key. A common
+pattern is to keep the host, user, and password in the shared secret, then have `hooks.post_creation` create the PR-specific
+database/schema and `hooks.pre_deletion` drop it.
+
 Here are the manual steps for reference. We recommend that you follow the steps above:
 
 1. In the upper left of the Control Plane console, "Manage Org" menu, click on "Secrets"

data/docs/tips.md

@@ -1,16 +1,23 @@
 # Tips
 
 1. [GVCs vs. Orgs](#gvcs-vs-orgs)
-2. [RAM](#ram)
-3. [Remote IP](#remote-ip)
-4. [Secrets and ENV Values](/docs/secrets-and-env-values.md)
-5. [CI](#ci)
-6. [Memcached](#memcached)
-7. [Sidekiq](#sidekiq)
-   - [Quieting Non-Critical Workers During Deployments](#quieting-non-critical-workers-during-deployments)
-   - [Setting Up a Pre Stop Hook](#setting-up-a-pre-stop-hook)
-   - [Setting Up a Liveness Probe](#setting-up-a-liveness-probe)
-8. [Useful Links](#useful-links)
+2. [Heroku Mappings](#heroku-mappings)
+3. [RAM](#ram)
+4. [CPU](#cpu)
+5. [Remote IP](#remote-ip)
+6. [Secrets and ENV Values](/docs/secrets-and-env-values.md)
+7. [CI](#ci)
+8. [Logs](#logs)
+9. [Memcached](#memcached)
+10. [Sidekiq](#sidekiq)
+    - [Quieting Non-Critical Workers During Deployments](#quieting-non-critical-workers-during-deployments)
+    - [Setting Up a Pre Stop Hook](#setting-up-a-pre-stop-hook)
+    - [Setting Up a Liveness Probe](#setting-up-a-liveness-probe)
+11. [Minimizing Review App Costs](#minimizing-review-app-costs)
+    - [Scale the Web Workload to Zero](#scale-the-web-workload-to-zero)
+    - [Delete or Pause Abandoned Apps with `cleanup-stale-apps`](#delete-or-pause-abandoned-apps-with-cleanup-stale-apps)
+    - [Pause and Resume with `ps:stop` / `ps:start`](#pause-and-resume-with-psstop--psstart)
+12. [Useful Links](#useful-links)
 
 ## GVCs vs. Orgs
 
@@ -20,6 +27,23 @@
 - You can have different images within a GVC and even within a workload. This flexibility is one of the key differences
   compared to Heroku apps.
 
+## Heroku Mappings
+
+If you're coming from Heroku, these concepts map roughly as follows:
+
+| Heroku           | Control Plane                       |
+| ---------------- | ----------------------------------- |
+| App              | GVC                                 |
+| Dyno             | Replica                             |
+| Procfile Process | Workload                            |
+| Config Var       | Secret / Environment Variable       |
+| Add-on           | Managed Service or External Service |
+| Release Phase    | Deployment Workflow                 |
+
+These are conceptual equivalents rather than exact matches — see [GVCs vs. Orgs](#gvcs-vs-orgs) above for one key
+difference. For a mapping of Heroku _CLI commands_ to `cpflow`/`cpln`, see
+[Mapping of Heroku Commands](/README.md#mapping-of-heroku-commands-to-cpflow-and-cpln).
+
 ## RAM
 
 Any workload replica that reaches the max memory is terminated and restarted. You can configure alerts for workload
@@ -59,6 +83,23 @@ The steps for configuring an alert for workload restarts are almost identical, b
 
 For more information on Grafana alerts, see: https://grafana.com/docs/grafana/latest/alerting/
 
+## CPU
+
+Control Plane workloads can be configured with CPU reservations and limits. If a workload consistently operates near its
+CPU limit, request latency may increase. If CPU is configured as the workload's autoscaling metric (with `maxScale`
+greater than `minScale`), Control Plane will add replicas in response — but the default `templates/rails.yml` pins
+`minScale: 1`, `maxScale: 1`, so it holds a single replica until you configure autoscaling.
+
+Worth monitoring:
+
+- CPU utilization
+- Request latency
+- Replica count
+- Container restarts
+
+Consider configuring an alert for sustained CPU utilization above 80%. You can set this up with the same Grafana
+alerting steps described under [RAM](#ram) above, substituting a CPU utilization query for the memory one.
+
 ## Remote IP
 
 The actual remote IP of the workload container is in the 127.0.0.x network, so that will be the value of the
@@ -70,6 +111,9 @@ pick those up and automatically populate `request.remote_ip`.
 
 So `REMOTE_ADDR` should not be used directly, only `request.remote_ip`.
 
+> **Warning:** Do not use `REMOTE_ADDR` for authentication, rate limiting, auditing, or IP allowlists. Always use
+> framework-specific mechanisms that understand proxy headers (such as Rails' `request.remote_ip`).
+
 ## CI
 
 **Note:** Docker builds much slower on Apple Silicon, so try configuring CI to build the images when using Apple
@@ -82,17 +126,92 @@ CPLN_TOKEN=...
 cpln profile create default --token ${CPLN_TOKEN}
 ```
 
+The `CPLN_TOKEN=...` line above is illustrative. In CI, don't write the literal token into your workflow file — store it
+in your provider's secret store and let CI inject it as the `CPLN_TOKEN` environment variable, which
+`cpln profile create ... --token ${CPLN_TOKEN}` then reads. See [`examples/circleci.yml`](/examples/circleci.yml) for the
+recommended pattern.
+
 Also, log in to the Control Plane Docker repository if building and pushing an image.
 
 ```sh
 cpln image docker-login
 ```
 
+## Logs
+
+`cpflow logs` is a lightweight live-tail command. When you hit `cpln`/`cpflow` line-count or response-size limits, use
+Grafana Loki's [`logcli`](https://grafana.com/docs/loki/latest/query/logcli/) directly against the Control Plane logs
+endpoint for larger historical exports.
+
+Install `logcli` with Homebrew when available:
+
+```sh
+brew install logcli
+```
+
+If Homebrew reports that the formula is unavailable, use Grafana's tap:
+
+```sh
+brew tap grafana/grafana
+brew install grafana/grafana/logcli
+```
+
+For Linux, CI, or other environments without Homebrew, see the [`logcli` installation
+docs](https://grafana.com/docs/loki/latest/query/logcli/getting-started/#install-logcli) for binary downloads or source
+builds.
+
+Configure it with your Control Plane org and current profile token:
+
+```sh
+export LOKI_ADDR=https://logs.cpln.io/logs/org/YOUR_ORG  # run `cpln org get` to find your org name
+export LOKI_BEARER_TOKEN=$(cpln profile token)
+```
+
+`LOKI_BEARER_TOKEN` is a short-lived bearer credential (it typically expires after roughly 15–60 minutes). The
+`$(cpln profile token)` capture above keeps the literal token out of shell history, but any later command that prints
+it (`echo $LOKI_BEARER_TOKEN`, `env | grep LOKI`) will expose it; avoid those, don't commit the value to scripts, and
+watch for it in CI logs. Rerun the token export if `logcli` returns a 401 or another authentication error.
+
+Then query logs by label. A Control Plane app is a GVC, so set `gvc` to the app name and narrow by workload or other
+labels as needed. The `--forward` flag returns results oldest-first (chronological), which is almost always what you
+want for incident investigation or sequential reading; omit it to get the `logcli` default of newest-first:
+
+```sh
+logcli query '{gvc="my-app", workload="rails"}' --since 1h --limit 10000 --forward
+```
+
+For cleaner bulk exports, strip label metadata from each output line and redirect the output:
+
+```sh
+logcli query '{gvc="my-app", workload="rails"}' --since 24h --limit 50000 --no-labels --forward > rails.log
+```
+
+For historical incidents, use absolute UTC timestamps instead of a relative `--since` window:
+
+```sh
+logcli query '{gvc="my-app"}' \
+  --from="2026-05-27T00:00:00Z" \
+  --to="2026-05-27T06:00:00Z" \
+  --limit 50000 \
+  --no-labels \
+  --forward > incident.log
+```
+
+`logcli` silently truncates results once `--limit` is reached, so a partial export looks the same as a complete one.
+To check for truncation, compare line count to the limit: `wc -l < incident.log` near `--limit` means the export was
+likely cut off. Prefer narrowing the time window (and concatenating the sub-ranges) over raising `--limit`, since the
+server-side cap may be lower than the flag value.
+
 ## Memcached
 
 On the workload container for Memcached (using the `memcached:alpine` image), configure the command with the args
 `-l 0.0.0.0`.
 
+This makes Memcached listen on all network interfaces so other workloads in the GVC can reach it at
+`memcached.APP_GVC.cpln.local`. The `memcached` image already defaults to all interfaces, but passing `-l 0.0.0.0`
+explicitly keeps the intent clear and guards against the listen address being restricted by a future base-image or
+config change.
+
 To do this:
 
 1. Navigate to the workload container for Memcached
@@ -114,6 +233,9 @@ There's no need to unquiet the workers, as that will happen automatically after
 cpflow run 'rails runner "Sidekiq::ProcessSet.new.each { |w| w.quiet! unless w[%q(hostname)].start_with?(%q(criticalworker.)) }"' -a my-app
 ```
 
+> **Note:** This assumes critical workers share a consistent hostname prefix (the check matches `hostname`, not
+> Sidekiq's `tag` attribute). If you use a custom naming convention, adjust the `start_with?` check accordingly.
+
 ### Setting Up a Pre Stop Hook
 
 By setting up a pre stop hook in the lifecycle of the workload container for Sidekiq, which sends "QUIET" to the workers,
@@ -144,6 +266,130 @@ To do this:
 
 To set up a liveness probe on port 7433, see: https://github.com/arturictus/sidekiq_alive
 
+## Minimizing Review App Costs
+
+Long-tail review apps — PRs that linger for days or weeks with little traffic — can drive up Control Plane spend if every
+workload runs full-time. `cpflow` already provides several knobs to manage this without custom orchestration.
+
+> **Note:** Scaling workloads to zero or stopping review apps does not reduce costs from external databases, managed
+> Redis instances, object storage, or other third-party services. Those continue to bill independently of Control Plane
+> workload state.
+
+### Scale the Web Workload to Zero
+
+`templates/rails.yml` ships with `type: standard`, `minScale: 1`, `maxScale: 1`. That's a safe default for production,
+but for review apps where cold-start latency is acceptable you can switch the web workload to a serverless type that
+scales to zero replicas when idle. Apply the snippet below to your project's `.controlplane/templates/rails.yml`, or
+create a review-app-specific template (for example `rails-review.yml`) and list it under `setup_app_templates` for the
+review-app entry in `.controlplane/controlplane.yml`.
+
+```yaml
+# Only `type` and `minScale` change from templates/rails.yml; `maxScale`, `capacityAI` and `timeoutSeconds`
+# are shown for context so the full `defaultOptions` block reaches the destination intact.
+# Update the relevant fields in your full templates/rails.yml (or a review-app-specific template); keep
+# containers, firewallConfig, identityLink, and everything else from that file intact.
+kind: workload
+name: rails
+spec:
+  type: serverless
+  defaultOptions:
+    autoscaling:
+      minScale: 0
+      maxScale: 1
+    capacityAI: false    # keep your existing value
+    timeoutSeconds: 60   # keep your existing value
+```
+
+See [`templates/rails.yml`](/templates/rails.yml) for the full default — `containers`, `firewallConfig`,
+`identityLink`, and the other required fields must be preserved when you copy the snippet above.
+
+Control Plane spins the workload back up on the next request. Only `type: serverless` workloads support `minScale: 0`;
+`type: standard` always keeps at least one replica running.
+
+Tradeoff: the first request after a quiet period pays the cold-start cost (typically 15–60 seconds for a Rails
+image, depending on app size and boot configuration). For review apps that's usually fine; for production it
+usually isn't.
+
+> **Note:** if you later suspend the app with `cpflow ps:stop`, Control Plane will not auto-wake it on the next
+> request. Run `cpflow ps:start` explicitly first. See
+> [Pause and Resume](#pause-and-resume-with-psstop--psstart).
+
+### Delete or Pause Abandoned Apps with `cleanup-stale-apps`
+
+For PRs that are clearly done — merged, closed, or untouched for weeks — deleting beats scaling. Set
+`stale_app_image_deployed_days` in `.controlplane/controlplane.yml`:
+
+```yaml
+my-app-review:
+  match_if_app_name_starts_with: true
+  stale_app_image_deployed_days: 14
+```
+
+Pick a threshold that fits your review cycle — 7 days can catch PRs still in QA; teams with longer review cycles often
+use 14–30 days.
+
+> **How staleness is measured:** `stale_app_image_deployed_days` uses the Control Plane image resource's `created`
+> timestamp, typically when the image was pushed to Control Plane's registry. If no matching image exists, it falls back
+> to the GVC's `created` timestamp. It does not consider last traffic or last PR comment.
+> The same stale-app scan applies to both delete and stop modes below.
+
+Then run in delete mode:
+
+```sh
+cpflow cleanup-stale-apps -a my-app-review --yes
+```
+
+The `--yes` flag skips the interactive confirmation prompt; keep it for CI jobs, or omit it when running manually and
+you want to review the prompt. Because `match_if_app_name_starts_with: true` is set, `-a my-app-review` here matches
+every app whose name starts with that prefix — by contrast, the `cpflow ps:stop -a my-app-review-123` examples below
+target a single concrete app name.
+
+This deletes the GVC, workloads, volumesets, and images for any review app whose latest matching image, or GVC when no
+matching image exists, is older than the threshold. It also unbinds the app identity from the secrets policy and any
+configured `shared_secret_grants` policies when those bindings exist. Wire it into a nightly CI cron — see
+[CI Automation — Generated Workflow Behavior](/docs/ci-automation.md#generated-workflow-behavior) for the
+`cpflow-cleanup-stale-review-apps.yml` workflow, which runs in delete mode by default; customize the workflow
+to pass `--mode=stop` if you prefer reversible pausing in CI.
+
+For reversible idle handling under the same stale-app scan, use stop mode instead:
+
+```sh
+cpflow cleanup-stale-apps -a my-app-review --mode=stop --yes
+```
+
+This uses the same staleness threshold, but runs `cpflow ps:stop` for each stale app instead of deleting the GVC,
+volumesets, or images. Resume an app later with `cpflow ps:start -a $APP_NAME`. `cpflow ps:stop` only suspends
+workloads listed under `app_workloads` / `additional_workloads` in `.controlplane/controlplane.yml`; workloads
+created outside that config (for example through the Control Plane UI) are left alone — see
+[Pause and Resume](#pause-and-resume-with-psstop--psstart) for details.
+
+### Pause and Resume with `ps:stop` / `ps:start`
+
+For review apps you want to keep but pause — for example, a long-running QA branch a tester will come back to — suspend
+all workloads with:
+
+```sh
+cpflow ps:stop -a my-app-review-123
+```
+
+This sets `defaultOptions.suspend: true` on every workload listed under `app_workloads` or `additional_workloads` in
+`.controlplane/controlplane.yml`. Workloads created outside that config (for example through the Control Plane UI) are
+left alone. Resume with:
+
+```sh
+cpflow ps:start -a my-app-review-123
+```
+
+No re-deploy is needed; the workloads come back with the same images they had before.
+
+> **Note:** `ps:stop` overrides serverless auto-wake. If the web workload is already serverless (`minScale: 0`),
+> suspending it sets `defaultOptions.suspend: true`, and Control Plane will not bring it back on the next request —
+> `ps:start` must be run explicitly first.
+>
+> **Note:** Sidekiq, Postgres, Redis, and Memcached templates default to `type: standard` and `minScale: 1`, so they
+> keep running while only the web tier sleeps. `cpflow ps:stop -a $APP_NAME` suspends every configured workload, web
+> included, and `cleanup-stale-apps --mode=stop` applies the same pause behavior to stale review apps.
+
 ## Useful Links
 
 - For best practices for the app's Dockerfile, see: https://lipanski.com/posts/dockerfile-ruby-best-practices

data/examples/controlplane.yml

@@ -58,6 +58,14 @@ aliases:
     #   it would be 'my-app-review-secrets-policy'
     secrets_policy_name: my-secrets-policy
 
+    # Optional: grant every app identity from this config entry access to
+    # existing shared org-level secret policies. Templates can reference the
+    # shared secret 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
 

data/lib/command/ai_github_flow_prompt.rb

@@ -32,7 +32,7 @@ module Command
       <<~PROMPT
         Set up Control Plane GitHub Flow for this repo. Start with `cpflow github-flow-readiness` and stop on any reported blockers. The repo must be deployable from a clean clone: published package versions, complete runtime scaffold, and a production Dockerfile that can build the app. If any package version is unpublished, inaccessible from CI, or requires credentials that are not already modeled in the repo or GitHub settings, stop and report the blocker instead of generating workflow files. If the repo is a legacy sample pinned to an obsolete Ruby or Bundler toolchain, if it does not even have a production Dockerfile yet, or if it is a monorepo without an already-decided single app boundary for this flow, stop and report that as a prerequisite instead of forcing the rollout.
 
-        If `.controlplane/` is missing, run `cpflow generate`. Treat the generated app names as the repo-name default (`#{inferred_app_prefix}`) and rename them only if the project needs a different prefix. Then run `cpflow generate-github-actions` (or `cpflow generate-github-actions --staging-branch BRANCH` when staging should deploy from a branch other than `main`/`master`), keep review apps opt-in via `+review-app-deploy`, make sure any `STAGING_APP_BRANCH` repository variable is also present in the generated staging workflow's `on.push.branches` filter, and list the GitHub secrets and variables that must be configured. 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 (`#{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 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/lib/command/apply_template.rb

@@ -29,6 +29,9 @@ module Command
       {{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`
       ```
     DESC
     EXAMPLES = <<~EX

data/lib/command/base.rb

@@ -587,6 +587,75 @@ module Command
       @cp ||= Controlplane.new(config)
     end
 
+    def bind_shared_secret_policy_grants(grant_policy_pairs)
+      grant_policy_pairs.each do |grant, policy|
+        bind_shared_secret_policy_grant(grant, policy)
+      end
+    end
+
+    def resolve_shared_secret_policy_grants
+      config.shared_secret_grants.map do |grant|
+        [grant, resolve_shared_secret_policy_grant(grant)]
+      end
+    end
+
+    def resolve_shared_secret_policy_grant(grant)
+      policy = cp.fetch_policy(grant.fetch(:policy_name))
+      raise shared_secret_policy_missing_message(grant) if policy.nil?
+
+      ensure_shared_secret_policy_targets_secret!(grant, policy)
+      policy
+    end
+
+    def bind_shared_secret_policy_grant(grant, policy)
+      policy_name = grant.fetch(:policy_name)
+      return if identity_bound_to_policy_with_reveal?(policy)
+
+      step("Binding identity '#{config.identity}' to shared secret policy '#{policy_name}'") do
+        cp.bind_identity_to_policy(config.identity_link, policy_name)
+      end
+    end
+
+    def ensure_shared_secret_policy_targets_secret!(grant, policy)
+      return if shared_secret_policy_targets_secret?(grant, policy)
+
+      raise "Shared secret policy '#{grant.fetch(:policy_name)}' for shared_secret_grants entry " \
+            "'#{grant.fetch(:name)}' must target only secret '#{grant.fetch(:secret_name)}'."
+    end
+
+    def shared_secret_policy_targets_secret?(grant, policy)
+      target_links = Array(policy["targetLinks"])
+
+      policy["targetKind"] == "secret" &&
+        target_links.one? &&
+        shared_secret_policy_target_links(grant).include?(target_links.first)
+    end
+
+    def shared_secret_policy_target_links(grant)
+      secret_name = grant.fetch(:secret_name)
+      [
+        "//secret/#{secret_name}",
+        "/org/#{config.org}/secret/#{secret_name}"
+      ]
+    end
+
+    def identity_bound_to_policy_with_reveal?(policy)
+      identity_policy_permissions(policy).include?("reveal")
+    end
+
+    def identity_policy_permissions(policy)
+      Array(policy["bindings"]).flat_map do |binding|
+        next [] unless Array(binding["principalLinks"]).include?(config.identity_link)
+
+        Array(binding["permissions"])
+      end.uniq
+    end
+
+    def shared_secret_policy_missing_message(grant)
+      "Shared secret policy '#{grant.fetch(:policy_name)}' for shared_secret_grants entry " \
+        "'#{grant.fetch(:name)}' does not exist. Create the policy or remove the shared secret grant."
+    end
+
     def ensure_docker_running!
       result = Shell.cmd("docker", "version", capture_stderr: true)
       return if result[:success]

data/lib/command/cleanup_stale_apps.rb

@@ -23,7 +23,7 @@ module Command
     DESCRIPTION = "Deletes or stops stale apps based on the latest image's creation date"
     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 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

data/lib/command/delete.rb

@@ -12,7 +12,8 @@ module Command
     DESCRIPTION = "Deletes the whole app (GVC with all workloads, all volumesets and all images) or a specific workload"
     LONG_DESCRIPTION = <<~DESC
       - 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
@@ -55,8 +56,11 @@ module Command
       check_images
       return unless confirm_delete(config.app)
 
+      # Snapshot policy state before the pre-deletion hook, so config errors surface
+      # before hook side effects while the hook can still use bound shared secrets.
+      policy_unbinds = secret_policy_unbinds
       run_pre_deletion_hook unless config.options[:skip_pre_deletion_hook]
-      unbind_identity_from_policy
+      unbind_identity_from_policy(policy_unbinds)
       delete_volumesets
       delete_gvc
       delete_images
@@ -125,19 +129,90 @@ module Command
       end
     end
 
-    def unbind_identity_from_policy
-      return if cp.fetch_identity(config.identity).nil?
+    def unbind_identity_from_policy(policy_unbinds)
+      policy_unbinds.each do |policy_unbind|
+        unbind_identity_from_secret_policy(policy_unbind)
+      end
+    end
+
+    def secret_policy_unbinds
+      return [] if cp.fetch_identity(config.identity).nil?
+
+      [
+        app_secret_policy_unbind,
+        *shared_secret_policy_unbinds
+      ].compact
+    end
+
+    def app_secret_policy_unbind
+      policy_unbind_for(
+        config.secrets_policy,
+        "Unbinding identity from policy for app '#{config.app}'"
+      )
+    end
+
+    def shared_secret_policy_unbinds
+      config.shared_secret_grants.filter_map do |grant|
+        shared_secret_policy_unbind(grant)
+      end
+    end
 
-      policy = cp.fetch_policy(config.secrets_policy)
+    def shared_secret_policy_unbind(grant)
+      policy_name = grant.fetch(:policy_name)
+      policy = cp.fetch_policy(policy_name)
       return if policy.nil?
 
-      is_bound = policy["bindings"].any? do |binding|
-        binding["principalLinks"].any? { |link| link == config.identity_link }
+      # cpflow only grants reveal on shared policies, so that is the only
+      # permission we remove from shared grants during cleanup.
+      return unless identity_bound_to_policy_with_reveal?(policy)
+
+      unless shared_secret_policy_targets_secret?(grant, policy)
+        # A drifted shared policy should not block teardown. Remove the app
+        # identity's reveal binding anyway so reusing the app name cannot inherit access.
+        warn_shared_secret_policy_target_mismatch(grant, policy_name)
       end
-      return unless is_bound
 
-      step("Unbinding identity from policy for app '#{config.app}'") do
-        cp.unbind_identity_from_policy(config.identity_link, config.secrets_policy)
+      shared_secret_policy_unbind_data(policy_name)
+    end
+
+    def shared_secret_policy_unbind_data(policy_name)
+      {
+        policy_name: policy_name,
+        message: "Unbinding identity from shared secret policy '#{policy_name}' for app '#{config.app}'",
+        permissions: ["reveal"]
+      }
+    end
+
+    def warn_shared_secret_policy_target_mismatch(grant, policy_name)
+      progress.puts(
+        "Warning: unbinding identity from shared secret policy '#{policy_name}' even though it does not " \
+        "target configured secret '#{grant.fetch(:secret_name)}'."
+      )
+    end
+
+    def policy_unbind_for(policy_name, message)
+      policy = cp.fetch_policy(policy_name)
+      return if policy.nil?
+
+      permissions = identity_policy_permissions(policy)
+      return if permissions.empty?
+
+      {
+        policy_name: policy_name,
+        message: message,
+        permissions: permissions
+      }
+    end
+
+    def unbind_identity_from_secret_policy(policy_unbind)
+      policy_unbind.fetch(:permissions).each do |permission|
+        step("#{policy_unbind.fetch(:message)} (#{permission})") do
+          cp.unbind_identity_from_policy(
+            config.identity_link,
+            policy_unbind.fetch(:policy_name),
+            permission: permission
+          )
+        end
       end
     end