Document cpflow upstream ref pinning

.controlplane/docs/testing-cpflow-github-actions.md

@@ -18,6 +18,48 @@ Control Plane secrets to local composite actions. A PR branch can contain fixed
 `.github/actions/*` files, but the deploy job still loads those local actions
 from `master` until the fix is merged there.
 
+## How Upstream Code Is Pinned
+
+Generated `cpflow-*` workflows are thin wrappers around reusable workflows in
+`shakacode/control-plane-flow`. GitHub reusable workflows cannot be loaded from
+a Ruby gem; GitHub resolves them from a repository ref. Each wrapper therefore
+has two upstream pins that must stay in sync:
+
+```yaml
+uses: shakacode/control-plane-flow/.github/workflows/cpflow-deploy-review-app.yml@<ref>
+with:
+  control_plane_flow_ref: <ref>
+```
+
+`uses: ...@<ref>` chooses the reusable workflow file. `control_plane_flow_ref`
+chooses the same upstream checkout for shared composite actions and, when
+`CPFLOW_VERSION` is unset, the source used to build and install the `cpflow` gem
+inside the workflow.
+
+The stable release path is still gem-driven:
+
+1. Install or update to a released `cpflow` gem.
+2. Run `cpflow generate-github-actions --staging-branch master`.
+3. The generated wrappers use `v<cpflow gem version>` as the upstream ref.
+
+That tag should point to the same source that produced the RubyGems release, so
+the workflow code is locked to a release tag rather than a moving branch. Do not
+pin production workflows to `main` or a feature branch. For unreleased testing,
+pin to an immutable commit SHA, not a branch name, then regenerate or repin to
+the release tag after the upstream release is published.
+
+`CPFLOW_VERSION` is separate from the GitHub workflow ref. If the repository
+variable is set, the setup action runs `gem install cpflow -v <version>`. If it
+is unset, the setup action builds `cpflow` from the checked-out upstream ref.
+For normal releases, either leave `CPFLOW_VERSION` unset while using the matching
+`v<version>` upstream tag, or set `CPFLOW_VERSION` to the same released gem
+version without the leading `v`.
+
+This repo is currently pinned to an upstream commit SHA because the reusable
+workflow change was tested before a new `cpflow` gem release existed. That is
+safer than pinning a branch, but it should be treated as a temporary test pin
+until the next upstream release tag is available.
+
 ## Local Checks
 
 After regenerating the flow, run these checks from the repository root. If

.controlplane/readme.md

@@ -421,6 +421,22 @@ GitHub Actions flow, update a project by regenerating the flow from the desired
 `cpflow` version or branch, reviewing the diff, and keeping any local app names,
 repository variables, secrets, and docs aligned with `.controlplane/controlplane.yml`.
 
+The generated workflows are intentionally thin wrappers around reusable
+workflows in `shakacode/control-plane-flow`. GitHub loads reusable workflows from
+a repository ref, not from the Ruby gem, so each wrapper has a `uses: ...@<ref>`
+line plus a matching `control_plane_flow_ref: <ref>`. For stable releases,
+generate these files from a released `cpflow` gem; the default ref is the
+matching upstream release tag, `v<gem version>`. Avoid `main` or feature-branch
+refs in production. Use an immutable commit SHA only when testing unreleased
+upstream changes, then move back to the release tag after the upstream release
+is published.
+
+`CPFLOW_VERSION` is a runtime gem-install override. When it is unset, the setup
+action builds `cpflow` from the checked-out upstream ref. When it is set, the
+setup action installs that RubyGems version instead. For normal release pins,
+either leave it unset while using the matching `v<version>` workflow tag, or set
+it to the same gem version without the leading `v`.
+
 For this app, validate a regenerated flow with:
 
 ```bash

.controlplane/shakacode-team.md

@@ -51,7 +51,9 @@ Optional repository settings:
 - `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.
 - `CPLN_CLI_VERSION`: pin a specific `@controlplane/cli` version; defaults to the generated action pin.
-- `CPFLOW_VERSION`: pin a specific cpflow gem version; defaults to the generated action pin.
+- `CPFLOW_VERSION`: optional runtime gem-install override. When unset, workflows build
+  `cpflow` from the checked-out upstream workflow ref. When set, use the RubyGems
+  version number without a leading `v`.
 - `HEALTH_CHECK_ACCEPTED_STATUSES`: production promotion health statuses; defaults to `200 301 302`.
 - `HEALTH_CHECK_RETRIES` / `HEALTH_CHECK_INTERVAL`: production health polling controls; defaults to `24` retries and `15` seconds.
 - `ROLLBACK_READINESS_RETRIES` / `ROLLBACK_READINESS_INTERVAL`: post-rollback health polling controls; defaults to `24` retries and `15` seconds.
@@ -71,6 +73,14 @@ that the deploy workflow checks out trusted local actions from `master` before
 passing Control Plane secrets; PR-branch composite action changes are not fully
 tested until they land on `master` and a real review-app deploy is rerun.
 
+Generated workflow wrappers point to upstream reusable workflows with
+`uses: shakacode/control-plane-flow/...@<ref>` and pass the same
+`control_plane_flow_ref`. For stable releases, `<ref>` should be the
+`v<cpflow gem version>` tag produced by the released gem. Do not use `main` or a
+feature branch for production automation. A commit SHA is acceptable for
+unreleased testing, but regenerate or repin to the release tag once the upstream
+release exists.
+
 See [readme.md](readme.md) and
 [Testing cpflow GitHub Actions Changes](docs/testing-cpflow-github-actions.md)
 for more details.

.github/cpflow-help.md

@@ -54,7 +54,7 @@ You asked for review app help. These commands are generated by [cpflow](https://
 | `DOCKER_BUILD_SSH_KNOWN_HOSTS` | optional | SSH known_hosts entries when SSH build hosts are not GitHub.com. |
 | `HEALTH_CHECK_ACCEPTED_STATUSES` | optional | Space-separated HTTP statuses considered healthy on promote (default `200 301 302`). |
 | `CPLN_CLI_VERSION` | optional | Pin a specific `@controlplane/cli` version; falls back to the action default when unset. |
-| `CPFLOW_VERSION` | optional | Pin a specific cpflow gem version; falls back to the generated default when unset. |
+| `CPFLOW_VERSION` | optional | Runtime gem-install override. When unset, cpflow is built from the pinned upstream workflow ref. When set, use the RubyGems version without a leading `v`. |
 
 </details>