cpflow 6.0.0.rc.0 → 6.0.1

data/lib/github_flow_templates/bin/pin-cpflow-github-ref

@@ -2,19 +2,28 @@
 # frozen_string_literal: true
 
 require "pathname"
+require "optparse"
 
 USAGE = <<~USAGE
-  Usage: bin/pin-cpflow-github-ref [--allow-moving-ref] <control-plane-flow-ref>
+  Usage: bin/pin-cpflow-github-ref [--version TAG] [--allow-moving-ref] <control-plane-flow-ref>
 
   Use a release tag for normal operation, e.g. v5.0.0.
   Use a full 40-character commit SHA for temporary unreleased upstream testing.
+  --version TAG supplies the reviewed v-prefixed version/tag for SHA comments
+  (required for a SHA; no default). Verify the tag/version against upstream first.
+  This helper does not resolve tags over the network or verify tag-to-SHA identity.
   This updates generated reusable-workflow `uses:` refs plus the production
   workflow's pinned control-plane-flow checkout and setup validation ref.
   Regenerate from the cpflow gem when templates changed.
   Use --allow-moving-ref only for short-lived local branch/ref experiments.
+  Use -h or --help to show this help.
 USAGE
 
-ALLOWED_OPTIONS = ["--allow-moving-ref"].freeze
+if ARGV.include?("--help") || ARGV.include?("-h")
+  puts USAGE
+  exit 0
+end
+
 FULL_COMMIT_SHA = /\A[0-9a-f]{40}\z/i
 RELEASE_TAG = /\Av\d+\.\d+\.\d+(?:[-.][0-9A-Za-z][0-9A-Za-z.-]*)?\z/
 PRODUCTION_WORKFLOW_REF = "shakacode/control-plane-flow/.github/workflows/" \
@@ -25,14 +34,19 @@ CPFLOW_CHECKOUT_REF_PATTERN = %r{
     ^\s+repository:\s+shakacode/control-plane-flow\s*\n
     (?:(?!^\s*-\s+name:).)*?
     ^\s+ref:\s+)
-  [^\s]+
+  [^\s\#]+ [\t\ ]* (?:\#[^\n]*)?
 }mx
 
-options, positional = ARGV.partition { |arg| arg.start_with?("--") }
-unknown_options = options - ALLOWED_OPTIONS
-
-unless unknown_options.empty?
-  warn "Unknown option(s): #{unknown_options.join(', ')}"
+version = nil
+allow_moving_ref = false
+parser = OptionParser.new do |options|
+  options.on("--version TAG") { |value| version = value }
+  options.on("--allow-moving-ref") { allow_moving_ref = true }
+end
+begin
+  positional = parser.parse(ARGV)
+rescue OptionParser::ParseError => e
+  warn e.message
   warn USAGE
   exit 1
 end
@@ -43,13 +57,21 @@ unless positional.length == 1
 end
 
 ref = positional.first
-allow_moving_ref = options.include?("--allow-moving-ref")
 
 unless ref.match?(%r{\A[0-9A-Za-z._/-]+\z})
   warn "Ref contains unsupported characters: #{ref.inspect}"
   exit 1
 end
 
+if (version && !version.match?(RELEASE_TAG)) || (ref.match?(FULL_COMMIT_SHA) && !version)
+  warn "A SHA pin requires --version TAG with a reviewed v-prefixed version/tag (for example v6.0.0.rc.0)."
+  warn USAGE
+  exit 1
+end
+
+ref = ref.downcase if ref.match?(FULL_COMMIT_SHA)
+annotated_ref = ref.match?(FULL_COMMIT_SHA) ? "#{ref} # #{version}" : ref
+
 unless ref.match?(FULL_COMMIT_SHA) || ref.match?(RELEASE_TAG) || allow_moving_ref
   warn "Ref must be a full 40-character commit SHA or a v-prefixed release tag: #{ref.inspect}"
   warn "Use --allow-moving-ref only for a short-lived branch/ref experiment."
@@ -68,11 +90,13 @@ changed = []
 workflow_paths.each do |path|
   text = File.read(path)
   production_setup_ref_pattern =
-    /(control_plane_flow_ref:\s+#{Regexp.escape(PRODUCTION_WORKFLOW_REF)}@)[^\s]+/
+    /(control_plane_flow_ref:\s+#{Regexp.escape(PRODUCTION_WORKFLOW_REF)}@)[^\s#]+[\t ]*(?:#[^\n]*)?/
+  workflow_ref_pattern =
+    %r{(uses:\s+shakacode/control-plane-flow/\.github/workflows/[^@\s]+@)[^\s#]+[\t ]*(?:#[^\n]*)?}
   updated = text
-            .gsub(%r{(uses:\s+shakacode/control-plane-flow/\.github/workflows/[^@\s]+@)[^\s]+}, "\\1#{ref}")
-            .gsub(production_setup_ref_pattern, "\\1#{ref}")
-            .gsub(CPFLOW_CHECKOUT_REF_PATTERN, "\\1#{ref}")
+            .gsub(workflow_ref_pattern) { "#{Regexp.last_match(1)}#{annotated_ref}" }
+            .gsub(production_setup_ref_pattern) { "#{Regexp.last_match(1)}#{annotated_ref}" }
+            .gsub(CPFLOW_CHECKOUT_REF_PATTERN) { "#{Regexp.last_match(1)}#{annotated_ref}" }
 
   next if updated == text
 

data/lib/github_flow_templates/bin/test-cpflow-github-flow

@@ -29,7 +29,11 @@ documents.each_key do |path|
   puts "parsed #{path}"
 end
 
-generated_local_action_pattern = %r{\A\./(?<directory>\.github/actions/cpflow-[a-z0-9]+(?:-[a-z0-9]+)*)\z}
+# Current workflows load cpflow actions from the pinned `.cpflow` checkout, which exists
+# only at run time. Caller-owned `.github/actions/cpflow-*` copies are the cpflow 6.0.0
+# layout; a workflow that still references one needs that copy checked in.
+generated_local_action_pattern =
+  %r{\A\./(?<checkout>\.cpflow/)?(?<directory>\.github/actions/cpflow-[a-z0-9]+(?:-[a-z0-9]+)*)\z}
 local_action_references = []
 invalid_local_action_references = []
 visited_container_ids = {}
@@ -43,10 +47,10 @@ walk = lambda do |node, source_path|
   case node
   when Hash
     uses = node["uses"]
-    if uses.is_a?(String) && uses.start_with?("./.github/actions/cpflow-")
+    if uses.is_a?(String) && uses.start_with?("./.github/actions/cpflow-", "./.cpflow/")
       match = uses.match(generated_local_action_pattern)
       if match
-        local_action_references << [source_path, match[:directory]]
+        local_action_references << [source_path, match[:directory]] unless match[:checkout]
       else
         invalid_local_action_references <<
           "#{source_path} has invalid generated local action reference #{uses}"
@@ -61,6 +65,24 @@ documents.each { |path, document| walk.call(document, path) }
 
 abort invalid_local_action_references.uniq.join("\n") unless invalid_local_action_references.empty?
 
+# `.cpflow` exists only after a job checks it out, so each job must do that before its first cpflow action.
+missing_checkouts = documents.flat_map do |path, document|
+  jobs = document.is_a?(Hash) && document["jobs"].is_a?(Hash) ? document["jobs"] : {}
+  jobs.filter_map do |job_name, job|
+    steps = job.is_a?(Hash) && job["steps"].is_a?(Array) ? job["steps"].grep(Hash) : []
+    first_action = steps.index { |step| step["uses"].to_s.start_with?("./.cpflow/") }
+    next unless first_action
+
+    checked_out = steps.take(first_action).any? do |step|
+      step["uses"].to_s.start_with?("actions/checkout@") &&
+        step["with"].is_a?(Hash) && step["with"]["path"] == ".cpflow" && !step["with"]["ref"].to_s.strip.empty?
+    end
+    "#{path}:#{job_name} must check out a pinned ref into .cpflow before its first cpflow action" unless checked_out
+  end
+end
+
+abort missing_checkouts.join("\n") unless missing_checkouts.empty?
+
 missing_actions = local_action_references.uniq.filter_map do |source_path, action_directory|
   directory_is_local = begin
     File.lstat(action_directory).directory?
@@ -79,7 +101,7 @@ missing_actions = local_action_references.uniq.filter_map do |source_path, actio
 end
 
 abort missing_actions.join("\n") unless missing_actions.empty?
-puts "all referenced local actions have checked-in descriptors"
+puts "all cpflow action references use the pinned checkout or a checked-in descriptor"
 RUBY
 
 echo "==> check composite action input descriptions"
@@ -142,60 +164,65 @@ Dir[".github/workflows/cpflow-*.yml"].sort.each do |path|
 end
 
 promote_path = ".github/workflows/cpflow-promote-staging-to-production.yml"
-promote_doc = YAML.load_file(promote_path, aliases: true)
-promote_job = promote_doc.fetch("jobs", {})["promote-to-production"]
+if File.exist?(promote_path)
+  promote_doc = YAML.load_file(promote_path, aliases: true)
+  promote_job = promote_doc.fetch("jobs", {})["promote-to-production"]
 
-unless promote_job
-  abort "#{promote_path}:promote-to-production job is missing"
-end
+  unless promote_job
+    abort "#{promote_path}:promote-to-production job is missing"
+  end
 
-if promote_job.key?("uses")
-  abort "#{promote_path}:promote-to-production must run as a normal caller-repo job, not a reusable workflow, so GitHub can expose production environment secrets"
-end
+  if promote_job.key?("uses")
+    abort "#{promote_path}:promote-to-production must run as a normal caller-repo job, not a reusable workflow, so GitHub can expose production environment secrets"
+  end
 
-unless promote_job["environment"].to_s == "production"
-  abort "#{promote_path}:promote-to-production must declare environment: production"
-end
+  # Older generated workflows use the string form; current ones add a deployment URL.
+  promote_environment = promote_job["environment"]
+  promote_environment = promote_environment["name"] if promote_environment.is_a?(Hash)
+  unless promote_environment.to_s == "production"
+    abort "#{promote_path}:promote-to-production must declare environment: production"
+  end
 
-checkout_step = Array(promote_job["steps"]).find { |step| step["name"] == "Checkout control-plane-flow actions" }
+  checkout_step = Array(promote_job["steps"]).find { |step| step["name"] == "Checkout control-plane-flow actions" }
 
-unless checkout_step
-  abort "#{promote_path}:promote-to-production must include a Checkout control-plane-flow actions step"
-end
+  unless checkout_step
+    abort "#{promote_path}:promote-to-production must include a Checkout control-plane-flow actions step"
+  end
 
-unless checkout_step["uses"] == EXPECTED_CPFLOW_CHECKOUT_ACTION
-  abort "#{promote_path}:promote-to-production must use #{EXPECTED_CPFLOW_CHECKOUT_ACTION} for the Checkout control-plane-flow actions step"
-end
+  unless checkout_step["uses"] == EXPECTED_CPFLOW_CHECKOUT_ACTION
+    abort "#{promote_path}:promote-to-production must use #{EXPECTED_CPFLOW_CHECKOUT_ACTION} for the Checkout control-plane-flow actions step"
+  end
 
-checkout_with = checkout_step.fetch("with", {})
-checkout_repository = checkout_with["repository"]
-checkout_ref = checkout_with["ref"]
+  checkout_with = checkout_step.fetch("with", {})
+  checkout_repository = checkout_with["repository"]
+  checkout_ref = checkout_with["ref"]
 
-unless checkout_repository == EXPECTED_CPFLOW_CHECKOUT_REPOSITORY
-  abort "#{promote_path}:promote-to-production must check out #{EXPECTED_CPFLOW_CHECKOUT_REPOSITORY}"
-end
+  unless checkout_repository == EXPECTED_CPFLOW_CHECKOUT_REPOSITORY
+    abort "#{promote_path}:promote-to-production must check out #{EXPECTED_CPFLOW_CHECKOUT_REPOSITORY}"
+  end
 
-if checkout_ref.to_s.strip.empty?
-  abort "#{promote_path}:promote-to-production must pin the Checkout control-plane-flow actions step"
-end
+  if checkout_ref.to_s.strip.empty?
+    abort "#{promote_path}:promote-to-production must pin the Checkout control-plane-flow actions step"
+  end
 
-refs[checkout_ref] << "#{promote_path}:promote-to-production"
+  refs[checkout_ref] << "#{promote_path}:promote-to-production"
 
-setup_step = Array(promote_job["steps"]).find { |step| step["name"] == "Setup production environment" }
+  setup_step = Array(promote_job["steps"]).find { |step| step["name"] == "Setup production environment" }
 
-unless setup_step
-  abort "#{promote_path}:promote-to-production must include a Setup production environment step"
-end
+  unless setup_step
+    abort "#{promote_path}:promote-to-production must include a Setup production environment step"
+  end
 
-setup_ref = setup_step.fetch("with", {})["control_plane_flow_ref"]
-setup_match = setup_ref.to_s.match(PROMOTE_WORKFLOW)
+  setup_ref = setup_step.fetch("with", {})["control_plane_flow_ref"]
+  setup_match = setup_ref.to_s.match(PROMOTE_WORKFLOW)
 
-unless setup_match
-  abort "#{promote_path}:promote-to-production must pass a pinned production control_plane_flow_ref to setup, " \
-        "for example #{EXPECTED_PROMOTE_WORKFLOW_REF_FORMAT}"
-end
+  unless setup_match
+    abort "#{promote_path}:promote-to-production must pass a pinned production control_plane_flow_ref to setup, " \
+          "for example #{EXPECTED_PROMOTE_WORKFLOW_REF_FORMAT}"
+  end
 
-refs[setup_match[1]] << "#{promote_path}:promote-to-production setup"
+  refs[setup_match[1]] << "#{promote_path}:promote-to-production setup"
+end
 
 if refs.empty?
   puts "no upstream cpflow reusable workflow refs found"
@@ -210,7 +237,21 @@ end
 RUBY
 
 echo "==> actionlint"
-actionlint \
-  -ignore "SC2129" \
-  -ignore 'property "workflow_(ref|sha|repository|file_path)" is not defined in object type' \
-  .github/workflows/cpflow-*.yml
+shopt -s nullglob
+cpflow_workflows=(.github/workflows/cpflow-*.yml)
+if [[ ${#cpflow_workflows[@]} -gt 0 ]]; then
+  actionlint \
+    -ignore "SC2129" \
+    -ignore 'property "workflow_(ref|sha|repository|file_path)" is not defined in object type' \
+    "${cpflow_workflows[@]}"
+fi
+
+custom_validator="bin/test-cpflow-github-flow-custom"
+if [[ -e "$custom_validator" || -L "$custom_validator" ]]; then
+  if [[ ! -f "$custom_validator" || ! -x "$custom_validator" ]]; then
+    echo "Custom validator must be an executable file: $custom_validator" >&2
+    exit 1
+  fi
+  echo "==> downstream cpflow GitHub flow checks"
+  "$ROOT/$custom_validator" "${cpflow_cmd[@]}"
+fi

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cpflow
 version: !ruby/object:Gem::Version
-  version: 6.0.0.rc.0
+  version: 6.0.1
 platform: ruby
 authors:
 - Justin Gordon
@@ -82,6 +82,9 @@ files:
 - ".agents/bin/setup"
 - ".agents/bin/test"
 - ".agents/bin/validate"
+- ".agents/legacy-workflow-policy.yml"
+- ".agents/shaka.md"
+- ".agents/trusted-actions.yml"
 - ".agents/trusted-github-actors.yml"
 - ".agents/workflows/address-review.md"
 - ".agents/workflows/ai-rollout-e2e-test.md"
@@ -92,6 +95,8 @@ files:
 - ".github/actions/cpflow-delete-control-plane-app/action.yml"
 - ".github/actions/cpflow-delete-control-plane-app/delete-app.sh"
 - ".github/actions/cpflow-detect-release-phase/action.yml"
+- ".github/actions/cpflow-preview-promotion/action.yml"
+- ".github/actions/cpflow-preview-promotion/preview-promotion.sh"
 - ".github/actions/cpflow-resolve-review-config/action.yml"
 - ".github/actions/cpflow-setup-environment/action.yml"
 - ".github/actions/cpflow-validate-config/action.yml"
@@ -154,6 +159,7 @@ files:
 - docs/dns.md
 - docs/grafana-opentelemetry.md
 - docs/migrating-heroku-to-control-plane.md
+- docs/postgres-review-apps.md
 - docs/postgres.md
 - docs/rds-private-networking.md
 - docs/redis.md
@@ -178,6 +184,7 @@ files:
 - examples/circleci.yml
 - examples/controlplane.yml
 - lib/command/ai_github_flow_prompt.rb
+- lib/command/ai_github_flow_prompt.txt
 - lib/command/apply_template.rb
 - lib/command/base.rb
 - lib/command/base_sub_command.rb
@@ -225,6 +232,7 @@ files:
 - lib/core/controlplane.rb
 - lib/core/controlplane_api.rb
 - lib/core/controlplane_api_direct.rb
+- lib/core/disposable_postgres_helpers.rb
 - lib/core/doctor_service.rb
 - lib/core/github_flow_readiness/checks.rb
 - lib/core/github_flow_readiness_service.rb
@@ -254,6 +262,7 @@ files:
 - lib/cpflow.rb
 - lib/cpflow/version.rb
 - lib/deprecated_commands.json
+- lib/generator_templates/.dockerignore
 - lib/generator_templates/Dockerfile
 - lib/generator_templates/controlplane.yml
 - lib/generator_templates/entrypoint.sh
@@ -309,7 +318,7 @@ licenses:
 metadata:
   rubygems_mfa_required: 'true'
 post_install_message: |
-  cpflow 6.0.0.rc.0 installed.
+  cpflow 6.0.1 installed.
   Generated GitHub Actions users: run `cpflow update-github-actions` after upgrading.
   Docs: https://github.com/shakacode/control-plane-flow/blob/main/docs/ci-automation.md#updating-generated-github-actions-after-gem-updates
 rdoc_options: []
@@ -326,7 +335,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.18
+rubygems_version: 4.0.8
 specification_version: 4
 summary: Control Plane Flow
 test_files: []