Harden cpflow workflow secret forwarding

justin808 · justin808 · commit 31a8103f397b · 2026-05-24T15:44:17.000-10:00
diff --git a/.controlplane/controlplane.yml b/.controlplane/controlplane.yml
@@ -54,7 +54,7 @@ apps:
     <<: *common
   # QA Apps are like Heroku review apps, but the use `prefix` so you can run a commmand like
   # this to create a QA app for the tutorial app.
-  # `cpflow setup gvc postgres redis rails -a qa-react-webpack-rails-tutorial-pr-1234`
+  # `cpflow setup gvc postgres redis rails -a qa-react-webpack-rails-tutorial-1234`
   qa-react-webpack-rails-tutorial:
     <<: *common
     # Order matters!
diff --git a/.controlplane/docs/testing-cpflow-github-actions.md b/.controlplane/docs/testing-cpflow-github-actions.md
@@ -151,8 +151,8 @@ examples such as `${{ vars.SOME_VALUE }}` can fail action loading before any
 shell step starts. The wrapper runs `cpflow github-flow-readiness`, parses the
 generated YAML, checks action input descriptions for literal GitHub expressions,
 checks that every generated wrapper keeps `uses:` and `control_plane_flow_ref`
-on the same upstream ref across all `cpflow-*` wrappers, checks that any
-secret-inheriting reusable workflow passes `control_plane_flow_ref`, and runs
+on the same upstream ref across all `cpflow-*` wrappers, rejects broad `secrets: inherit` in generated cpflow wrappers, checks that
+any secret-passing reusable workflow passes `control_plane_flow_ref`, and runs
 `actionlint -ignore 'SC2129' .github/workflows/cpflow-*.yml`.
 
 ## PR Checks
diff --git a/.controlplane/readme.md b/.controlplane/readme.md
@@ -74,6 +74,9 @@ or similarly trusted maintainers should be able to approve the promotion job.
 The promotion workflow uses that environment before it can access
 `CPLN_TOKEN_PRODUCTION`, so the production token is not exposed to ordinary
 review-app or staging runs.
+Generated caller workflows pass only the named secrets each upstream workflow
+needs. They do not use `secrets: inherit`; `CPLN_TOKEN_PRODUCTION` is supplied
+only by the protected `production` Environment after approval.
 
 Advanced optional variables:
 
@@ -499,6 +502,7 @@ The GitHub settings and Control Plane resources must match the app names in
 `REVIEW_APP_PREFIX` unset and let the workflow infer
 `qa-react-webpack-rails-tutorial`; generated review apps are named
 `qa-react-webpack-rails-tutorial-<PR number>`.
+If you have older review apps from the previous `qa-react-webpack-rails-tutorial-pr-<PR number>` naming, delete them manually after this flow lands; cleanup targets the current prefix convention.
 
 This allows teams to:
 - Preview changes in a production-like environment
diff --git a/.controlplane/shakacode-team.md b/.controlplane/shakacode-team.md
@@ -39,7 +39,6 @@ Required repository variables for staging deploys:
 - `CPLN_ORG_STAGING=shakacode-open-source-examples-staging`
 - `STAGING_APP_NAME=react-webpack-rails-tutorial-staging`
 - `STAGING_APP_BRANCH=master`
-- `PRIMARY_WORKLOAD=rails`
 
 Review apps infer `CPLN_ORG_STAGING`, `REVIEW_APP_PREFIX`, and
 `PRIMARY_WORKLOAD` from `.controlplane/controlplane.yml` and workflow defaults,
@@ -56,9 +55,13 @@ Production promotion uses a protected GitHub Environment named `production`:
 Protect the `production` environment with required reviewers, enable prevent
 self-review, and consider disabling administrator bypass. Do not store
 `CPLN_TOKEN_PRODUCTION` as a repository or organization secret.
+Generated caller workflows pass only the named secrets each upstream workflow
+needs. They do not use `secrets: inherit`; `CPLN_TOKEN_PRODUCTION` is supplied
+only by the protected `production` Environment after approval.
 
 Optional repository settings:
 
+- `PRIMARY_WORKLOAD`: public workload used for review URLs and promote health checks; defaults to `rails`.
 - `DOCKER_BUILD_SSH_KEY`: secret for private SSH dependencies during Docker builds.
 - `DOCKER_BUILD_EXTRA_ARGS`: newline-delimited Docker build tokens, such as `--build-arg=FOO=bar`.
 - `DOCKER_BUILD_SSH_KNOWN_HOSTS`: custom `known_hosts` entries when SSH build hosts are not GitHub.com.
diff --git a/.github/cpflow-help.md b/.github/cpflow-help.md
@@ -35,7 +35,7 @@ You asked for review app help. These commands are generated by [cpflow](https://
 | Name | Required | Notes |
 | --- | --- | --- |
 | `CPLN_TOKEN_STAGING` | yes | Service-account token scoped to the staging Control Plane org on controlplane.com. |
-| `CPLN_TOKEN_PRODUCTION` | yes (for promote) | Store this as a secret on the protected `production` GitHub Environment, not as a repository or organization secret. |
+| `CPLN_TOKEN_PRODUCTION` | yes for promote, as an environment secret | Store this as a secret on the protected `production` GitHub Environment, not as a repository or organization secret. |
 | `DOCKER_BUILD_SSH_KEY` | optional | Private SSH key used when Docker builds fetch private deps via `RUN --mount=type=ssh`. |
 
 For normal generated review apps, `CPLN_TOKEN_STAGING` is the only required
@@ -54,15 +54,18 @@ For production promotion, create a GitHub Environment named `production`, add
 required reviewers, enable prevent self-review, and store
 `CPLN_TOKEN_PRODUCTION` as an environment secret there. The generated promotion
 workflow uses that environment before it can access production secrets.
+Generated caller workflows pass only the named secrets each upstream workflow
+needs. They do not use `secrets: inherit`; the production token is supplied by
+the protected `production` Environment after approval.
 
 ### GitHub Actions variables
 
 | Name | Required | Notes |
 | --- | --- | --- |
 | `CPLN_ORG_STAGING` | optional for review apps; yes for staging | Override the staging/review Control Plane org inferred from `controlplane.yml`. |
-| `CPLN_ORG_PRODUCTION` | yes (for promote) | Control Plane org on controlplane.com for production. Prefer a `production` environment variable. |
+| `CPLN_ORG_PRODUCTION` | yes for promote, preferably as environment variable | Control Plane org on controlplane.com for production. Prefer a `production` environment variable. |
 | `STAGING_APP_NAME` | yes | App name in `controlplane.yml` used as the staging deploy target. |
-| `PRODUCTION_APP_NAME` | yes (for promote) | App name in `controlplane.yml` used as the production deploy target. Prefer a `production` environment variable. |
+| `PRODUCTION_APP_NAME` | yes for promote, preferably as environment variable | App name in `controlplane.yml` used as the production deploy target. Prefer a `production` environment variable. |
 | `REVIEW_APP_PREFIX` | optional | Override the review-app app key inferred from the `match_if_app_name_starts_with: true` entry in `controlplane.yml`. |
 | `REVIEW_APP_DEPLOYING_ICON_URL` | optional, advanced | Cosmetic custom image URL for the animated deploying icon in review-app PR comments. Set to `none` to use the text fallback icon. |
 | `STAGING_APP_BRANCH` | optional | Custom staging branch. Custom branches must also appear in `cpflow-deploy-staging.yml`'s push filter. |
@@ -75,6 +78,11 @@ workflow uses that environment before it can access production secrets.
 
 </details>
 
+Generated review app names use `<review-app-prefix>-<PR number>`, for example
+`my-app-review-123`. If you are migrating from older local workflow glue that
+created names like `<review-app-prefix>-pr-123`, delete those old review apps
+manually after merging this flow.
+
 <details>
 <summary>Advanced: testing unreleased control-plane-flow changes</summary>
 
diff --git a/.github/workflows/cpflow-cleanup-stale-review-apps.yml b/.github/workflows/cpflow-cleanup-stale-review-apps.yml
@@ -10,7 +10,8 @@ permissions:
 
 jobs:
   cleanup:
-    uses: shakacode/control-plane-flow/.github/workflows/cpflow-cleanup-stale-review-apps.yml@cfe494bf32925d49508380e03856d97bd71f6689
+    uses: shakacode/control-plane-flow/.github/workflows/cpflow-cleanup-stale-review-apps.yml@7d9b80dcb55b243d0cc78b0a85bcb3d568ce8e02
     with:
-      control_plane_flow_ref: cfe494bf32925d49508380e03856d97bd71f6689
-    secrets: inherit
+      control_plane_flow_ref: 7d9b80dcb55b243d0cc78b0a85bcb3d568ce8e02
+    secrets:
+      CPLN_TOKEN_STAGING: ${{ secrets.CPLN_TOKEN_STAGING }}
diff --git a/.github/workflows/cpflow-delete-review-app.yml b/.github/workflows/cpflow-delete-review-app.yml
@@ -26,7 +26,8 @@ jobs:
        contains(fromJson('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)) ||
       (github.event_name == 'pull_request_target' && github.event.action == 'closed') ||
       github.event_name == 'workflow_dispatch'
-    uses: shakacode/control-plane-flow/.github/workflows/cpflow-delete-review-app.yml@cfe494bf32925d49508380e03856d97bd71f6689
+    uses: shakacode/control-plane-flow/.github/workflows/cpflow-delete-review-app.yml@7d9b80dcb55b243d0cc78b0a85bcb3d568ce8e02
     with:
-      control_plane_flow_ref: cfe494bf32925d49508380e03856d97bd71f6689
-    secrets: inherit
+      control_plane_flow_ref: 7d9b80dcb55b243d0cc78b0a85bcb3d568ce8e02
+    secrets:
+      CPLN_TOKEN_STAGING: ${{ secrets.CPLN_TOKEN_STAGING }}
diff --git a/.github/workflows/cpflow-deploy-review-app.yml b/.github/workflows/cpflow-deploy-review-app.yml
@@ -30,7 +30,9 @@ jobs:
        github.event.issue.pull_request &&
        contains(fromJson('["+review-app-deploy","+review-app-deploy\n","+review-app-deploy\r\n"]'), github.event.comment.body) &&
        contains(fromJson('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association))
-    uses: shakacode/control-plane-flow/.github/workflows/cpflow-deploy-review-app.yml@cfe494bf32925d49508380e03856d97bd71f6689
+    uses: shakacode/control-plane-flow/.github/workflows/cpflow-deploy-review-app.yml@7d9b80dcb55b243d0cc78b0a85bcb3d568ce8e02
     with:
-      control_plane_flow_ref: cfe494bf32925d49508380e03856d97bd71f6689
-    secrets: inherit
+      control_plane_flow_ref: 7d9b80dcb55b243d0cc78b0a85bcb3d568ce8e02
+    secrets:
+      CPLN_TOKEN_STAGING: ${{ secrets.CPLN_TOKEN_STAGING }}
+      DOCKER_BUILD_SSH_KEY: ${{ secrets.DOCKER_BUILD_SSH_KEY }}
diff --git a/.github/workflows/cpflow-deploy-staging.yml b/.github/workflows/cpflow-deploy-staging.yml
@@ -16,8 +16,10 @@ permissions:
 
 jobs:
   deploy-staging:
-    uses: shakacode/control-plane-flow/.github/workflows/cpflow-deploy-staging.yml@cfe494bf32925d49508380e03856d97bd71f6689
+    uses: shakacode/control-plane-flow/.github/workflows/cpflow-deploy-staging.yml@7d9b80dcb55b243d0cc78b0a85bcb3d568ce8e02
     with:
-      control_plane_flow_ref: cfe494bf32925d49508380e03856d97bd71f6689
+      control_plane_flow_ref: 7d9b80dcb55b243d0cc78b0a85bcb3d568ce8e02
       staging_app_branch_default: ""
-    secrets: inherit
+    secrets:
+      CPLN_TOKEN_STAGING: ${{ secrets.CPLN_TOKEN_STAGING }}
+      DOCKER_BUILD_SSH_KEY: ${{ secrets.DOCKER_BUILD_SSH_KEY }}
diff --git a/.github/workflows/cpflow-help-command.yml b/.github/workflows/cpflow-help-command.yml
@@ -23,4 +23,6 @@ jobs:
        contains(fromJson('["+review-app-help","+review-app-help\n","+review-app-help\r\n"]'), github.event.comment.body) &&
        contains(fromJson('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)) ||
       github.event_name == 'workflow_dispatch'
-    uses: shakacode/control-plane-flow/.github/workflows/cpflow-help-command.yml@cfe494bf32925d49508380e03856d97bd71f6689
+    uses: shakacode/control-plane-flow/.github/workflows/cpflow-help-command.yml@7d9b80dcb55b243d0cc78b0a85bcb3d568ce8e02
+    with:
+      control_plane_flow_ref: 7d9b80dcb55b243d0cc78b0a85bcb3d568ce8e02
diff --git a/.github/workflows/cpflow-promote-staging-to-production.yml b/.github/workflows/cpflow-promote-staging-to-production.yml
@@ -18,16 +18,15 @@ jobs:
     if: github.event.inputs.confirm_promotion == 'promote'
     # Keep the @ref in `uses:` and `control_plane_flow_ref` below in sync: the
     # first selects the reusable workflow, the second selects its shared actions.
-    uses: shakacode/control-plane-flow/.github/workflows/cpflow-promote-staging-to-production.yml@cfe494bf32925d49508380e03856d97bd71f6689
+    uses: shakacode/control-plane-flow/.github/workflows/cpflow-promote-staging-to-production.yml@7d9b80dcb55b243d0cc78b0a85bcb3d568ce8e02
     with:
-      control_plane_flow_ref: cfe494bf32925d49508380e03856d97bd71f6689
+      control_plane_flow_ref: 7d9b80dcb55b243d0cc78b0a85bcb3d568ce8e02
       # Keep CPLN_TOKEN_PRODUCTION as a secret on this protected GitHub
       # Environment. Required reviewers approve the job before GitHub exposes
       # environment secrets to the upstream reusable workflow.
       production_environment: production
-    # `secrets: inherit` passes all caller repository secrets to the trusted
-    # upstream workflow. The upstream workflow only reads the named secrets it
-    # references, but GitHub does not enforce that boundary. Strict consumers can
-    # keep both the `uses:` ref and `control_plane_flow_ref` pinned to an
-    # immutable commit SHA.
-    secrets: inherit
+    # Only pass the staging token explicitly. CPLN_TOKEN_PRODUCTION must live on
+    # the protected production Environment, where GitHub exposes it only after
+    # the required reviewers approve this job.
+    secrets:
+      CPLN_TOKEN_STAGING: ${{ secrets.CPLN_TOKEN_STAGING }}
diff --git a/.github/workflows/cpflow-review-app-help.yml b/.github/workflows/cpflow-review-app-help.yml
@@ -14,4 +14,6 @@ permissions:
 
 jobs:
   show-help:
-    uses: shakacode/control-plane-flow/.github/workflows/cpflow-review-app-help.yml@cfe494bf32925d49508380e03856d97bd71f6689
+    uses: shakacode/control-plane-flow/.github/workflows/cpflow-review-app-help.yml@7d9b80dcb55b243d0cc78b0a85bcb3d568ce8e02
+    with:
+      control_plane_flow_ref: 7d9b80dcb55b243d0cc78b0a85bcb3d568ce8e02
diff --git a/bin/test-cpflow-github-flow b/bin/test-cpflow-github-flow
@@ -55,6 +55,10 @@ Dir[".github/workflows/cpflow-*.yml"].sort.each do |path|
     input_ref = with["control_plane_flow_ref"]
     uses_match = job["uses"].to_s.match(CONTROL_PLANE_FLOW_WORKFLOW)
 
+    if job["secrets"] == "inherit"
+      abort "#{path}:#{job_name} uses secrets: inherit; pass only the named secrets the upstream workflow needs"
+    end
+
     unless uses_match
       abort "#{path}:#{job_name} has control_plane_flow_ref but no control-plane-flow reusable workflow" if input_ref
 
@@ -68,7 +72,7 @@ Dir[".github/workflows/cpflow-*.yml"].sort.each do |path|
       refs[input_ref] << "#{path}:#{job_name}"
       abort "#{path}:#{job_name} mismatched cpflow refs: #{uses_ref}, #{input_ref}" if uses_ref != input_ref
     elsif job.key?("secrets")
-      abort "#{path}:#{job_name} inherits secrets but is missing control_plane_flow_ref for #{uses_ref}"
+      abort "#{path}:#{job_name} passes secrets but is missing control_plane_flow_ref for #{uses_ref}"
     end
   end
 end
