From d74319f9888bb2c569b339e1c709d04b0d547e57 Mon Sep 17 00:00:00 2001 From: Justin Gordon Date: Fri, 22 May 2026 21:50:16 -1000 Subject: [PATCH] Document cpflow upstream ref pinning --- .../docs/testing-cpflow-github-actions.md | 42 +++++++++++++++++++ .controlplane/readme.md | 16 +++++++ .controlplane/shakacode-team.md | 12 +++++- .github/cpflow-help.md | 2 +- 4 files changed, 70 insertions(+), 2 deletions(-) diff --git a/.controlplane/docs/testing-cpflow-github-actions.md b/.controlplane/docs/testing-cpflow-github-actions.md index 934ed176..a64a180e 100644 --- a/.controlplane/docs/testing-cpflow-github-actions.md +++ b/.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@ +with: + control_plane_flow_ref: +``` + +`uses: ...@` 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` 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 `. 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` 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 diff --git a/.controlplane/readme.md b/.controlplane/readme.md index 9e946224..9eb511d2 100644 --- a/.controlplane/readme.md +++ b/.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: ...@` +line plus a matching `control_plane_flow_ref: `. For stable releases, +generate these files from a released `cpflow` gem; the default ref is the +matching upstream release tag, `v`. 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` workflow tag, or set +it to the same gem version without the leading `v`. + For this app, validate a regenerated flow with: ```bash diff --git a/.controlplane/shakacode-team.md b/.controlplane/shakacode-team.md index ca03e4a2..bb864651 100644 --- a/.controlplane/shakacode-team.md +++ b/.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/...@` and pass the same +`control_plane_flow_ref`. For stable releases, `` should be the +`v` 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. diff --git a/.github/cpflow-help.md b/.github/cpflow-help.md index 4df158a1..f608d4e5 100644 --- a/.github/cpflow-help.md +++ b/.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`. |