cpflow 5.3.0 → 6.0.0

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

@@ -132,21 +132,30 @@ production org, using production-only secrets and values.
 
 ## Version Locking
 
-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
+Freshly generated wrappers start with a Control Plane Flow release tag, for
+example `__CPFLOW_GITHUB_ACTIONS_REF__`. Before review and merge, use the pin
+helper below to replace that tag with its immutable commit SHA and retain the
+reviewed tag in a readable comment. Reusable review-app, staging, cleanup, and
+helper workflows then use that SHA. Production promotion uses the same SHA and
+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 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).
+checked-out upstream source. `CPFLOW_VERSION` is supported only while the
+wrapper itself uses an actual release-tag ref; it must match that tag. Keep it
+unset after replacing the wrapper ref with an immutable SHA because the
+checked-out source already determines the runtime version.
 
-After updating the `cpflow` gem in this repo, update the generated wrappers in
-the same PR:
+If an existing `bin/test-cpflow-github-flow` differs from cpflow's generated
+validator, first preserve its downstream checks in executable
+`bin/test-cpflow-github-flow-custom`, then remove or rename the old generated
+validator before retrying the update.
+
+After updating the `cpflow` gem in this repo, refresh the generated local
+actions and validation helpers in the same PR. The default command
+preserves every top-level workflow, including its refs, triggers, permissions, and
+downstream customizations:
 
 ```sh
 cpflow update-github-actions
@@ -160,12 +169,30 @@ bundle exec cpflow update-github-actions
 bin/test-cpflow-github-flow bundle exec cpflow
 ```
 
+Replace workflow wrappers only after explicitly selecting and reviewing them:
+
+```sh
+cpflow update-github-actions --workflows FILE...
+```
+
+Reapply required downstream customizations after a selected replacement, then
+pin and validate the complete flow.
+
+For a reviewed release, resolve its tag to the exact commit SHA, then pin and
+validate that immutable source:
+
+```sh
+bin/pin-cpflow-github-ref --version vX.Y.Z <40-character-control-plane-flow-commit-sha>
+bin/test-cpflow-github-flow
+```
+
 Do not leave downstream apps pinned to a moving branch such as `main`. For a
 short-lived test of an unreleased upstream PR, pin to a full 40-character commit
-SHA and leave `CPFLOW_VERSION` unset:
+SHA, use the upstream source's current in-progress version tag as the readable
+`--version` label, and leave `CPFLOW_VERSION` unset:
 
 ```sh
-bin/pin-cpflow-github-ref <40-character-control-plane-flow-commit-sha>
+bin/pin-cpflow-github-ref --version vX.Y.Z <40-character-control-plane-flow-commit-sha>
 bin/test-cpflow-github-flow ruby /path/to/control-plane-flow/bin/cpflow
 ```
 

data/lib/github_flow_templates/.github/workflows/cpflow-deploy-review-app.yml

@@ -42,4 +42,5 @@ jobs:
     uses: shakacode/control-plane-flow/.github/workflows/cpflow-deploy-review-app.yml@__CPFLOW_GITHUB_ACTIONS_REF__
     secrets:
       CPLN_TOKEN_STAGING: ${{ secrets.CPLN_TOKEN_STAGING }}
+      REVIEW_APP_DOCKER_BUILD_SECRETS: ${{ secrets.REVIEW_APP_DOCKER_BUILD_SECRETS }}
       DOCKER_BUILD_SSH_KEY: ${{ secrets.DOCKER_BUILD_SSH_KEY }}

data/lib/github_flow_templates/.github/workflows/cpflow-deploy-staging.yml

@@ -21,4 +21,5 @@ jobs:
       staging_app_branch_default: "__STAGING_BRANCH_DEFAULT__"
     secrets:
       CPLN_TOKEN_STAGING: ${{ secrets.CPLN_TOKEN_STAGING }}
+      DOCKER_BUILD_SECRETS: ${{ secrets.DOCKER_BUILD_SECRETS }}
       DOCKER_BUILD_SSH_KEY: ${{ secrets.DOCKER_BUILD_SSH_KEY }}

data/lib/github_flow_templates/.github/workflows/cpflow-promote-staging-to-production.yml

@@ -46,27 +46,93 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
+  preview-promotion:
+    if: github.event.inputs.confirm_promotion == 'promote'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    # No production Environment or production token: this finishes before approval.
+    outputs:
+      primary_workload: ${{ steps.preview.outputs.primary_workload }}
+      staging_image: ${{ steps.preview.outputs.staging_image }}
+      production_commit: ${{ steps.preview.outputs.production_commit }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Checkout control-plane-flow actions
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          repository: shakacode/control-plane-flow
+          ref: __CPFLOW_GITHUB_ACTIONS_REF__
+          path: .cpflow
+          persist-credentials: false
+
+      - name: Normalize staging org
+        id: staging-org
+        env:
+          STAGING_ORG: ${{ vars.CPLN_ORG_STAGING }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          org="${STAGING_ORG#"${STAGING_ORG%%[![:space:]]*}"}"
+          org="${org%"${org##*[![:space:]]}"}"
+          if ! [[ "$org" =~ ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$ ]]; then
+            echo "::error::CPLN_ORG_STAGING must be a valid Control Plane org name."
+            exit 1
+          fi
+          echo "org=$org" >> "$GITHUB_OUTPUT"
+
+      - name: Setup staging environment
+        uses: ./.github/actions/cpflow-setup-environment
+        with:
+          token: ${{ secrets.CPLN_TOKEN_STAGING }}
+          org: ${{ steps.staging-org.outputs.org }}
+          working_directory: .cpflow
+          cpln_cli_version: ${{ vars.CPLN_CLI_VERSION }}
+          cpflow_version: ${{ vars.CPFLOW_VERSION }}
+          # The setup action validates CPFLOW_VERSION against this full workflow ref.
+          control_plane_flow_ref: shakacode/control-plane-flow/.github/workflows/cpflow-promote-staging-to-production.yml@__CPFLOW_GITHUB_ACTIONS_REF__
+
+      - name: Preview commits before production approval
+        id: preview
+        uses: ./.github/actions/cpflow-preview-promotion
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
+          CPLN_TOKEN: ${{ secrets.CPLN_TOKEN_STAGING }}
+        with:
+          staging_app_name: ${{ vars.STAGING_APP_NAME }}
+          staging_org: ${{ steps.staging-org.outputs.org }}
+          primary_workload: ${{ vars.PRIMARY_WORKLOAD }}
+
   promote-to-production:
+    needs: preview-promotion
     if: github.event.inputs.confirm_promotion == 'promote'
     runs-on: ubuntu-latest
     # This normal caller-repo job declares the protected production Environment
     # directly, so GitHub exposes environment secrets in this job after the
     # environment gate. Do not move production promotion back behind a
     # cross-repo reusable workflow; environment secrets are not available there.
-    environment: production
+    # The URL gives the deployment a "View deployment" link on GitHub.
+    environment:
+      name: production
+      url: ${{ steps.health-check.outputs.endpoint }}
     timeout-minutes: 45
     outputs:
       staging_app_name: ${{ steps.release-context.outputs.staging_app_name }}
       production_app_name: ${{ steps.release-context.outputs.production_app_name }}
+      staging_commit: ${{ steps.copy-image.outputs.staging_commit }}
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Checkout control-plane-flow actions
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           repository: shakacode/control-plane-flow
           ref: __CPFLOW_GITHUB_ACTIONS_REF__
@@ -90,7 +156,7 @@ jobs:
           fi
 
       - name: Validate required secrets and variables
-        uses: ./.cpflow/.github/actions/cpflow-validate-config
+        uses: ./.github/actions/cpflow-validate-config
         # Pass secrets via env so the composite action checks indirect shell
         # variables instead of interpolating secret values into a run script.
         env:
@@ -171,7 +237,7 @@ jobs:
           } >> "$GITHUB_OUTPUT"
 
       - name: Setup production environment
-        uses: ./.cpflow/.github/actions/cpflow-setup-environment
+        uses: ./.github/actions/cpflow-setup-environment
         with:
           token: ${{ secrets.CPLN_TOKEN_PRODUCTION }}
           org: ${{ steps.cpln-orgs.outputs.production }}
@@ -237,7 +303,7 @@ jobs:
 
       - name: Detect release phase support
         id: release-phase
-        uses: ./.cpflow/.github/actions/cpflow-detect-release-phase
+        uses: ./.github/actions/cpflow-detect-release-phase
         with:
           app_name: ${{ vars.PRODUCTION_APP_NAME }}
 
@@ -440,8 +506,35 @@ jobs:
 
           echo "image=${staging_image}" >> "$GITHUB_OUTPUT"
 
+      - name: Verify approved promotion snapshot
+        id: verify-preview
+        env:
+          PREVIEW_WORKLOAD: ${{ needs.preview-promotion.outputs.primary_workload }}
+          CURRENT_PRIMARY_WORKLOAD: ${{ steps.workloads.outputs.primary }}
+          PREVIEW_IMAGE: ${{ needs.preview-promotion.outputs.staging_image }}
+          PREVIEW_PRODUCTION_COMMIT: ${{ needs.preview-promotion.outputs.production_commit }}
+          CURRENT_STAGING_IMAGE: ${{ steps.staging-image.outputs.image }}
+          CURRENT_PRODUCTION_IMAGE: ${{ steps.capture-current.outputs.current_image }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [[ -z "$PREVIEW_WORKLOAD" || "$PREVIEW_WORKLOAD" != "$CURRENT_PRIMARY_WORKLOAD" ]]; then
+            echo "::error::The production primary workload differs from the preview. Set PRIMARY_WORKLOAD as a repository variable shared by both jobs and rerun."
+            exit 1
+          fi
+          if [[ -z "$PREVIEW_IMAGE" || "$CURRENT_STAGING_IMAGE" != "$PREVIEW_IMAGE" ]]; then
+            echo "::error::Staging changed since the preview. Rerun promotion and review the new comparison."
+            exit 1
+          fi
+          production_tag="${CURRENT_PRODUCTION_IMAGE%%@*}"
+          production_commit="${production_tag##*_}"
+          if [[ -n "$PREVIEW_PRODUCTION_COMMIT" && "$production_commit" != "$PREVIEW_PRODUCTION_COMMIT" ]]; then
+            echo "::error::Live production does not match its recorded release. Reconcile the production release record, then rerun promotion."
+            exit 1
+          fi
+
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
 
       - name: Copy image from staging
         id: copy-image
@@ -476,22 +569,26 @@ jobs:
             exit 1
           fi
 
-          if ! CPLN_TOKEN="${CPLN_TOKEN_STAGING}" cpln image get "${staging_image}" --org "${CPLN_ORG_STAGING}" -o json >/dev/null; then
+          staging_image_without_digest="${staging_image%%@*}"
+          if ! CPLN_TOKEN="${CPLN_TOKEN_STAGING}" cpln image get "${staging_image_without_digest}" --org "${CPLN_ORG_STAGING}" -o json >/dev/null; then
             echo "::error::Staging image '${STAGING_IMAGE}' was not found in org '${CPLN_ORG_STAGING}'; aborting promotion."
             exit 1
           fi
 
           staging_tag=""
-          if [[ "${staging_image}" == *@* ]]; then
-            staging_tag="${staging_image##*@}"
-          elif [[ "${staging_image}" == *:* ]]; then
-            staging_tag="${staging_image##*:}"
+          if [[ "${staging_image_without_digest}" == *:* ]]; then
+            staging_tag="${staging_image_without_digest##*:}"
           fi
           staging_commit=""
           if [[ "${staging_tag}" == *_* ]]; then
             staging_commit="${staging_tag##*_}"
           else
-            echo "::warning::Staging image '${staging_image}' did not include a '_<commit>' suffix; production image tag will omit the commit suffix."
+            echo "::error::Staging image '${staging_image}' does not include the commit suffix required for a traceable production release."
+            exit 1
+          fi
+          if ! [[ "${staging_commit}" =~ ^[0-9a-f]{40}$ ]]; then
+            echo "::error::Staging image '${staging_image}' has an invalid commit suffix; expected a full lowercase Git commit SHA."
+            exit 1
           fi
 
           # The workflow-level concurrency group serializes this sequence so two
@@ -566,8 +663,10 @@ jobs:
           fi
 
           echo "image=${production_image}" >> "$GITHUB_OUTPUT"
+          echo "staging_commit=${staging_commit}" >> "$GITHUB_OUTPUT"
 
       - name: Deploy image to production
+        id: deploy-production
         env:
           PRODUCTION_APP_NAME: ${{ vars.PRODUCTION_APP_NAME }}
           CPLN_ORG_PRODUCTION: ${{ steps.cpln-orgs.outputs.production }}
@@ -576,6 +675,16 @@ jobs:
         run: |
           set -euo pipefail
 
+          deployment_marker_dir="$(mktemp -d)"
+          export CPFLOW_DEPLOYMENT_STARTED_FILE="${deployment_marker_dir}/started"
+          record_deployment_state() {
+            if [[ -f "${CPFLOW_DEPLOYMENT_STARTED_FILE}" ]]; then
+              echo "deployment_started=true" >> "${GITHUB_OUTPUT}"
+            fi
+            rm -rf "${deployment_marker_dir}"
+          }
+          trap record_deployment_state EXIT
+
           deploy_args=(-a "${PRODUCTION_APP_NAME}")
           if [[ -n "${RELEASE_PHASE_FLAG}" ]]; then
             deploy_args+=("${RELEASE_PHASE_FLAG}")
@@ -589,7 +698,7 @@ jobs:
 
       - name: Wait for deployment health
         id: health-check
-        uses: ./.cpflow/.github/actions/cpflow-wait-for-health
+        uses: ./.github/actions/cpflow-wait-for-health
         with:
           workload_name: ${{ steps.workloads.outputs.primary }}
           app_name: ${{ vars.PRODUCTION_APP_NAME }}
@@ -599,7 +708,11 @@ jobs:
           accepted_statuses: ${{ env.HEALTH_CHECK_ACCEPTED_STATUSES }}
 
       - name: Roll back on failure
-        if: failure() && steps.capture-current.outcome == 'success'
+        if: >-
+          failure() &&
+          steps.deploy-production.outputs.deployment_started == 'true' &&
+          steps.capture-current.outputs.rollback_state != '' &&
+          steps.capture-current.outputs.rollback_state != '{}'
         env:
           ROLLBACK_STATE: ${{ steps.capture-current.outputs.rollback_state }}
           PRODUCTION_APP_NAME: ${{ vars.PRODUCTION_APP_NAME }}
@@ -661,7 +774,11 @@ jobs:
           fi
 
       - name: Wait for rollback readiness
-        if: failure() && steps.capture-current.outcome == 'success'
+        if: >-
+          failure() &&
+          steps.deploy-production.outputs.deployment_started == 'true' &&
+          steps.capture-current.outputs.rollback_state != '' &&
+          steps.capture-current.outputs.rollback_state != '{}'
         env:
           ROLLBACK_STATE: ${{ steps.capture-current.outputs.rollback_state }}
           PRODUCTION_APP_NAME: ${{ vars.PRODUCTION_APP_NAME }}
@@ -770,6 +887,7 @@ jobs:
           GITHUB_RUN_ID: ${{ github.run_id }}
           STAGING_APP_NAME: ${{ needs.promote-to-production.outputs.staging_app_name }}
           PRODUCTION_APP_NAME: ${{ needs.promote-to-production.outputs.production_app_name }}
+          STAGING_COMMIT: ${{ needs.promote-to-production.outputs.staging_commit }}
         shell: bash
         run: |
           set -euo pipefail
@@ -779,5 +897,6 @@ jobs:
           release_tag="production-${release_date}-${timestamp}-${GITHUB_RUN_ID}"
 
           gh release create "${release_tag}" \
+            --target "${STAGING_COMMIT}" \
             --title "Production Release ${release_date} ${timestamp}" \
             --notes "Promoted ${STAGING_APP_NAME} to ${PRODUCTION_APP_NAME} on ${release_date} at ${timestamp}."

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

@@ -16,10 +16,70 @@ echo "==> parse generated GitHub Actions YAML"
 ruby <<'RUBY'
 require "yaml"
 
-Dir[".github/actions/**/action.yml", ".github/workflows/*.yml"].sort.each do |path|
-  YAML.load_file(path, aliases: true)
+documents = Dir[
+  ".github/actions/**/action.yml",
+  ".github/actions/**/action.yaml",
+  ".github/workflows/*.yml",
+  ".github/workflows/*.yaml"
+].sort.to_h do |path|
+  [path, YAML.load_file(path, aliases: true)]
+end
+
+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}
+local_action_references = []
+invalid_local_action_references = []
+visited_container_ids = {}
+walk = lambda do |node, source_path|
+  if node.is_a?(Hash) || node.is_a?(Array)
+    next if visited_container_ids.key?(node.object_id)
+
+    visited_container_ids[node.object_id] = true
+  end
+
+  case node
+  when Hash
+    uses = node["uses"]
+    if uses.is_a?(String) && uses.start_with?("./.github/actions/cpflow-")
+      match = uses.match(generated_local_action_pattern)
+      if match
+        local_action_references << [source_path, match[:directory]]
+      else
+        invalid_local_action_references <<
+          "#{source_path} has invalid generated local action reference #{uses}"
+      end
+    end
+    node.each_value { |value| walk.call(value, source_path) }
+  when Array
+    node.each { |value| walk.call(value, source_path) }
+  end
+end
+documents.each { |path, document| walk.call(document, path) }
+
+abort invalid_local_action_references.uniq.join("\n") unless invalid_local_action_references.empty?
+
+missing_actions = local_action_references.uniq.filter_map do |source_path, action_directory|
+  directory_is_local = begin
+    File.lstat(action_directory).directory?
+  rescue Errno::ENOENT
+    false
+  end
+  descriptor_is_local = %w[action.yml action.yaml].any? do |filename|
+    begin
+      File.lstat(File.join(action_directory, filename)).file?
+    rescue Errno::ENOENT
+      false
+    end
+  end
+
+  "#{source_path} references missing local action #{action_directory}" unless directory_is_local && descriptor_is_local
+end
+
+abort missing_actions.join("\n") unless missing_actions.empty?
+puts "all referenced local actions have checked-in descriptors"
 RUBY
 
 echo "==> check composite action input descriptions"
@@ -45,7 +105,7 @@ require "yaml"
 CONTROL_PLANE_FLOW_WORKFLOW = %r{\Ashakacode/control-plane-flow/\.github/workflows/[^@\s]+@([^\s]+)\z}
 PROMOTE_WORKFLOW = %r{\Ashakacode/control-plane-flow/\.github/workflows/cpflow-promote-staging-to-production\.yml@([^\s]+)\z}
 EXPECTED_PROMOTE_WORKFLOW_REF_FORMAT = "shakacode/control-plane-flow/.github/workflows/cpflow-promote-staging-to-production.yml@vX.Y.Z"
-EXPECTED_CPFLOW_CHECKOUT_ACTION = "actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd"
+EXPECTED_CPFLOW_CHECKOUT_ACTION = "actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1"
 EXPECTED_CPFLOW_CHECKOUT_REPOSITORY = "shakacode/control-plane-flow"
 
 refs = Hash.new { |hash, key| hash[key] = [] }
@@ -82,60 +142,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"
@@ -150,7 +215,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