Validate cpflow gem and workflow pins

justin808 · justin808 · commit 6ab284f10f47 · 2026-05-23T21:49:32.000-10:00
diff --git a/.github/actions/cpflow-setup-environment/action.yml b/.github/actions/cpflow-setup-environment/action.yml
@@ -37,6 +37,12 @@ inputs:
       without publishing a release.
     required: false
     default: ""
+  control_plane_flow_ref:
+    description: >-
+      control-plane-flow GitHub ref used by the calling reusable workflow. When
+      cpflow_version is set, this must be the matching release tag.
+    required: false
+    default: ""
 
 runs:
   using: composite
@@ -83,6 +89,7 @@ runs:
     - name: Install Control Plane CLI and cpflow gem
       shell: bash
       env:
+        CONTROL_PLANE_FLOW_REF: ${{ inputs.control_plane_flow_ref }}
         CPLN_CLI_VERSION: ${{ inputs.cpln_cli_version }}
         CPFLOW_VERSION: ${{ inputs.cpflow_version }}
         CPFLOW_SOURCE_DIR: ${{ github.action_path }}/../../..
@@ -95,6 +102,46 @@ runs:
 
         CPLN_CLI_VERSION="${CPLN_CLI_VERSION:-${default_cpln_cli_version}}"
 
+        normalize_version() {
+          local version="${1#v}"
+
+          if [[ "${version}" =~ ^([0-9]+\.[0-9]+\.[0-9]+)([.-](test|beta|alpha|rc|pre|dev|snapshot|nightly)([.-]?([0-9]+))?)?$ ]]; then
+            if [[ -n "${BASH_REMATCH[3]}" ]]; then
+              echo "${BASH_REMATCH[1]}.${BASH_REMATCH[3]}${BASH_REMATCH[5]:+.${BASH_REMATCH[5]}}"
+            else
+              echo "${BASH_REMATCH[1]}"
+            fi
+          fi
+        }
+
+        normalize_release_ref() {
+          local ref="${1#refs/tags/}"
+
+          [[ "${ref}" == v* ]] || return 0
+          normalize_version "${ref}"
+        }
+
+        validate_cpflow_version_pin() {
+          [[ -z "${CPFLOW_VERSION}" ]] && return 0
+
+          local actual_version
+          local expected_version
+          actual_version="$(normalize_version "${CPFLOW_VERSION}")"
+          expected_version="$(normalize_release_ref "${CONTROL_PLANE_FLOW_REF}")"
+
+          if [[ -z "${expected_version}" ]]; then
+            echo "::error::CPFLOW_VERSION can only be used when control_plane_flow_ref is a release tag like v${CPFLOW_VERSION}. Current control_plane_flow_ref: ${CONTROL_PLANE_FLOW_REF:-<empty>}. Leave CPFLOW_VERSION unset when testing a commit SHA or branch so cpflow is built from the same source as the reusable workflow."
+            exit 1
+          fi
+
+          if [[ "${actual_version}" != "${expected_version}" ]]; then
+            echo "::error::CPFLOW_VERSION must match control_plane_flow_ref. CPFLOW_VERSION=${CPFLOW_VERSION}, normalized CPFLOW_VERSION=${actual_version:-<unrecognized>}, control_plane_flow_ref=${CONTROL_PLANE_FLOW_REF}, expected CPFLOW_VERSION=${expected_version}."
+            exit 1
+          fi
+        }
+
+        validate_cpflow_version_pin
+
         npm_global_prefix="${HOME}/.npm-global"
         mkdir -p "${npm_global_prefix}"
         echo "${npm_global_prefix}/bin" >> "$GITHUB_PATH"
diff --git a/.github/workflows/cpflow-cleanup-stale-review-apps.yml b/.github/workflows/cpflow-cleanup-stale-review-apps.yml
@@ -53,6 +53,7 @@ jobs:
           working_directory: .cpflow
           cpln_cli_version: ${{ vars.CPLN_CLI_VERSION }}
           cpflow_version: ${{ vars.CPFLOW_VERSION }}
+          control_plane_flow_ref: ${{ inputs.control_plane_flow_ref }}
 
       - name: Checkout caller repository
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
diff --git a/.github/workflows/cpflow-delete-review-app.yml b/.github/workflows/cpflow-delete-review-app.yml
@@ -97,6 +97,7 @@ jobs:
           working_directory: app
           cpln_cli_version: ${{ vars.CPLN_CLI_VERSION }}
           cpflow_version: ${{ vars.CPFLOW_VERSION }}
+          control_plane_flow_ref: ${{ inputs.control_plane_flow_ref }}
 
       - name: Set workflow links
         if: steps.config.outputs.ready == 'true'
diff --git a/.github/workflows/cpflow-deploy-review-app.yml b/.github/workflows/cpflow-deploy-review-app.yml
@@ -202,6 +202,7 @@ jobs:
           org: ${{ vars.CPLN_ORG_STAGING }}
           cpln_cli_version: ${{ vars.CPLN_CLI_VERSION }}
           cpflow_version: ${{ vars.CPFLOW_VERSION }}
+          control_plane_flow_ref: ${{ inputs.control_plane_flow_ref }}
           working_directory: app
 
       - name: Detect release phase support
diff --git a/.github/workflows/cpflow-deploy-staging.yml b/.github/workflows/cpflow-deploy-staging.yml
@@ -107,6 +107,7 @@ jobs:
           working_directory: .cpflow
           cpln_cli_version: ${{ vars.CPLN_CLI_VERSION }}
           cpflow_version: ${{ vars.CPFLOW_VERSION }}
+          control_plane_flow_ref: ${{ inputs.control_plane_flow_ref }}
 
       - name: Build Docker image
         uses: ./.cpflow/.github/actions/cpflow-build-docker-image
@@ -145,6 +146,7 @@ jobs:
           working_directory: .cpflow
           cpln_cli_version: ${{ vars.CPLN_CLI_VERSION }}
           cpflow_version: ${{ vars.CPFLOW_VERSION }}
+          control_plane_flow_ref: ${{ inputs.control_plane_flow_ref }}
 
       - name: Detect release phase support
         id: release-phase
diff --git a/.github/workflows/cpflow-promote-staging-to-production.yml b/.github/workflows/cpflow-promote-staging-to-production.yml
@@ -92,6 +92,7 @@ jobs:
           working_directory: .cpflow
           cpln_cli_version: ${{ vars.CPLN_CLI_VERSION }}
           cpflow_version: ${{ vars.CPFLOW_VERSION }}
+          control_plane_flow_ref: ${{ inputs.control_plane_flow_ref }}
 
       # Runs after Setup production environment so the pinned Ruby (>= 3.1) is on PATH.
       # YAML.load_file(..., aliases: true) is not supported on Ruby 3.0 (system Ruby on ubuntu-22.04).
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,6 +12,14 @@ In addition to the standard keepachangelog.com categories, this project uses a l
 
 ## [Unreleased]
 
+### Added
+
+- Added a generated workflow guard that fails early when `CPFLOW_VERSION` does not match the `control_plane_flow_ref` release tag. This prevents review apps from running with reusable workflow/composite action code from one `control-plane-flow` version and a `cpflow` gem from another.
+
+### Fixed
+
+- Fixed generated Control Plane entrypoints so database preparation runs through `./bin/rails`, stops the container on failure, and only runs for Rails server commands instead of every workload sharing the image.
+
 ## [5.0.0] - 2026-05-23
 
 ### Breaking Changes
diff --git a/docs/ci-automation.md b/docs/ci-automation.md
@@ -301,6 +301,13 @@ feature-branch refs.
 pinning the wrappers to the matching `v<version>` tag, or set
 `CPFLOW_VERSION` to that same released gem version without the leading `v`.
 
+The setup action fails early when `CPFLOW_VERSION` and `control_plane_flow_ref`
+are out of sync. `CPFLOW_VERSION=5.0.0` is accepted only when
+`control_plane_flow_ref` is `v5.0.0` (or `refs/tags/v5.0.0`). When testing an
+upstream commit SHA or branch, leave `CPFLOW_VERSION` unset so the workflow
+builds `cpflow` from the same source that supplies the reusable workflow and
+composite actions.
+
 ## Testing Unreleased Upstream Changes Downstream
 
 You can test a `control-plane-flow` PR in a downstream app before merging or
@@ -319,7 +326,10 @@ releasing it. Use an immutable commit SHA from the upstream PR branch:
    local experiments that should not be committed.
 
 3. Keep `CPFLOW_VERSION` unset so the workflow builds `cpflow` from the same
-   upstream SHA that supplies the reusable workflow and composite actions.
+   upstream SHA that supplies the reusable workflow and composite actions. If
+   `CPFLOW_VERSION` is set while `control_plane_flow_ref` is a SHA, the setup
+   action fails before deployment because the gem and action code cannot be
+   proven to match.
 4. Run:
 
    ```sh
diff --git a/lib/generator_templates/entrypoint.sh b/lib/generator_templates/entrypoint.sh
@@ -1,8 +1,25 @@
 #!/bin/sh
+set -e
 # Runs before the main command
 
-echo " -- Preparing database"
-rails db:prepare
+is_rails_server_command() {
+  if [ "${1:-}" = "bundle" ] && [ "${2:-}" = "exec" ]; then
+    shift 2
+  fi
+
+  if [ "${1:-}" = "./bin/thrust" ]; then
+    shift
+  fi
+
+  { [ "${1:-}" = "rails" ] || [ "${1:-}" = "./bin/rails" ]; } &&
+    { [ "${2:-}" = "server" ] || [ "${2:-}" = "s" ]; }
+}
+
+# Match generated Rails server commands; workers and renderers skip DB prep.
+if is_rails_server_command "$@"; then
+  echo " -- Preparing database"
+  ./bin/rails db:prepare
+fi
 
 echo " -- Finishing entrypoint.sh, executing command"
 exec "$@"
diff --git a/lib/github_flow_templates/.github/cpflow-help.md b/lib/github_flow_templates/.github/cpflow-help.md
@@ -70,6 +70,11 @@ For normal releases, point both pins at a release tag such as `v5.0.0`.
 You may leave `CPFLOW_VERSION` unset, or set it to the matching RubyGems version
 without the leading `v`, such as `5.0.0`.
 
+If `CPFLOW_VERSION` is set, the setup action verifies that it matches the
+`control_plane_flow_ref` release tag before installing anything. For example,
+`CPFLOW_VERSION=5.0.0` requires `control_plane_flow_ref: v5.0.0`. A mismatch
+fails the workflow before the review app build/deploy starts.
+
 For temporary downstream testing of an upstream PR before a gem is released, pin
 both values to the exact 40-character commit SHA and leave `CPFLOW_VERSION`
 unset:
diff --git a/spec/command/generate_github_actions_spec.rb b/spec/command/generate_github_actions_spec.rb
@@ -153,6 +153,7 @@ def shared_workflow_path(name)
       contents = setup_action_path.read
       expect(contents).to include("cpln_cli_version:")
       expect(contents).to include('default_cpln_cli_version="3.10.2"')
+      expect(contents).to include("control_plane_flow_ref:")
       expect(reusable_staging_workflow_path.read).to include("cpln_cli_version: ${{ vars.CPLN_CLI_VERSION }}")
       expect(reusable_staging_workflow_path.read).to include("cpflow_version: ${{ vars.CPFLOW_VERSION }}")
     end
@@ -226,8 +227,13 @@ def shared_workflow_path(name)
     it "passes setup action versions through env before using them in shell commands" do
       contents = setup_action_path.read
 
+      expect(contents).to include("CONTROL_PLANE_FLOW_REF: ${{ inputs.control_plane_flow_ref }}")
       expect(contents).to include("CPLN_CLI_VERSION: ${{ inputs.cpln_cli_version }}")
       expect(contents).to include("CPFLOW_VERSION: ${{ inputs.cpflow_version }}")
+      expect(contents).to include("normalize_version")
+      expect(contents).to include("validate_cpflow_version_pin")
+      expect(contents).to include("CPFLOW_VERSION must match control_plane_flow_ref")
+      expect(contents).to include("CPFLOW_VERSION can only be used when control_plane_flow_ref is a release tag")
       expect(contents).to include("ruby/setup-ruby intentionally tracks the v1 tag")
       expect(contents).to include('default_ruby_version="3.2"')
       expect(contents).to include("minimum-supported Ruby advances")
@@ -252,6 +258,30 @@ def shared_workflow_path(name)
       expect(contents).not_to include("gem install cpflow -v ${{ inputs.cpflow_version }}")
     end
 
+    it "passes control_plane_flow_ref to every setup action call for gem/ref validation" do
+      # This validates checked-in reusable workflows, not generated app wrappers.
+      Dir.glob(Cpflow.root_path.join(".github/workflows/cpflow-*.yml").to_s).each do |path|
+        workflow = YAML.load_file(path, aliases: true)
+        workflow_inputs = (workflow["on"] || workflow[true]).fetch("workflow_call").fetch("inputs")
+
+        expect(workflow_inputs).to(
+          have_key("control_plane_flow_ref"),
+          "#{path} must declare control_plane_flow_ref as a workflow_call input"
+        )
+
+        workflow.fetch("jobs").each_value do |job|
+          # Job-level `uses:` entries call reusable workflows; they cannot call composite actions directly.
+          Array(job["steps"]).each do |step|
+            next unless step["uses"] == "./.cpflow/.github/actions/cpflow-setup-environment"
+
+            expect(step.fetch("with")).to include(
+              "control_plane_flow_ref" => "${{ inputs.control_plane_flow_ref }}"
+            ), "#{path} setup action call must pass control_plane_flow_ref"
+          end
+        end
+      end
+    end
+
     it "exposes Docker build action inputs" do
       contents = build_action_path.read
       expect(contents).to include("docker_build_extra_args:")
diff --git a/spec/command/generate_spec.rb b/spec/command/generate_spec.rb
@@ -110,6 +110,11 @@ def generated_ruby_arg
         expect(app_template_content).to include("SECRET_KEY_BASE")
         expect(rails_template_content).to include("minScale: 1")
         expect(rails_template_content).to include("timeoutSeconds: 60")
+        expect(entrypoint_path.read).to include("set -e")
+        expect(entrypoint_path.read).to include("./bin/rails db:prepare")
+        expect(entrypoint_path.read).to include("is_rails_server_command")
+        expect(entrypoint_path.read).to include('[ "${1:-}" = "rails" ]')
+        expect(entrypoint_path.read).to include('[ "${2:-}" = "s" ]')
         expect(entrypoint_path.read).to include('exec "$@"')
         expect(entrypoint_path.read).not_to include("$*")
         expect(postgres_template_path).to exist
