cpflow 5.3.0 → 6.0.0

data/docs/rds-private-networking.md

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

data/docs/releasing.md

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

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

@@ -11,6 +11,48 @@ set these values directly at the GVC or workload levels, so none of these ENV va
 
 ## Review app secrets
 
+For credentials and initialization scripts created by the PostgreSQL template, see
+[PostgreSQL for disposable review apps](./postgres-review-apps.md).
+
+For same-repository review apps that need only disposable credentials, opt in on
+the dynamically matched review-app entry in `.controlplane/controlplane.yml`:
+
+```yaml
+apps:
+  my-app-review:
+    match_if_app_name_starts_with: true
+    generated_review_secret_keys:
+      - SECRET_KEY_BASE
+      - RENDERER_PASSWORD
+```
+
+`cpflow setup-app` then creates a separate `APP_NAME-secrets` dictionary and
+policy for each PR app, tags both resources with the exact app name, fills each
+configured key with a random 256-bit hex value, and never prints the values.
+`--refresh-templates` fills missing keys without rotating existing values.
+Initial template application skips templates named for the generated dictionary
+and policy, so templates cannot replace its values or broaden its access.
+Refresh also skips the generated policy template.
+Setup refuses to reuse a dictionary without the exact app tag or a policy that
+targets another secret or binds another principal; it rechecks the policy
+immediately before granting the app identity. Keep this
+setting off persistent apps and do
+not combine it with custom `secrets_name` or `secrets_policy_name`. Templates
+that use `{{APP_SECRETS}}` automatically point at the PR-specific dictionary.
+`cpflow delete` and delete-mode stale cleanup remove that dictionary and policy
+before removing the app, provided the policy still targets the dictionary and
+has no other bindings. Generated dictionaries carry an app marker; if a prior
+attempt removed the policy first, cleanup can use that marker to remove only the
+matching disposable dictionary. An unmarked policy is also left for inspection
+if its dictionary is already gone. If the GVC was removed separately before disposable credential cleanup finished, rerun
+`cpflow delete` with the same app name to finish secret cleanup. The generated
+delete action calls that same recovery path when the GVC is already absent.
+Cleanup still checks the app-specific names and tag if the key-generation option
+was later removed. Unexpected grants or unmarked secrets leave those resources
+for inspection.
+This generates credentials only; external licenses, database accounts, and
+provider tokens still require their own review-only provisioning.
+
 Review apps run application code from pull requests. For repositories with external contributors, do not put sensitive
 production or long-lived staging secrets in review apps. A secret reference such as `cpln://secret/...` protects the
 value while it is stored in Control Plane configuration, but the value becomes readable by application code after it is

data/docs/sidebars.ts

@@ -44,6 +44,7 @@ const sidebars: SidebarsConfig = {
       label: 'Data Services',
       items: [
         'postgres',
+        'postgres-review-apps',
         'rds-private-networking',
         'redis',
       ],

data/examples/controlplane.yml

@@ -104,6 +104,11 @@ aliases:
     # If not specified, defaults to 21600 (6 hours).
     runner_job_timeout: 1000
 
+    # Sets how long `cpflow run` waits for Control Plane to reconcile a cron job status
+    # after the non-interactive command prints its completion marker.
+    # If not specified, defaults to 1200 (20 minutes).
+    runner_job_status_reconciliation_timeout: 1200
+
     # Apps with a deployed image created before this amount of days will be listed for deletion
     # when running the command `cpflow cleanup-stale-apps`.
     stale_app_image_deployed_days: 5

data/lib/command/ai_github_flow_prompt.rb

@@ -32,9 +32,9 @@ module Command
       <<~PROMPT
         Set up Control Plane GitHub Flow for this repo. First make sure the `cpflow` CLI is available: use the repo's existing `bundle exec cpflow` if present, otherwise install the published `cpflow` Ruby gem with `gem install cpflow`; if neither is possible, stop and report that blocker. Use the same `cpflow` invocation for the rest of the rollout. Start with `cpflow github-flow-readiness` and stop on any reported blockers. The repo must be deployable from a clean clone: published package versions, complete runtime scaffold, and a production Dockerfile that can build the app. If any package version is unpublished, inaccessible from CI, or requires credentials that are not already modeled in the repo or GitHub settings, stop and report the blocker instead of generating workflow files. If the repo is a legacy sample pinned to an obsolete Ruby or Bundler toolchain, if it does not even have a production Dockerfile yet, or if it is a monorepo without an already-decided single app boundary for this flow, stop and report that as a prerequisite instead of forcing the rollout.
 
-        If `.controlplane/` is missing, run `cpflow generate`. Treat the generated app names as the repo-name default (`#{inferred_app_prefix}`) and rename them only if the project needs a different prefix. Then run `cpflow generate-github-actions` (or `cpflow generate-github-actions --staging-branch BRANCH` when staging should deploy from a branch other than `main`/`master`), keep review apps opt-in via `+review-app-deploy`, make sure any `STAGING_APP_BRANCH` repository variable is also present in the generated staging workflow's `on.push.branches` filter, and list the GitHub secrets and variables that must be configured. Do not hand-edit duplicated upstream refs into the generated wrappers: the only downstream Control Plane Flow pin should be the reusable workflow `uses: ...@vX.Y.Z` value generated from the installed `cpflow` gem version, and upstream workflows load their matching shared actions automatically. When bumping the `cpflow` gem in a downstream repo, run `cpflow update-github-actions` (or `bundle exec cpflow update-github-actions`) and validate with `bin/test-cpflow-github-flow` in the same PR so the checked-in wrappers move to the matching release tag. Keep the normal generated review-app setup simple: review apps require only `CPLN_TOKEN_STAGING` when the generated review app config can be inferred. For public demos, starter staging apps, and long-lived review apps, keep the app workload `type: standard` with one warm replica, set its autoscaling metric to `disabled`, and enable `capacityAI: true` so Control Plane can right-size CPU and memory allocation at that fixed replica count. Shared Postgres and other stateful workloads are the usual exceptions and should stay manually sized; Capacity AI is for supported stateless app/service workloads. If true idle scale-to-zero is explicitly required, create a separate `serverless` workload before first deploy or plan a delete/recreate migration because Control Plane will not change an existing `standard` workload to `serverless` in place. For shared review-app resources such as one staging database, use `shared_secret_grants` and `{{SHARED_SECRET_DATABASE}}` placeholders instead of hardcoding the base app secret name; this keeps review-app policy binding and cleanup automatic while avoiding per-PR database cost. Document the one-time Control Plane bootstrap command for persistent staging and production apps with `cpflow setup-app --skip-post-creation-hook`; for existing apps or later template updates, document `cpflow apply-template` and the need for the app identity to have `reveal` on the app secret policy. Do not imply the staging deploy or promotion workflows create those persistent GVCs. For production promotion, document a protected `production` GitHub Environment with required reviewers, prevent self-review, and `CPLN_TOKEN_PRODUCTION` stored as an environment secret, not as a repository or organization secret.
+        If `.controlplane/` is missing, run `cpflow generate`. Treat the generated app names as the repo-name default (`#{inferred_app_prefix}`) and rename them only if the project needs a different prefix. Then run `cpflow generate-github-actions` (or `cpflow generate-github-actions --staging-branch BRANCH` when staging should deploy from a branch other than `main`/`master`), keep review apps opt-in via `+review-app-deploy`, make sure any `STAGING_APP_BRANCH` repository variable is also present in the generated staging workflow's `on.push.branches` filter, and list the GitHub secrets and variables that must be configured. Do not hand-edit duplicated upstream refs into the generated wrappers. Keep every generated Control Plane Flow source pin synchronized at the same `vX.Y.Z`: each reusable-workflow `uses: ...@vX.Y.Z` ref, the production promotion `.cpflow` checkout ref, and its `control_plane_flow_ref` setup input. By default, `cpflow generate-github-actions` derives these values from the installed `cpflow` gem version; temporary explicit ref overrides are for unreleased testing and must keep all three values synchronized. Keep the generated `.github/actions/cpflow-*` files from that same gem unchanged; upstream reusable workflows invoke those checked-in local actions and separately check out the matching runtime source at `.cpflow`. When bumping the `cpflow` gem in a downstream repo, `cpflow update-github-actions` refreshes local actions and helpers while preserving all top-level workflows, including their refs and triggers. Use `cpflow update-github-actions --workflows FILE...` to explicitly select wrappers for replacement, then review the diff and reapply downstream customizations. A differing existing validator blocks all writes: preserve its downstream checks in executable `bin/test-cpflow-github-flow-custom`, then remove or rename the old generated validator before retrying. The generated validator invokes that preserved extension and propagates its failures. Follow `docs/ci-automation.md` for the migration procedure, keep source pins compatible with the updated actions, and run `bin/test-cpflow-github-flow` in the same PR (or `bin/test-cpflow-github-flow bundle exec cpflow` when using Bundler). Keep the normal generated review-app setup simple: review apps require only `CPLN_TOKEN_STAGING` when the generated review app config can be inferred. For public demos, starter staging apps, and long-lived review apps, keep the app workload `type: standard` with one warm replica, set its autoscaling metric to `disabled`, and enable `capacityAI: true` so Control Plane can right-size CPU and memory allocation at that fixed replica count. Shared Postgres and other stateful workloads are the usual exceptions and should stay manually sized; Capacity AI is for supported stateless app/service workloads. If true idle scale-to-zero is explicitly required, create a separate `serverless` workload before first deploy or plan a delete/recreate migration because Control Plane will not change an existing `standard` workload to `serverless` in place. For shared review-app resources such as one staging database, use `shared_secret_grants` and `{{SHARED_SECRET_DATABASE}}` placeholders instead of hardcoding the base app secret name; this keeps review-app policy binding and cleanup automatic while avoiding per-PR database cost. Document the one-time Control Plane bootstrap command for persistent staging and production apps with `cpflow setup-app --skip-post-creation-hook`; for existing apps or later template updates, document `cpflow apply-template` and the need for the app identity to have `reveal` on the app secret policy. Do not imply the staging deploy or promotion workflows create those persistent GVCs. For production promotion, document a protected `production` GitHub Environment with required reviewers, prevent self-review, and `CPLN_TOKEN_PRODUCTION` stored as an environment secret, not as a repository or organization secret.
 
-        Keep Node available in the final image if asset compilation or SSR depends on ExecJS, Yarn, `pnpm`, or npm after the main install layer. Make sure the generated Dockerfile uses a Ruby base image compatible with the app's declared Ruby requirement. Preserve repo-defined frontend build hooks: if `config/shakapacker.yml` defines a `precompile_hook`, or React on Rails enables `config.auto_load_bundle = true`, confirm the generated Dockerfile runs that codegen step before `rails assets:precompile`. If `config/database.yml` shows SQLite in production, confirm that the generated scaffold uses persistent `db` and `storage` volumes plus a release script that runs `rails db:prepare`; otherwise keep the default Postgres workload. If the public workload is not named `rails`, set `PRIMARY_WORKLOAD` or adjust the generated workflows. Inspect the Dockerfile and package sources for private GitHub dependencies or `RUN --mount=type=ssh`; if present, wire `DOCKER_BUILD_SSH_KEY`, optionally set `DOCKER_BUILD_SSH_KNOWN_HOSTS` for non-GitHub SSH hosts, and keep `DOCKER_BUILD_EXTRA_ARGS` to newline-delimited single tokens such as `--build-arg=FOO=bar`.
+        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 redirects every production database file into persistent `/app/data` (or keeps it under persistent `/app/storage`) without mounting over the image's `/app/db` migrations, stores Active Storage under `/app/storage`, and 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`.
 
         Run the real local validations you can: Docker build if feasible, repo tests or smoke checks, YAML validation, and any CI-equivalent build steps. Push the branch and check the GitHub Actions results. Only stop early for a real external blocker or a product decision that changes scope.
       PROMPT

data/lib/command/apply_template.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../core/disposable_postgres_helpers"
+
 module Command
   class ApplyTemplate < Base # rubocop:disable Metrics/ClassLength
     NAME = "apply-template"
@@ -10,7 +12,9 @@ module Command
       location_option,
       skip_confirm_option,
       add_app_identity_option,
-      preserve_existing_runtime_option
+      preserve_existing_runtime_option,
+      exclude_secret_template_option,
+      exclude_policy_template_option
     ].freeze
     DESCRIPTION = "Applies application-specific configs from templates"
     LONG_DESCRIPTION = <<~DESC
@@ -19,6 +23,7 @@ module Command
       - 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
+      - Use `--exclude-secret-template NAME` and `--exclude-policy-template NAME` to exclude exact named templates without changing workload image handling
       - 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:**
@@ -61,7 +66,8 @@ module Command
       @skipped_templates = []
 
       templates = @template_parser.parse(@names_to_filenames.values)
-      templates = preserve_existing_runtime(templates) if config.options[:preserve_existing_runtime]
+      templates = filter_existing_resources(templates)
+      DisposablePostgresHelpers.new(config, cp).prepare_templates!(templates)
       pending_templates = confirm_templates(templates)
       add_app_identity_template(pending_templates) if config.options[:add_app_identity]
       pending_templates.each do |template|
@@ -77,6 +83,27 @@ module Command
 
     private
 
+    def filter_existing_resources(templates)
+      templates = preserve_existing_runtime(templates) if config.options[:preserve_existing_runtime]
+      templates = exclude_named_template(templates, :exclude_secret_template, "secret")
+      exclude_named_template(templates, :exclude_policy_template, "policy")
+    end
+
+    def exclude_named_template(templates, option, kind)
+      name = config.options[option]
+      return templates unless name
+      raise "--#{option.to_s.tr('_', '-')} requires a #{kind} name." if name.empty?
+
+      templates.filter_map do |template|
+        if template["kind"] == kind && template["name"] == name
+          report_skipped(template)
+          next
+        end
+
+        template
+      end
+    end
+
     def template_kind(template)
       case template["kind"]
       when "gvc"
@@ -154,13 +181,18 @@ module Command
       cache_existing_workloads(templates)
       ready_fallback_image = unambiguous_ready_app_image
 
+      skip_existing_secret_resources(templates).each do |template|
+        preserve_workload_images(template, ready_fallback_image) if template["kind"] == "workload"
+      end
+    end
+
+    def skip_existing_secret_resources(templates)
       templates.filter_map do |template|
         if template["kind"] == "secret" && cp.fetch_secret(template["name"])
           report_skipped(template)
           next
         end
 
-        preserve_workload_images(template, ready_fallback_image) if template["kind"] == "workload"
         template
       end
     end
@@ -312,7 +344,7 @@ module Command
       return unless @skipped_templates.any?
 
       skipped = @skipped_templates.map { |template| "  - [#{template_kind(template)}] #{template['name']}" }.join("\n")
-      progress.puts("\n#{Shell.color('Skipped templates (already exist):', :blue)}\n#{skipped}")
+      progress.puts("\n#{Shell.color('Skipped templates:', :blue)}\n#{skipped}")
     end
   end
 end

data/lib/command/base.rb

@@ -483,6 +483,28 @@ module Command
       }
     end
 
+    def self.exclude_secret_template_option(required: false)
+      {
+        name: :exclude_secret_template,
+        params: {
+          desc: "Excludes one named secret template while applying templates",
+          type: :string,
+          required: required
+        }
+      }
+    end
+
+    def self.exclude_policy_template_option(required: false)
+      {
+        name: :exclude_policy_template,
+        params: {
+          desc: "Excludes one named policy template while applying templates",
+          type: :string,
+          required: required
+        }
+      }
+    end
+
     def self.skip_pre_deletion_hook_option(required: false)
       {
         name: :skip_pre_deletion_hook,
@@ -688,15 +710,46 @@ module Command
     end
 
     def shared_secret_policy_targets_secret?(grant, policy)
+      policy_targets_secret?(policy, grant.fetch(:secret_name))
+    end
+
+    def policy_targets_secret?(policy, secret_name)
       target_links = Array(policy["targetLinks"])
 
       policy["targetKind"] == "secret" &&
         target_links.one? &&
-        shared_secret_policy_target_links(grant).include?(target_links.first)
+        secret_policy_target_links(secret_name).include?(target_links.first)
     end
 
-    def shared_secret_policy_target_links(grant)
-      secret_name = grant.fetch(:secret_name)
+    def generated_review_app_tag(resource)
+      tags = resource["tags"]
+      return nil unless tags.is_a?(Hash)
+
+      tags[::Config::GENERATED_REVIEW_APP_TAG]
+    end
+
+    def generated_review_secret_owned_by_app?(secret, secret_name = config.secrets)
+      secret.is_a?(Hash) && secret["name"] == secret_name && secret["type"] == "dictionary" &&
+        generated_review_app_tag(secret) == config.app
+    end
+
+    def generated_review_policy_binding_state(policy)
+      bindings = Array(policy["bindings"])
+      return :unbound if bindings.empty?
+      return :unsafe unless generated_review_policy_bindings_for_app?(bindings)
+
+      case bindings.map { |binding| binding["permissions"] }.uniq
+      when [[]] then :unbound
+      when [["reveal"]] then :bound
+      else :unsafe
+      end
+    end
+
+    def generated_review_policy_bindings_for_app?(bindings)
+      bindings.all? { |binding| Array(binding["principalLinks"]) == [config.identity_link] }
+    end
+
+    def secret_policy_target_links(secret_name)
       [
         "//secret/#{secret_name}",
         "/org/#{config.org}/secret/#{secret_name}"

data/lib/command/cleanup_stale_apps.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Command
-  class CleanupStaleApps < Base
+  class CleanupStaleApps < Base # rubocop:disable Metrics/ClassLength
     CLEANUP_MODE_OPTION = {
       name: :mode,
       params: {
@@ -24,7 +24,7 @@ module Command
     LONG_DESCRIPTION = <<~DESC
       - Acts on stale apps based on the creation date of the latest image, or the GVC if no images exist
       - With `--mode=delete` (default): deletes the whole app (GVC with all workloads, all volumesets and all images), and unbinds the app from the secrets policy and any configured `shared_secret_grants` policies as long as both the identity and each policy exist (and are bound)
-      - With `--mode=stop`: suspends all workloads via `cpflow ps:stop` — no GVC, volumeset, or image is removed; resume with `cpflow ps:start`
+      - With `--mode=stop`: suspends configured workloads that exist in the live GVC through Control Plane — no GVC, volumeset, or image is removed; resume with `cpflow ps:start`
       - `--mode=stop` only suspends workloads listed in `app_workloads` + `additional_workloads`; workloads present in the live GVC but missing from the config are skipped silently
       - `--mode=stop` returns once each workload is marked suspended; it does not wait for the workload to reach a not-ready state
       - Specify the amount of days after an app should be considered stale through `stale_app_image_deployed_days` in the `.controlplane/controlplane.yml` file
@@ -101,14 +101,38 @@ module Command
     def process_app(app)
       if mode == "stop"
         progress.puts("Stopping app '#{app}'")
-        run_cpflow_command("ps:stop", "-a", app)
+        stop_configured_live_workloads(app)
       else
         run_cpflow_command("delete", "-a", app, "--yes")
       end
     end
 
+    def stop_configured_live_workloads(app)
+      app_config = config.find_app_config(app)
+      raise "Can't find config for stale app '#{app}'." unless app_config
+
+      configured_workloads = required_app_option(app_config, app, :app_workloads) +
+                             required_app_option(app_config, app, :additional_workloads)
+      live_workloads = (cp.fetch_workloads(app)&.fetch("items", []) || []).map { |workload| workload.fetch("name") }
+
+      (configured_workloads & live_workloads).each do |workload|
+        step("Stopping workload '#{workload}'") do
+          cp.set_workload_suspend(workload, true, app, missing_ok: true)
+        end
+      end
+    end
+
+    def required_app_option(app_config, app, option)
+      raise "Can't find option '#{option}' for app '#{app}' in 'controlplane.yml'." unless app_config.key?(option)
+
+      value = app_config.fetch(option)
+      raise "Option '#{option}' for app '#{app}' in 'controlplane.yml' must be an array." unless value.is_a?(Array)
+
+      value
+    end
+
     def action_description
-      mode == "stop" ? "suspend all workloads in" : "delete"
+      mode == "stop" ? "suspend configured workloads in" : "delete"
     end
 
     def mode

data/lib/command/copy_image_from_upstream.rb

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