cpflow 5.0.4 → 5.1.0

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/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/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.0"
   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

@@ -66,27 +66,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: