cpflow 5.0.0 → 5.0.1

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

@@ -4,12 +4,13 @@ run-name: "Deploy Review App - PR #${{ github.event.pull_request.number || githu
 
 on:
   workflow_call:
-    inputs:
-      control_plane_flow_ref:
-        description: Git ref used to load shared cpflow composite actions.
+    secrets:
+      CPLN_TOKEN_STAGING:
+        description: Control Plane token for the staging org that owns review apps.
+        required: true
+      DOCKER_BUILD_SSH_KEY:
+        description: Optional SSH key used by Docker builds that fetch private dependencies.
         required: false
-        type: string
-        default: main
 
 permissions:
   contents: read
@@ -25,8 +26,6 @@ concurrency:
   cancel-in-progress: false
 
 env:
-  APP_NAME: ${{ vars.REVIEW_APP_PREFIX }}-${{ github.event.pull_request.number || github.event.issue.number || github.event.inputs.pr_number }}
-  CPLN_ORG: ${{ vars.CPLN_ORG_STAGING }}
   PR_NUMBER: ${{ github.event.pull_request.number || github.event.issue.number || github.event.inputs.pr_number }}
   PRIMARY_WORKLOAD: ${{ vars.PRIMARY_WORKLOAD }}
 
@@ -72,8 +71,8 @@ jobs:
       - name: Checkout control-plane-flow actions
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
         with:
-          repository: shakacode/control-plane-flow
-          ref: ${{ inputs.control_plane_flow_ref }}
+          repository: ${{ job.workflow_repository }}
+          ref: ${{ job.workflow_sha }}
           path: .cpflow
           persist-credentials: false
 
@@ -82,13 +81,9 @@ jobs:
         uses: ./.cpflow/.github/actions/cpflow-validate-config
         env:
           CPLN_TOKEN_STAGING: ${{ secrets.CPLN_TOKEN_STAGING }}
-          CPLN_ORG_STAGING: ${{ vars.CPLN_ORG_STAGING }}
-          REVIEW_APP_PREFIX: ${{ vars.REVIEW_APP_PREFIX }}
         with:
           required: |
             secret:CPLN_TOKEN_STAGING
-            variable:CPLN_ORG_STAGING
-            variable:REVIEW_APP_PREFIX
           pull_request_friendly: "true"
 
       - name: Resolve PR ref and commit
@@ -106,7 +101,6 @@ jobs:
           DISPATCH_PR_NUMBER: ${{ github.event.inputs.pr_number }}
           ISSUE_NUMBER: ${{ github.event.issue.number }}
           PR_EVENT_NUMBER: ${{ github.event.pull_request.number }}
-          REVIEW_APP_PREFIX: ${{ vars.REVIEW_APP_PREFIX }}
         shell: bash
         run: |
           set -euo pipefail
@@ -137,7 +131,6 @@ jobs:
           fi
 
           echo "PR_NUMBER=$pr_number" >> "$GITHUB_ENV"
-          echo "APP_NAME=${REVIEW_APP_PREFIX}-$pr_number" >> "$GITHUB_ENV"
           echo "PR_SHA=$pr_sha" >> "$GITHUB_ENV"
           echo "same_repo=${same_repo}" >> "$GITHUB_OUTPUT"
 
@@ -194,14 +187,25 @@ jobs:
           set -euo pipefail
           rm -rf app/.git
 
+      - name: Resolve review app config
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true'
+        id: review-config
+        uses: ./.cpflow/.github/actions/cpflow-resolve-review-config
+        with:
+          working_directory: app
+          configured_cpln_org_staging: ${{ vars.CPLN_ORG_STAGING }}
+          configured_review_app_prefix: ${{ vars.REVIEW_APP_PREFIX }}
+          pr_number: ${{ env.PR_NUMBER }}
+
       - name: Setup environment
         if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true'
         uses: ./.cpflow/.github/actions/cpflow-setup-environment
         with:
           token: ${{ secrets.CPLN_TOKEN_STAGING }}
-          org: ${{ vars.CPLN_ORG_STAGING }}
+          org: ${{ steps.review-config.outputs.cpln_org }}
           cpln_cli_version: ${{ vars.CPLN_CLI_VERSION }}
           cpflow_version: ${{ vars.CPFLOW_VERSION }}
+          control_plane_flow_ref: ${{ job.workflow_ref }}
           working_directory: app
 
       - name: Detect release phase support
@@ -209,7 +213,7 @@ jobs:
         id: release-phase
         uses: ./.cpflow/.github/actions/cpflow-detect-release-phase
         with:
-          app_name: ${{ env.APP_NAME }}
+          app_name: ${{ steps.review-config.outputs.app_name }}
           working_directory: app
 
       - name: Check if review app exists
@@ -355,8 +359,8 @@ jobs:
         if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true' && (steps.check-app.outputs.exists == 'true' || steps.setup-review-app.outcome == 'success')
         uses: ./.cpflow/.github/actions/cpflow-build-docker-image
         with:
-          app_name: ${{ env.APP_NAME }}
-          org: ${{ vars.CPLN_ORG_STAGING }}
+          app_name: ${{ steps.review-config.outputs.app_name }}
+          org: ${{ steps.review-config.outputs.cpln_org }}
           commit: ${{ env.PR_SHA }}
           pr_number: ${{ env.PR_NUMBER }}
           docker_build_extra_args: ${{ vars.DOCKER_BUILD_EXTRA_ARGS }}

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

@@ -5,16 +5,18 @@ run-name: Deploy Control Plane staging app
 on:
   workflow_call:
     inputs:
-      control_plane_flow_ref:
-        description: Git ref used to load shared cpflow composite actions.
-        required: false
-        type: string
-        default: main
       staging_app_branch_default:
         description: Fallback branch name baked into the generated caller workflow.
         required: false
         type: string
         default: ""
+    secrets:
+      CPLN_TOKEN_STAGING:
+        description: Control Plane token for the staging org.
+        required: true
+      DOCKER_BUILD_SSH_KEY:
+        description: Optional SSH key used by Docker builds that fetch private dependencies.
+        required: false
 
 permissions:
   contents: read
@@ -62,8 +64,8 @@ jobs:
         if: steps.check-branch.outputs.is_deployable == 'true'
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
         with:
-          repository: shakacode/control-plane-flow
-          ref: ${{ inputs.control_plane_flow_ref }}
+          repository: ${{ job.workflow_repository }}
+          ref: ${{ job.workflow_sha }}
           path: .cpflow
           persist-credentials: false
 
@@ -94,8 +96,8 @@ jobs:
       - name: Checkout control-plane-flow actions
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
         with:
-          repository: shakacode/control-plane-flow
-          ref: ${{ inputs.control_plane_flow_ref }}
+          repository: ${{ job.workflow_repository }}
+          ref: ${{ job.workflow_sha }}
           path: .cpflow
           persist-credentials: false
 
@@ -107,6 +109,7 @@ jobs:
           working_directory: .cpflow
           cpln_cli_version: ${{ vars.CPLN_CLI_VERSION }}
           cpflow_version: ${{ vars.CPFLOW_VERSION }}
+          control_plane_flow_ref: ${{ job.workflow_ref }}
 
       - name: Build Docker image
         uses: ./.cpflow/.github/actions/cpflow-build-docker-image
@@ -132,8 +135,8 @@ jobs:
       - name: Checkout control-plane-flow actions
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
         with:
-          repository: shakacode/control-plane-flow
-          ref: ${{ inputs.control_plane_flow_ref }}
+          repository: ${{ job.workflow_repository }}
+          ref: ${{ job.workflow_sha }}
           path: .cpflow
           persist-credentials: false
 
@@ -145,6 +148,7 @@ jobs:
           working_directory: .cpflow
           cpln_cli_version: ${{ vars.CPLN_CLI_VERSION }}
           cpflow_version: ${{ vars.CPFLOW_VERSION }}
+          control_plane_flow_ref: ${{ job.workflow_ref }}
 
       - name: Detect release phase support
         id: release-phase

data/.github/workflows/cpflow-help-command.yml

@@ -2,12 +2,6 @@ name: Review App Help Command
 
 on:
   workflow_call:
-    inputs:
-      control_plane_flow_ref:
-        description: Accepted for generated wrapper consistency; unused because this workflow checks out caller content only.
-        required: false
-        type: string
-        default: main
 
 permissions:
   contents: read

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

@@ -3,11 +3,18 @@ name: Promote Staging to Production
 on:
   workflow_call:
     inputs:
-      control_plane_flow_ref:
-        description: Git ref used to load shared cpflow composite actions.
+      production_environment:
+        description: GitHub Environment that protects production promotion and stores production-only secrets.
         required: false
         type: string
-        default: main
+        default: production
+    secrets:
+      CPLN_TOKEN_STAGING:
+        description: Control Plane token for reading the already-deployed staging image.
+        required: true
+      CPLN_TOKEN_PRODUCTION:
+        description: Production Control Plane token. Store it on the protected production Environment; do not pass it from a repository secret.
+        required: false
 
 permissions:
   contents: read
@@ -48,6 +55,10 @@ jobs:
   promote-to-production:
     if: github.event.inputs.confirm_promotion == 'promote'
     runs-on: ubuntu-latest
+    # GitHub uses secrets from this protected Environment for jobs that declare
+    # it, so CPLN_TOKEN_PRODUCTION should be configured only there. The caller
+    # wrapper intentionally passes only CPLN_TOKEN_STAGING.
+    environment: ${{ inputs.production_environment }}
     timeout-minutes: 45
 
     steps:
@@ -59,11 +70,24 @@ jobs:
       - name: Checkout control-plane-flow actions
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
         with:
-          repository: shakacode/control-plane-flow
-          ref: ${{ inputs.control_plane_flow_ref }}
+          repository: ${{ job.workflow_repository }}
+          ref: ${{ job.workflow_sha }}
           path: .cpflow
           persist-credentials: false
 
+      - name: Validate production token
+        shell: bash
+        env:
+          CPLN_TOKEN_PRODUCTION: ${{ secrets.CPLN_TOKEN_PRODUCTION }}
+          PRODUCTION_ENVIRONMENT: ${{ inputs.production_environment }}
+        run: |
+          set -euo pipefail
+
+          if [[ -z "${CPLN_TOKEN_PRODUCTION}" ]]; then
+            echo "::error::CPLN_TOKEN_PRODUCTION is not set. Add it as a secret on the '${PRODUCTION_ENVIRONMENT}' GitHub Environment."
+            exit 1
+          fi
+
       - name: Validate required secrets and variables
         uses: ./.cpflow/.github/actions/cpflow-validate-config
         # Pass secrets via env so the composite action checks indirect shell
@@ -92,6 +116,7 @@ jobs:
           working_directory: .cpflow
           cpln_cli_version: ${{ vars.CPLN_CLI_VERSION }}
           cpflow_version: ${{ vars.CPFLOW_VERSION }}
+          control_plane_flow_ref: ${{ job.workflow_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).

data/.github/workflows/cpflow-review-app-help.yml

@@ -2,12 +2,6 @@ name: Show Review App Commands on PR Open
 
 on:
   workflow_call:
-    inputs:
-      control_plane_flow_ref:
-        description: Accepted for generated wrapper consistency; unused because this workflow does not check out shared actions.
-        required: false
-        type: string
-        default: main
 
 permissions:
   issues: write
@@ -15,10 +9,6 @@ permissions:
 
 jobs:
   show-help:
-    # Skip on PRs in repos that have not configured the cpflow review app flow yet,
-    # so this workflow does not noisily comment on every contributor PR. Once the
-    # repository sets `vars.REVIEW_APP_PREFIX`, the help message starts appearing.
-    if: vars.REVIEW_APP_PREFIX != ''
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
@@ -30,6 +20,7 @@ jobs:
               "# 🚀 Quick Review App Commands",
               "",
               "Welcome! Here are the commands you can use in this PR:",
+              "They require the repository to have cpflow review apps configured, including the `CPLN_TOKEN_STAGING` secret.",
               "",
               "### `+review-app-deploy`",
               "Deploy your PR branch for testing.",

data/CHANGELOG.md

@@ -12,6 +12,27 @@ In addition to the standard keepachangelog.com categories, this project uses a l
 
 ## [Unreleased]
 
+## [5.0.1] - 2026-05-24
+
+### Breaking Changes
+
+- BREAKING CHANGE: Generated GitHub Actions wrappers now pin Control Plane Flow only through the `uses: shakacode/control-plane-flow/...@<ref>` line and no longer accept downstream `control_plane_flow_ref` inputs. Repositories with older generated wrappers must regenerate or remove `control_plane_flow_ref` from `with:` blocks to avoid validation failures. [PR 321](https://github.com/shakacode/control-plane-flow/pull/321) by [Justin Gordon](https://github.com/justin808).
+
+### Changed
+
+- **Simplified generated review-app help docs to a compact command/setup reference and moved extended guidance to upstream CI automation docs.** [PR 319](https://github.com/shakacode/control-plane-flow/pull/319) by [Justin Gordon](https://github.com/justin808).
+- **Clarified generated PR-open help opt-out guidance for forks and clones, including a sample job `if:` guard in generated wrappers.** [PR 323](https://github.com/shakacode/control-plane-flow/pull/323) by [Justin Gordon](https://github.com/justin808).
+- **Improved generated GitHub Actions ref/gem alignment checks so `CPFLOW_VERSION` must match the ref pinned via `uses: shakacode/control-plane-flow/...@<ref>`, and setup validates the checked-out action code against the remote tag/commit for that ref.** [PR 318](https://github.com/shakacode/control-plane-flow/pull/318) by [Justin Gordon](https://github.com/justin808).
+- **Improved review-app workflow config inference so generated deploy/delete/cleanup workflows can derive the review-app prefix and staging Control Plane org from `.controlplane/controlplane.yml`; testing review apps normally requires only the `CPLN_TOKEN_STAGING` secret.** [PR 318](https://github.com/shakacode/control-plane-flow/pull/318) by [Justin Gordon](https://github.com/justin808).
+- **Improved production promotion safety docs and generated workflow validation for using a protected `production` GitHub Environment with required reviewers and a production-only `CPLN_TOKEN_PRODUCTION` environment secret.** [PR 318](https://github.com/shakacode/control-plane-flow/pull/318) by [Justin Gordon](https://github.com/justin808).
+
+### Fixed
+
+- **Fixed generated Control Plane entrypoints so database preparation runs through `./bin/rails`, fails fast, and runs only for generated Rails server commands instead of every workload sharing the image.** [PR 318](https://github.com/shakacode/control-plane-flow/pull/318) by [Justin Gordon](https://github.com/justin808). Generated Dockerfiles run from `WORKDIR /app`; apps with custom Dockerfiles that run the entrypoint from another directory should adjust the `./bin/rails db:prepare` path after regenerating. Apps with hand-edited `.controlplane/entrypoint.sh` files should audit custom commands when regenerating, especially Thruster invocations with custom flags and startup paths that relied on continuing after a failed database connection.
+- **Fixed generated Dockerfiles so copied Control Plane entrypoints are marked executable inside the image even if the source file mode is lost.** [PR 318](https://github.com/shakacode/control-plane-flow/pull/318) by [Justin Gordon](https://github.com/justin808).
+- **Fixed generated review-app deploy/delete/cleanup workflows so they use one shared `cpflow-resolve-review-config` composite action instead of duplicated YAML parsing logic.** [PR 318](https://github.com/shakacode/control-plane-flow/pull/318) by [Justin Gordon](https://github.com/justin808).
+- **Fixed generated production-promotion caller wrappers so they pass only `CPLN_TOKEN_STAGING`; `CPLN_TOKEN_PRODUCTION` remains on the protected GitHub Environment where GitHub exposes it after approval.** [PR 318](https://github.com/shakacode/control-plane-flow/pull/318) by [Justin Gordon](https://github.com/justin808).
+
 ## [5.0.0] - 2026-05-23
 
 ### Breaking Changes
@@ -353,7 +374,8 @@ Deprecated `cpl` gem. New gem is `cpflow`.
 
 First release.
 
-[Unreleased]: https://github.com/shakacode/control-plane-flow/compare/v5.0.0...HEAD
+[Unreleased]: https://github.com/shakacode/control-plane-flow/compare/v5.0.1...HEAD
+[5.0.1]: https://github.com/shakacode/control-plane-flow/compare/v5.0.0...v5.0.1
 [5.0.0]: https://github.com/shakacode/control-plane-flow/compare/v5.0.0.rc.3...v5.0.0
 [5.0.0.rc.3]: https://github.com/shakacode/control-plane-flow/compare/v5.0.0.rc.1...v5.0.0.rc.3
 [5.0.0.rc.1]: https://github.com/shakacode/control-plane-flow/compare/v4.2.0...v5.0.0.rc.1

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cpflow (5.0.0)
+    cpflow (5.0.1)
       dotenv (~> 3.1)
       jwt (~> 3.1)
       psych (~> 5.2)

data/docs/ai-github-flow-prompt.md

@@ -20,7 +20,7 @@ prompt tells the agent to stop on.
 ```text
 Set up Control Plane GitHub Flow for this repo. Start with `cpflow github-flow-readiness` and stop on any reported blockers. The repo must be deployable from a clean clone: published package versions, complete runtime scaffold, and a production Dockerfile that can build the app. If any package version is unpublished, inaccessible from CI, or requires credentials that are not already modeled in the repo or GitHub settings, stop and report the blocker instead of generating workflow files. If the repo is a legacy sample pinned to an obsolete Ruby or Bundler toolchain, if it does not even have a production Dockerfile yet, or if it is a monorepo without an already-decided single app boundary for this flow, stop and report that as a prerequisite instead of forcing the rollout.
 
-If `.controlplane/` is missing, run `cpflow generate`. Treat the generated app names as the repo-name default and rename them only if the project needs a different prefix. Then run `cpflow generate-github-actions` (or `cpflow generate-github-actions --staging-branch BRANCH` when staging should deploy from a branch other than `main`/`master`), keep review apps opt-in via `+review-app-deploy`, make sure any `STAGING_APP_BRANCH` repository variable is also present in the generated staging workflow's `on.push.branches` filter, and list the GitHub secrets and variables that must be configured.
+If `.controlplane/` is missing, run `cpflow generate`. Treat the generated app names as the repo-name default and rename them only if the project needs a different prefix. Then run `cpflow generate-github-actions` (or `cpflow generate-github-actions --staging-branch BRANCH` when staging should deploy from a branch other than `main`/`master`), keep review apps opt-in via `+review-app-deploy`, make sure any `STAGING_APP_BRANCH` repository variable is also present in the generated staging workflow's `on.push.branches` filter, and list the GitHub secrets and variables that must be configured. Do not hand-edit duplicated upstream refs into the generated wrappers: the only downstream Control Plane Flow pin should be the reusable workflow `uses: ...@vX.Y.Z` value generated from the installed `cpflow` gem version, and upstream workflows load their matching shared actions automatically. Keep the standard path simple: review apps require only `CPLN_TOKEN_STAGING` when the generated review app config can be inferred. For production promotion, document a protected `production` GitHub Environment with required reviewers, prevent self-review, and `CPLN_TOKEN_PRODUCTION` stored as an environment secret, not as a repository or organization secret.
 
 Keep Node available in the final image if asset compilation or SSR depends on ExecJS, Yarn, `pnpm`, or npm after the main install layer. Make sure the generated Dockerfile uses a Ruby base image compatible with the app's declared Ruby requirement. Preserve repo-defined frontend build hooks: if `config/shakapacker.yml` defines a `precompile_hook`, or React on Rails enables `config.auto_load_bundle = true`, confirm the generated Dockerfile runs that codegen step before `rails assets:precompile`. If `config/database.yml` shows SQLite in production, confirm that the generated scaffold uses persistent `db` and `storage` volumes plus a release script that runs `rails db:prepare`; otherwise keep the default Postgres workload. If the public workload is not named `rails`, set `PRIMARY_WORKLOAD` or adjust the generated workflows. Inspect the Dockerfile and package sources for private GitHub dependencies or `RUN --mount=type=ssh`; if present, wire `DOCKER_BUILD_SSH_KEY`, optionally set `DOCKER_BUILD_SSH_KNOWN_HOSTS` for non-GitHub SSH hosts, and keep `DOCKER_BUILD_EXTRA_ARGS` to newline-delimited single tokens such as `--build-arg=FOO=bar`.