cpflow 5.0.4 → 5.1.1

data/lib/command/deploy_image.rb

@@ -17,16 +17,32 @@ module Command
       - 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
     DESC
 
-    def call # rubocop:disable Metrics/MethodLength
-      run_release_script if config.options[:run_release_phase]
+    def call
+      release_script = release_script_to_run
+      image = resolve_image_to_deploy
+      shared_secret_policy_grant_pairs = resolve_shared_secret_policy_grants
+      workload_data_by_name = app_workload_data
+
+      bind_shared_secret_policy_grants(shared_secret_policy_grant_pairs)
+      run_release_script(release_script) if release_script
+      deploy_image_to_workloads(image, workload_data_by_name)
+    end
+
+    private
+
+    def app_workload_data
+      config[:app_workloads].to_h do |workload|
+        [workload, cp.fetch_workload!(workload)]
+      end
+    end
 
+    def deploy_image_to_workloads(image, workload_data_by_name) # rubocop:disable Metrics/MethodLength
       deployed_endpoints = {}
-      image = resolve_image_to_deploy
 
-      config[:app_workloads].each do |workload|
-        workload_data = cp.fetch_workload!(workload)
+      workload_data_by_name.each do |workload, workload_data|
         workload_data.dig("spec", "containers").each do |container|
           next unless container["image"].match?(%r{^/org/#{config.org}/image/#{config.app}[:@]})
 
@@ -47,8 +63,6 @@ module Command
       end
     end
 
-    private
-
     def resolve_image_to_deploy
       image = cp.latest_image
       # Preserve the pre-existing fail-fast check so missing images are reported
@@ -93,8 +107,16 @@ module Command
       deployments.dig("items", 0, "status", "endpoint")
     end
 
-    def run_release_script
+    def release_script_to_run
+      return unless config.options[:run_release_phase]
+
       release_script = config[:release_script]
+      return release_script if release_script.is_a?(String) && !release_script.strip.empty?
+
+      raise "release_script must be configured when --run-release-phase is provided."
+    end
+
+    def run_release_script(release_script)
       run_command_in_latest_image(release_script, title: "release script")
     end
   end

data/lib/command/generate_github_actions.rb

@@ -42,6 +42,7 @@ module Command
     def template_variables
       {
         "__CPFLOW_GITHUB_ACTIONS_REF__" => cpflow_github_actions_ref,
+        "__CPFLOW_MINOR_SERIES__" => cpflow_minor_series,
         "__STAGING_BRANCH_FILTER__" => staging_branch_filter,
         "__STAGING_BRANCH_DEFAULT__" => staging_branch_default
       }
@@ -78,6 +79,11 @@ module Command
     def default_cpflow_github_actions_ref
       "v#{::Cpflow::VERSION}"
     end
+
+    # Returns e.g. "5.0.x" for the version-locking placeholder in cpflow-help.md.
+    def cpflow_minor_series
+      "#{::Cpflow::VERSION.split('.').first(2).join('.')}.x"
+    end
   end
 
   class GenerateGithubActions < Base

data/lib/command/maintenance_off.rb

@@ -10,6 +10,7 @@ module Command
     DESCRIPTION = "Disables maintenance mode for an app"
     LONG_DESCRIPTION = <<~DESC
       - Disables maintenance mode for an app
+      - Safe to re-run: if a previous run timed out after switching the domain but before stopping the maintenance workload, re-running while maintenance mode is already disabled stops the maintenance workload to finish it (so it is not a pure no-op)
       - Specify the one-off workload through `one_off_workload` in the `.controlplane/controlplane.yml` file
       - Optionally specify the maintenance workload through `maintenance_workload` in the `.controlplane/controlplane.yml` file (defaults to 'maintenance')
       - Maintenance mode is only supported for domains that use path based routing mode and have a route configured for the prefix '/' on either port 80 or 443

data/lib/command/maintenance_on.rb

@@ -10,6 +10,7 @@ module Command
     DESCRIPTION = "Enables maintenance mode for an app"
     LONG_DESCRIPTION = <<~DESC
       - Enables maintenance mode for an app
+      - Safe to re-run: if a previous run timed out after switching the domain but before stopping the app workloads, re-running while maintenance mode is already enabled stops the app workloads to finish it (so it is not a pure no-op)
       - Specify the one-off workload through `one_off_workload` in the `.controlplane/controlplane.yml` file
       - Optionally specify the maintenance workload through `maintenance_workload` in the `.controlplane/controlplane.yml` file (defaults to 'maintenance')
       - Maintenance mode is only supported for domains that use path based routing mode and have a route configured for the prefix '/' on either port 80 or 443

data/lib/command/run.rb

@@ -47,6 +47,8 @@ module Command
         and also overridden per job through `--cpu` and `--memory`)
       - By default, the job is stopped if it takes longer than 6 hours to finish
         (can be configured though `runner_job_timeout` in `controlplane.yml`)
+      - Non-interactive jobs return the Control Plane cron job status even when the job finishes before
+        Control Plane exposes a runner replica to attach logs to
     DESC
     EXAMPLES = <<~EX.freeze
       ```sh
@@ -97,7 +99,7 @@ module Command
 
     attr_reader :interactive, :detached, :location, :original_workload, :runner_workload,
                 :default_image, :default_cpu, :default_memory, :job_timeout, :job_history_limit,
-                :container, :job, :replica, :command
+                :container, :job, :replica, :command, :job_completed_before_replica_exit_status
 
     def call # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
       @interactive = config.options[:interactive] || interactive_command?
@@ -129,6 +131,7 @@ module Command
       update_runner_workload
       start_job
       wait_for_replica_for_job
+      exit(job_completed_before_replica_exit_status) if job_completed_before_replica_exit_status
 
       progress.puts
       if interactive
@@ -269,7 +272,20 @@ module Command
         result = cp.fetch_workload_replicas(runner_workload, location: location)
         @replica = result&.dig("items")&.find { |item| item.include?(job) }
 
-        replica || false
+        replica || completed_job_before_replica? || false
+      end
+    end
+
+    def completed_job_before_replica?
+      case current_job_status
+      when "successful"
+        @job_completed_before_replica_exit_status = ExitCode::SUCCESS
+        true
+      when nil, "active", "pending"
+        false
+      else
+        @job_completed_before_replica_exit_status = ExitCode::ERROR_DEFAULT
+        true
       end
     end
 
@@ -505,9 +521,7 @@ module Command
 
     def resolve_job_status # rubocop:disable Metrics/MethodLength
       loop do
-        result = cp.fetch_cron_workload(runner_workload, location: location)
-        job_details = result&.dig("items")&.find { |item| item["id"] == job }
-        status = job_details&.dig("status")
+        status = current_job_status
 
         Shell.debug("JOB STATUS", status)
 
@@ -522,6 +536,12 @@ module Command
       end
     end
 
+    def current_job_status
+      result = cp.fetch_cron_workload(runner_workload, location: location)
+      job_details = result&.dig("items")&.find { |item| item["id"] == job }
+      job_details&.dig("status")
+    end
+
     ###########################################
     ### temporary extaction from run:detached
     ###########################################

data/lib/command/setup_app.rb

@@ -17,6 +17,7 @@ module Command
       - 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
@@ -35,9 +36,11 @@ module Command
               "or run 'cpflow apply-template #{templates.join(' ')} -a #{config.app}'."
       end
 
-      skip_secrets_setup = config.options[:skip_secret_access_binding] ||
-                           config.options[:skip_secrets_setup] || config.current[:skip_secrets_setup]
+      skip_secrets_setup = skip_secrets_setup?
 
+      # Validate shared grants before app resource creation so config/policy
+      # drift does not leave a partially-created review app.
+      shared_secret_policy_grant_pairs = resolve_shared_secret_policy_grants unless skip_secrets_setup
       create_secret_and_policy_if_not_exist unless skip_secrets_setup
 
       args = []
@@ -45,11 +48,17 @@ module Command
       run_cpflow_command("apply-template", *templates, "-a", config.app, *args)
 
       bind_identity_to_policy unless skip_secrets_setup
+      bind_shared_secret_policy_grants(shared_secret_policy_grant_pairs) unless skip_secrets_setup
       run_post_creation_hook unless config.options[:skip_post_creation_hook]
     end
 
     private
 
+    def skip_secrets_setup?
+      config.options[:skip_secret_access_binding] ||
+        config.options[:skip_secrets_setup] || config.current[:skip_secrets_setup]
+    end
+
     def create_secret_and_policy_if_not_exist
       create_secret_if_not_exists
       create_policy_if_not_exists

data/lib/core/config.rb

@@ -10,6 +10,9 @@ class Config # rubocop:disable Metrics/ClassLength
   include Helpers
 
   CONFIG_FILE_LOCATION = ".controlplane/controlplane.yml"
+  REQUIRED_SHARED_SECRET_GRANT_KEYS = %i[name secret_name policy_name].freeze
+  SHARED_SECRET_RESOURCE_NAME_KEYS = %i[secret_name policy_name].freeze
+  CONTROL_PLANE_RESOURCE_NAME_REGEX = /\A[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\z/
 
   def initialize(args, options, required_options)
     @args = args
@@ -56,6 +59,16 @@ class Config # rubocop:disable Metrics/ClassLength
     current&.dig(:secrets_policy_name) || "#{secrets}-policy"
   end
 
+  def shared_secret_grants
+    @shared_secret_grants ||= normalize_shared_secret_grants(current&.dig(:shared_secret_grants))
+  end
+
+  def shared_secret_placeholders
+    shared_secret_grants.to_h do |grant|
+      ["{{SHARED_SECRET_#{grant.fetch(:name).upcase}}}", grant.fetch(:secret_name)]
+    end
+  end
+
   def location
     @location ||= load_location_from_options || load_location_from_env || load_location_from_file
   end
@@ -171,6 +184,74 @@ class Config # rubocop:disable Metrics/ClassLength
     raise "Can't find config for app '#{app_name}' in 'controlplane.yml'." unless app_options
   end
 
+  def normalize_shared_secret_grants(grants)
+    return [] if grants.nil?
+
+    raise "shared_secret_grants for app config must be an array." unless grants.is_a?(Array)
+
+    normalized_grants = grants.map.with_index { |grant, index| normalize_shared_secret_grant(grant, index) }
+    ensure_unique_shared_secret_grant_names!(normalized_grants)
+    normalized_grants
+  end
+
+  def normalize_shared_secret_grant(raw_grant, index)
+    ensure_shared_secret_grant_map!(raw_grant, index)
+
+    grant = raw_grant.transform_keys(&:to_sym)
+    label = grant[:name] || "##{index + 1}"
+    ensure_shared_secret_grant_keys!(grant, label)
+    ensure_shared_secret_resource_names!(grant, label)
+    build_shared_secret_grant(grant)
+  end
+
+  def build_shared_secret_grant(grant)
+    name = grant.fetch(:name).to_s
+    ensure_shared_secret_grant_name!(name)
+    {
+      name: name,
+      secret_name: grant.fetch(:secret_name).to_s,
+      policy_name: grant.fetch(:policy_name).to_s
+    }
+  end
+
+  def ensure_shared_secret_grant_map!(raw_grant, index)
+    return if raw_grant.is_a?(Hash)
+
+    raise "shared_secret_grants entry ##{index + 1} must be a map."
+  end
+
+  def ensure_shared_secret_grant_keys!(grant, label)
+    REQUIRED_SHARED_SECRET_GRANT_KEYS.each do |key|
+      value = grant[key]
+      raise "shared_secret_grants entry '#{label}' must include #{key}." if value.nil? || value.to_s.empty?
+    end
+  end
+
+  def ensure_shared_secret_grant_name!(name)
+    return if name.match?(/\A[a-z](?:[a-z0-9_]*[a-z0-9])?\z/)
+
+    raise "shared_secret_grants entry name '#{name}' must be lower snake case."
+  end
+
+  def ensure_shared_secret_resource_names!(grant, label)
+    SHARED_SECRET_RESOURCE_NAME_KEYS.each do |key|
+      value = grant.fetch(key).to_s
+      next if value.match?(CONTROL_PLANE_RESOURCE_NAME_REGEX)
+
+      raise "shared_secret_grants entry '#{label}' #{key} '#{value}' must be a Control Plane resource name."
+    end
+  end
+
+  def ensure_unique_shared_secret_grant_names!(grants)
+    seen_names = {}
+    grants.each do |grant|
+      name = grant.fetch(:name)
+      raise "shared_secret_grants entry name '#{name}' must be unique." if seen_names[name]
+
+      seen_names[name] = true
+    end
+  end
+
   def ensure_app!
     return if app
 

data/lib/core/controlplane.rb

@@ -396,13 +396,23 @@ class Controlplane # rubocop:disable Metrics/ClassLength
   end
 
   def bind_identity_to_policy(identity_link, policy)
-    cmd = "cpln policy add-binding #{policy} --org #{org} --identity #{identity_link} --permission reveal"
-    perform!(cmd)
+    cmd = [
+      "cpln", "policy", "add-binding", policy,
+      "--org", org,
+      "--identity", identity_link,
+      "--permission", "reveal"
+    ]
+    perform!(Shellwords.join(cmd))
   end
 
-  def unbind_identity_from_policy(identity_link, policy)
-    cmd = "cpln policy remove-binding #{policy} --org #{org} --identity #{identity_link} --permission reveal"
-    perform!(cmd)
+  def unbind_identity_from_policy(identity_link, policy, permission: "reveal")
+    cmd = [
+      "cpln", "policy", "remove-binding", policy,
+      "--org", org,
+      "--identity", identity_link,
+      "--permission", permission
+    ]
+    perform!(Shellwords.join(cmd))
   end
 
   # apply

data/lib/core/maintenance_mode.rb

@@ -1,8 +1,19 @@
 # frozen_string_literal: true
 
-class MaintenanceMode
+class MaintenanceMode # rubocop:disable Metrics/ClassLength
   extend Forwardable
 
+  DOMAIN_WORKLOAD_UPDATE_MAX_POLL_ATTEMPTS = 30
+  DOMAIN_WORKLOAD_UPDATE_RETRY_WAIT_SECONDS = 1
+  DOMAIN_WORKLOAD_UPDATE_STEP_OPTIONS = {
+    retry_on_failure: true,
+    # `with_retry` loops while `retry_count <= max_retry_count` starting from 0, so
+    # total attempts == max_retry_count + 1. Subtract 1 so the bounded poll runs
+    # exactly DOMAIN_WORKLOAD_UPDATE_MAX_POLL_ATTEMPTS times.
+    max_retry_count: DOMAIN_WORKLOAD_UPDATE_MAX_POLL_ATTEMPTS - 1,
+    wait: DOMAIN_WORKLOAD_UPDATE_RETRY_WAIT_SECONDS
+  }.freeze
+
   def_delegators :@command, :config, :progress, :cp, :step, :run_cpflow_command
 
   def initialize(command)
@@ -22,6 +33,7 @@ class MaintenanceMode
   def enable!
     if enabled?
       progress.puts("Maintenance mode is already enabled for app '#{config.app}'.")
+      ensure_app_workloads_stopped
     else
       enable_maintenance_mode
     end
@@ -30,6 +42,7 @@ class MaintenanceMode
   def disable!
     if disabled?
       progress.puts("Maintenance mode is already disabled for app '#{config.app}'.")
+      ensure_maintenance_workload_stopped
     else
       disable_maintenance_mode
     end
@@ -69,6 +82,28 @@ class MaintenanceMode
     cp.fetch_workload!(maintenance_workload)
   end
 
+  # A run that already switched the route but hit the poll timeout aborts before
+  # its final workload-stop step runs. The next `enable!`/`disable!` short-circuits
+  # on the route check, so do the matching stop here — once the route is on the
+  # target, this brings the workloads into the state that route implies. `ps:stop`
+  # is idempotent, so each is a no-op once the target workload is already stopped.
+  #
+  # The stop target differs by direction. `ps:stop -a` covers only
+  # `app_workloads` + `additional_workloads`, never the maintenance workload:
+  #   - enable!: the route now points at the maintenance workload, so the *app*
+  #     workloads are the ones left running and `ps:stop -a` is correct.
+  #   - disable!: the route now points at the app workloads (and a short-circuit
+  #     `disable!` can run on an app whose app workloads are serving live traffic),
+  #     so stopping all workloads would cause an outage. The workload a timed-out
+  #     `disable!` leaves running is the maintenance workload, so stop only that.
+  def ensure_app_workloads_stopped
+    start_or_stop_all_workloads(:stop)
+  end
+
+  def ensure_maintenance_workload_stopped
+    start_or_stop_maintenance_workload(:stop)
+  end
+
   def start_or_stop_all_workloads(action)
     run_cpflow_command("ps:#{action}", "-a", config.app, "--wait")
 
@@ -82,16 +117,68 @@ class MaintenanceMode
   end
 
   def switch_domain_workload(to:)
-    step("Switching workload for domain '#{domain_data['name']}' to '#{to}'") do
-      cp.set_domain_workload(domain_data, to)
-
-      # Give it a bit of time for the domain to update
-      Kernel.sleep(30)
+    domain_name = domain_data["name"]
+
+    # Unlike the polling step below, the switch request is intentionally not
+    # retried: if it fails, nothing has changed yet, so aborting and letting the
+    # user re-run is the safe outcome. (Retrying would not help here anyway —
+    # `with_retry` retries on a falsy return, and `set_domain_workload` raises
+    # rather than returning false.)
+    step("Requesting workload switch for domain '#{domain_name}' to '#{to}'") do
+      # `set_domain_workload` mutates the route in place, so send a deep copy
+      # (round-tripped through JSON, since the domain is plain parsed-API data
+      # with string keys and JSON-native values) to keep the cached
+      # `@domain_data` reflecting the real server route. The poll re-fetches and
+      # matches on that fresh data, but if every poll times out without a routable
+      # fetch, `@domain_data` is what a re-run's `enabled?`/`disabled?` check reads
+      # — mutating it here would make that check report the requested route, not
+      # the actual one.
+      domain_data_for_update = JSON.parse(JSON.generate(domain_data))
+      cp.set_domain_workload(domain_data_for_update, to)
     end
 
+    wait_for_domain_workload_switch(domain_name, to)
+
     progress.puts
   end
 
+  # If the route never switches within the bounded poll window, this step aborts
+  # (abort_on_error) before any workloads are stopped, so traffic stays on the
+  # current workload. The label tells the user how to recover, since an exhausted
+  # poll has no error message of its own to print.
+  def wait_for_domain_workload_switch(domain_name, to)
+    @last_poll_error = nil # reset the poll-error dedup state for this poll window
+    step("Waiting for domain '#{domain_name}' workload to switch to '#{to}' " \
+         "(re-run this command if it times out)", **DOMAIN_WORKLOAD_UPDATE_STEP_OPTIONS) do
+      domain_workload_update_confirmed?(domain_name, to)
+    end
+  end
+
+  # Refetches the domain, refreshes the cached `@domain_data` when the fetch
+  # returns a routable domain, and reports whether the route now points at
+  # `workload`. Any error — a 5xx mid-propagation, a transient 403
+  # (`ForbiddenError < StandardError`, not a `RuntimeError`), or a network blip —
+  # is treated as "not switched yet" so the poll keeps retrying. The broad rescue
+  # logs the error to the step's stderr, so a latent bug (e.g. `NoMethodError`)
+  # surfaces in the "failed!" output on timeout instead of being swallowed.
+  def domain_workload_update_confirmed?(domain_name, workload)
+    refreshed_domain_data = cp.fetch_domain(domain_name)
+    @domain_data = refreshed_domain_data if refreshed_domain_data
+    refreshed_domain_data && cp.domain_workload_matches?(refreshed_domain_data, workload)
+  rescue StandardError => e
+    # A persistent failure (bad domain name, network outage, a latent bug) repeats
+    # the same error on every poll attempt, so only log when the message changes —
+    # otherwise the timeout output would carry up to MAX_POLL_ATTEMPTS identical
+    # lines. Guard on `tmp_stderr` so this stays safe if ever called outside a
+    # `step` block, where no tmp stderr is set up.
+    message = "#{e.class}: #{e.message} (#{e.backtrace&.first})\n"
+    if message != @last_poll_error && Shell.tmp_stderr
+      Shell.write_to_tmp_stderr(message)
+      @last_poll_error = message
+    end
+    false
+  end
+
   def domain_data
     @domain_data ||=
       if config.domain

data/lib/core/template_parser.rb

@@ -49,6 +49,10 @@ class TemplateParser
                 .gsub("{{APP_SECRETS}}", config.secrets)
                 .gsub("{{APP_SECRETS_POLICY}}", config.secrets_policy)
 
+    config.shared_secret_placeholders.each do |placeholder, secret_name|
+      yaml_file = yaml_file.gsub(placeholder, secret_name)
+    end
+
     find_deprecated_variables(yaml_file)
 
     # Kept for backwards compatibility

data/lib/cpflow/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Cpflow
-  VERSION = "5.0.4"
+  VERSION = "5.1.1"
   MIN_CPLN_VERSION = "3.1.0"
 end

data/lib/generator_templates/controlplane.yml

@@ -41,6 +41,13 @@ apps:
   __APP_PREFIX__-review:
     <<: *common
     match_if_app_name_starts_with: true
+    # To save review-app database cost, create one shared staging database
+    # secret and policy, then uncomment this block and use
+    # {{SHARED_SECRET_DATABASE}} in templates that need DATABASE_URL.
+    # shared_secret_grants:
+    #   - name: database
+    #     secret_name: __APP_PREFIX__-review-database-secrets
+    #     policy_name: __APP_PREFIX__-review-database-secrets-policy
     # Uncomment to automatically initialize and tear down review-app databases:
     # hooks:
     #   post_creation: bundle exec rails db:prepare

data/lib/generator_templates_sqlite/controlplane.yml

@@ -41,6 +41,13 @@ apps:
   __APP_PREFIX__-review:
     <<: *common
     match_if_app_name_starts_with: true
+    # Optional: if a review app needs an existing shared org-level secret,
+    # declare its policy here and reference it in templates with
+    # {{SHARED_SECRET_<NAME>}}.
+    # shared_secret_grants:
+    #   - name: database
+    #     secret_name: __APP_PREFIX__-review-database-secrets
+    #     policy_name: __APP_PREFIX__-review-database-secrets-policy
 
   __APP_PREFIX__-production:
     <<: *production

data/lib/github_flow_templates/.github/cpflow-help.md

@@ -23,11 +23,23 @@ For the normal generated review-app path, GitHub needs one repository secret:
 | --- | --- | --- |
 | `CPLN_TOKEN_STAGING` | Repository secret | Control Plane service-account token for the staging/review org. |
 
+For public repositories, use a staging/review token that cannot access
+production Control Plane resources. Generated review-app deploys skip fork PR
+heads because Docker builds use repository secrets. If a forked change needs a
+review app, first move the reviewed change to a trusted branch in this
+repository.
+
 No repository variables are required for the standard review-app path when
 `.controlplane/controlplane.yml` has exactly one review app entry with
 `match_if_app_name_starts_with: true`. cpflow infers the review-app prefix and
 staging org from that config.
 
+Review apps run pull request code. Any value mounted through
+`cpln://secret/...` can be read by that code after the workload starts, so keep
+review-app secret dictionaries limited to disposable databases, review-only
+renderer credentials, and license values that are acceptable for review-app
+exposure.
+
 Optional overrides exist for forks, clones, and unusual apps:
 
 | Name | Notes |
@@ -66,27 +78,50 @@ Production promotion is part of the generated flow, but keep it protected:
 | `PRODUCTION_APP_NAME` | Prefer `production` Environment variable | Production app name from `controlplane.yml`. |
 
 Configure the `production` GitHub Environment with required reviewers and
-prevent self-review. The generated promotion wrapper passes only the staging
-token from repository secrets; GitHub injects `CPLN_TOKEN_PRODUCTION` only after
-the environment approval gate passes.
+prevent self-review. 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. Do not move production
+promotion behind a cross-repo reusable workflow: GitHub does not expose this
+repo's environment secrets to that called workflow.
+
+Keep `CPLN_TOKEN_PRODUCTION` absent from repository and organization secrets. A
+normal environment-gated job cannot tell which secret scope supplied a nonempty
+value, so a broader secret with the same name can mask a missing environment
+secret.
+
+If the promotion workflow fails with
+`CPLN_TOKEN_PRODUCTION is not set. Add it as a secret on the 'production' GitHub Environment.`,
+the token is missing from the environment scope or the workflow job is no longer
+declaring `environment: production`. Create or verify the environment secret
+and confirm there is no same-named repository or organization secret:
+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
+```
 
 Before the first promotion, bootstrap the production app the same way in the
 production org, using production-only secrets and values.
 
 ## Version Locking
 
-Generated wrappers pin Control Plane Flow once with the reusable workflow
-`uses:` ref, for example `@__CPFLOW_GITHUB_ACTIONS_REF__`. For stable releases,
-this ref should be a release tag. The upstream reusable workflow automatically
-loads its matching shared actions from GitHub's workflow context, so downstream
-wrappers should not pass a duplicate Control Plane Flow ref input. If your
-generated wrappers still include a `with:` block whose only purpose is to repeat
-the same ref, regenerate them with a newer `cpflow`.
+Generated wrappers pin Control Plane Flow with a release tag, for example
+`__CPFLOW_GITHUB_ACTIONS_REF__`. Reusable review-app, staging, cleanup, and
+helper workflows pin the tag in their `uses:` ref. Production promotion pins
+the same tag in the `Checkout control-plane-flow actions` step so the
+caller-owned job can keep `environment: production` and receive production
+environment secrets directly.
 
 Leave `CPFLOW_VERSION` unset so the workflow builds cpflow from the same
 checked-out upstream source. If you set `CPFLOW_VERSION`, it must match the
-release tag, for example `CPFLOW_VERSION=5.0.1` with a wrapper pinned to
-`uses: ...@v5.0.1`.
+release tag your wrappers are pinned to: a `CPFLOW_VERSION=__CPFLOW_MINOR_SERIES__` runtime
+override goes with a wrapper pinned to `uses: ...@v__CPFLOW_MINOR_SERIES__` (substitute the
+release you pinned above).
 
 After updating the `cpflow` gem in this repo, update the generated wrappers in
 the same PR:
@@ -119,7 +154,7 @@ Most apps do not need these:
 | Name | Notes |
 | --- | --- |
 | `DOCKER_BUILD_EXTRA_ARGS` | Newline-delimited extra Docker build tokens. |
-| `DOCKER_BUILD_SSH_KEY` | Private SSH key for Docker builds that fetch private dependencies. |
+| `DOCKER_BUILD_SSH_KEY` | Read-only, revocable deploy key for Docker builds that fetch private dependencies. Do not use a personal SSH key. |
 | `DOCKER_BUILD_SSH_KNOWN_HOSTS` | SSH known_hosts entries when SSH build hosts are not GitHub.com. |
 | `REVIEW_APP_DEPLOYING_ICON_URL` | Cosmetic custom image URL for the animated deploying icon. Set to `none` to use the text fallback icon. |
 | `STAGING_APP_BRANCH` | Custom staging branch. The branch must also appear in `cpflow-deploy-staging.yml`'s push filter. |