cpflow 5.0.2 → 5.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6a3d49d8db4d5df28b82fa8cfb81af3470299d485169997c2904c683b1a56c6
-  data.tar.gz: 48cacf78f5d61ca95405b46e152b26547536a3862a06d93433efaa7c52f7f85d
+  metadata.gz: 4ae89eb9d37d93ce9d6e22fa42d4210cce3183505a00ee91cee172e47cb9750b
+  data.tar.gz: ba697c7e72c80ae792feb52b47f42db38180c63af42ab7959650ce1b757d0201
 SHA512:
-  metadata.gz: 9158740f20c83981417325473f6f9d3b27fee1e0967b31746d44f32d4d6e0dca2d14ab17dfd05d2f27a10a745b33e663cc775c562919fdaa2311e554cddfb2af
-  data.tar.gz: c822be6375f28c6c01e13b397f5857fa4d3cd8463cc787cd6dc9be5a6f4967aa17a84af19f4e31c6b565e8325e19286de1c0fa398c22db4966a3f723e7adfb1a
+  metadata.gz: d8e9ed791d7c2401b598b2ca8aefd33b363d609baca9193b678c828eaf4ba286ce3b1177a9cbe4dee5d3c6bdaf03648d77d1d8ecc2c86b384bd123625cf38038
+  data.tar.gz: 972e3a9a8db47d3875363ab969efd14038181147b2e31ab3ad80de6d062b00d0674d4be76d53f7f470763f663b4a762568c174399c0d482c787fe4e8a1b6f79e

data/.github/workflows/rspec.yml

@@ -4,7 +4,17 @@ on:
   push:
     branches:
       - main
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+      - 'LICENSE'
+      - 'COMM-LICENSE.txt'
   pull_request:
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+      - 'LICENSE'
+      - 'COMM-LICENSE.txt'
   workflow_dispatch:
 
 jobs:

data/.github/workflows/rubocop.yml

@@ -4,7 +4,17 @@ on:
   push:
     branches:
       - main
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+      - 'LICENSE'
+      - 'COMM-LICENSE.txt'
   pull_request:
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+      - 'LICENSE'
+      - 'COMM-LICENSE.txt'
 
 jobs:
   rubocop:

data/.github/workflows/trigger-docs-site.yml

@@ -34,7 +34,7 @@ jobs:
     timeout-minutes: 5
     steps:
       - name: Generate GitHub App token
-        uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1.12.0
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
         id: app-token
         with:
           app-id: ${{ secrets.DOCS_DISPATCH_APP_ID }}
@@ -44,7 +44,7 @@ jobs:
 
       - name: Dispatch docs-updated event
         id: dispatch
-        uses: peter-evans/repository-dispatch@ff45666b9427631e3450c54a1bcbee4d9ff4d7c0 # v3.0.0
+        uses: peter-evans/repository-dispatch@28959ce8df70de7be546dd1250a005dd32156697 # v4.0.1
         with:
           token: ${{ steps.app-token.outputs.token }}
           repository: shakacode/controlplaneflow-com

data/CHANGELOG.md

@@ -12,6 +12,16 @@ In addition to the standard keepachangelog.com categories, this project uses a l
 
 ## [Unreleased]
 
+## [5.0.3] - 2026-05-26
+
+### Changed
+
+- **Changed `cpflow update-github-actions`, `cpflow generate-github-actions --force`, RubyGems install guidance, and release-task follow-up output so downstream repositories remember to update checked-in generated GitHub Actions wrappers when the `cpflow` gem version changes.** [PR 328](https://github.com/shakacode/control-plane-flow/pull/328) by [Justin Gordon](https://github.com/justin808).
+
+### Fixed
+
+- **Fixed `cpflow update-github-actions` so reordered default staging branches remain defaults, empty or non-hash staging workflow YAML no longer crashes, and fresh repos fail with a clear `generate-github-actions` instruction instead of silently creating wrappers.** [PR 331](https://github.com/shakacode/control-plane-flow/pull/331) by [Justin Gordon](https://github.com/justin808). Clarified the RubyGems post-install message so first-time installers see the `generate-github-actions` path.
+
 ## [5.0.2] - 2026-05-25
 
 ### Fixed
@@ -382,7 +392,8 @@ Deprecated `cpl` gem. New gem is `cpflow`.
 
 First release.
 
-[Unreleased]: https://github.com/shakacode/control-plane-flow/compare/v5.0.2...HEAD
+[Unreleased]: https://github.com/shakacode/control-plane-flow/compare/v5.0.3...HEAD
+[5.0.3]: https://github.com/shakacode/control-plane-flow/compare/v5.0.2...v5.0.3
 [5.0.2]: https://github.com/shakacode/control-plane-flow/compare/v5.0.1...v5.0.2
 [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

data/Gemfile.lock

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

data/cpflow.gemspec

@@ -12,6 +12,23 @@ Gem::Specification.new do |spec|
   spec.description = "CLI for providing Heroku-like platform-as-a-service on Control Plane"
   spec.homepage    = "https://github.com/shakacode/control-plane-flow"
   spec.license     = "MIT"
+  spec.post_install_message = <<~MESSAGE
+    cpflow #{Cpflow::VERSION} installed.
+
+    If this repository already uses generated cpflow GitHub Actions, update the
+    checked-in wrappers so GitHub loads the matching control-plane-flow release tag:
+
+      cpflow update-github-actions
+      bin/test-cpflow-github-flow
+
+    If you run cpflow through Bundler:
+
+      bundle exec cpflow update-github-actions
+      bin/test-cpflow-github-flow bundle exec cpflow
+
+    New repository? Run `cpflow generate-github-actions` first to create the
+    wrappers (and the `bin/test-cpflow-github-flow` script referenced above).
+  MESSAGE
 
   spec.required_ruby_version = ">= 3.0.0"
 

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. 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. Document the one-time Control Plane bootstrap command for persistent staging and production apps with `cpflow setup-app --skip-post-creation-hook`; for existing apps or later template updates, document `cpflow apply-template` and the need for the app identity to have `reveal` on the app secret policy. Do not imply the staging deploy or promotion workflows create those persistent GVCs. 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.
+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. When bumping the `cpflow` gem in a downstream repo, run `cpflow update-github-actions` (or `bundle exec cpflow update-github-actions`) and validate with `bin/test-cpflow-github-flow` in the same PR so the checked-in wrappers move to the matching release tag. Keep the standard path simple: review apps require only `CPLN_TOKEN_STAGING` when the generated review app config can be inferred. Document the one-time Control Plane bootstrap command for persistent staging and production apps with `cpflow setup-app --skip-post-creation-hook`; for existing apps or later template updates, document `cpflow apply-template` and the need for the app identity to have `reveal` on the app secret policy. Do not imply the staging deploy or promotion workflows create those persistent GVCs. 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`.
 

data/docs/ci-automation.md

@@ -455,6 +455,43 @@ That release tag should point to the same source that produced the RubyGems
 release. Downstream production automation should use release tags, not `main` or
 feature-branch refs.
 
+## Updating Generated GitHub Actions After Gem Updates
+
+Whenever a downstream repo updates the `cpflow` gem, update the checked-in
+GitHub Actions wrappers in the same PR. The gem version does not make GitHub load
+new reusable workflow YAML by itself; GitHub loads the `uses:` ref committed in
+`.github/workflows/cpflow-*.yml`.
+
+Use the installed gem to refresh the generated wrappers:
+
+```sh
+cpflow update-github-actions
+bin/test-cpflow-github-flow
+```
+
+If the app runs `cpflow` through Bundler, use:
+
+```sh
+bundle exec cpflow update-github-actions
+bin/test-cpflow-github-flow bundle exec cpflow
+```
+
+`cpflow update-github-actions` regenerates the generated wrapper and helper
+files from the installed gem, pins the wrapper `uses:` refs to `v<gem-version>`,
+and preserves a single custom staging branch from the existing generated staging
+workflow. Pass `--staging-branch BRANCH` when changing or restoring a custom
+staging branch explicitly.
+
+When keeping `cpflow` in an app Gemfile, leave a comment next to the gem entry
+so future dependency bumps include the wrapper update:
+
+```ruby
+# After bumping cpflow, run:
+#   bundle exec cpflow update-github-actions
+#   bin/test-cpflow-github-flow bundle exec cpflow
+gem "cpflow", "5.0.1"
+```
+
 `CPFLOW_VERSION` is a runtime override. If a downstream repository sets the
 `CPFLOW_VERSION` variable, the setup action runs `gem install cpflow -v
 <version>`. If it is unset, the setup action builds `cpflow` from the checked-out

data/docs/commands.md

@@ -218,6 +218,9 @@ Creates GitHub Actions templates for a Heroku Flow style Control Plane pipeline:
 Pass `--staging-branch BRANCH` when staging should auto-deploy from a branch
 other than `main` or `master`; the generator will bake that branch into the
 GitHub Actions push trigger and use it as the default STAGING_APP_BRANCH.
+Pass `--force` to overwrite existing generated files. Prefer
+`cpflow update-github-actions` after bumping the cpflow gem in a downstream
+repo.
 
 ```sh
 # Creates thin .github/workflows wrappers for the Control Plane flow
@@ -225,6 +228,9 @@ cpflow generate-github-actions
 
 # Creates the flow with staging deploys triggered from develop
 cpflow generate-github-actions --staging-branch develop
+
+# Overwrites existing generated wrappers from the installed cpflow gem
+cpflow generate-github-actions --force
 ```
 
 ### `github-flow-readiness`
@@ -533,6 +539,28 @@ cpflow terraform generate
 cpflow terraform import
 ```
 
+### `update-github-actions`
+
+Regenerates the generated cpflow GitHub Actions wrappers and helper files
+from the currently installed cpflow gem. Use this after updating the
+cpflow gem so checked-in workflow wrappers move to the matching upstream
+release tag, for example `v5.0.2`.
+
+If the existing generated staging workflow uses a custom single staging
+branch, the command preserves it. Pass `--staging-branch BRANCH` to set or
+replace the generated staging branch explicitly.
+
+```sh
+# After updating the cpflow gem, refresh generated GitHub Actions wrappers
+cpflow update-github-actions
+
+# When running cpflow through Bundler
+bundle exec cpflow update-github-actions
+
+# Preserve or set a custom staging branch
+cpflow update-github-actions --staging-branch develop
+```
+
 ### `version`
 
 - Displays the current version of the CLI

data/docs/releasing.md

@@ -99,6 +99,8 @@ GEM_RELEASE_MAX_RETRIES=<n>
 9. Commits the version bump, tags `vX.Y.Z`, and pushes the commit and tags.
 10. Publishes the `cpflow` gem to RubyGems.org.
 11. Creates or updates the GitHub release from the matching changelog section.
+12. Prints the downstream GitHub Actions follow-up command:
+    `cpflow update-github-actions`.
 
 The older `bundle exec rake "create_release[4.2.0,false]"` task name remains as
 a compatibility alias, but new releases should use `bundle exec rake release`.

data/lib/command/ai_github_flow_prompt.rb

@@ -32,7 +32,7 @@ module Command
       <<~PROMPT
         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 (`#{inferred_app_prefix}`) 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. Document the one-time Control Plane bootstrap command for persistent staging and production apps with `cpflow setup-app --skip-post-creation-hook`; for existing apps or later template updates, document `cpflow apply-template` and the need for the app identity to have `reveal` on the app secret policy. Do not imply the staging deploy or promotion workflows create those persistent GVCs. 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.
+        If `.controlplane/` is missing, run `cpflow generate`. Treat the generated app names as the repo-name default (`#{inferred_app_prefix}`) 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. When bumping the `cpflow` gem in a downstream repo, run `cpflow update-github-actions` (or `bundle exec cpflow update-github-actions`) and validate with `bin/test-cpflow-github-flow` in the same PR so the checked-in wrappers move to the matching release tag. Keep the standard path simple: review apps require only `CPLN_TOKEN_STAGING` when the generated review app config can be inferred. Document the one-time Control Plane bootstrap command for persistent staging and production apps with `cpflow setup-app --skip-post-creation-hook`; for existing apps or later template updates, document `cpflow apply-template` and the need for the app identity to have `reveal` on the app secret policy. Do not imply the staging deploy or promotion workflows create those persistent GVCs. 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`.
 

data/lib/command/base.rb

@@ -330,6 +330,17 @@ module Command
       }
     end
 
+    def self.force_option(required: false)
+      {
+        name: :force,
+        params: {
+          desc: "Overwrite existing generated files",
+          type: :boolean,
+          required: required
+        }
+      }
+    end
+
     def self.logs_limit_option(required: false)
       {
         name: :limit,

data/lib/command/generate_github_actions.rb

@@ -4,6 +4,7 @@ require "json"
 require "pathname"
 
 require_relative "generator_helpers"
+require_relative "staging_branch_validation"
 
 module Command
   class GithubActionsGenerator < Thor::Group
@@ -80,8 +81,10 @@ module Command
   end
 
   class GenerateGithubActions < Base
+    include StagingBranchValidation
+
     NAME = "generate-github-actions"
-    OPTIONS = [staging_branch_option].freeze
+    OPTIONS = [staging_branch_option, force_option].freeze
     DESCRIPTION = "Creates GitHub Actions templates for review apps, staging deploys, and production promotion"
     LONG_DESCRIPTION = <<~DESC
       Creates GitHub Actions templates for a Heroku Flow style Control Plane pipeline:
@@ -93,6 +96,9 @@ module Command
       Pass `--staging-branch BRANCH` when staging should auto-deploy from a branch
       other than `main` or `master`; the generator will bake that branch into the
       GitHub Actions push trigger and use it as the default STAGING_APP_BRANCH.
+      Pass `--force` to overwrite existing generated files. Prefer
+      `cpflow update-github-actions` after bumping the cpflow gem in a downstream
+      repo.
     DESC
     EXAMPLES = <<~EX
       ```sh
@@ -101,6 +107,9 @@ module Command
 
       # Creates the flow with staging deploys triggered from develop
       cpflow generate-github-actions --staging-branch develop
+
+      # Overwrites existing generated wrappers from the installed cpflow gem
+      cpflow generate-github-actions --force
       ```
     EX
     WITH_INFO_HEADER = false
@@ -129,10 +138,11 @@ module Command
       self.class.ensure_template_root!
       branch = staging_branch
 
-      if (existing = existing_files).any?
+      if (existing = existing_files).any? && !force?
         files = existing.map { |path| "- #{path}" }.join("\n")
         Shell.warn("The following files already exist:\n#{files}\n\n" \
-                   "Remove or rename them before running `cpflow #{NAME}` again.")
+                   "Remove or rename them before running `cpflow #{NAME}` again, " \
+                   "or run `cpflow update-github-actions` after updating the cpflow gem.")
         return
       end
 
@@ -145,38 +155,8 @@ module Command
       @existing_files ||= self.class.generated_files.select { |path| File.exist?(path) }
     end
 
-    def staging_branch
-      branch = config.options[:staging_branch].to_s.strip
-      return nil if branch.empty?
-
-      unless valid_staging_branch?(branch)
-        Shell.abort(
-          "Invalid --staging-branch value: #{branch.inspect}. " \
-          "Use a valid git branch name containing only alphanumerics, dots, slashes, underscores, hyphens, and @."
-        )
-      end
-
-      branch
-    end
-
-    def valid_staging_branch?(branch)
-      return false unless branch.match?(%r{\A[a-zA-Z0-9._/@-]+\z})
-
-      valid_git_branch_shape?(branch) && valid_git_branch_components?(branch)
-    end
-
-    def valid_git_branch_shape?(branch)
-      return false if branch.start_with?("-", "/", ".")
-      return false if branch.end_with?("/", ".")
-      return false if branch.include?("@{")
-
-      !branch.include?("..")
-    end
-
-    def valid_git_branch_components?(branch)
-      branch.split("/").none? do |component|
-        component.empty? || component.start_with?(".") || component.end_with?(".lock")
-      end
+    def force?
+      config.options[:force]
     end
   end
 end

data/lib/command/staging_branch_validation.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Command
+  module StagingBranchValidation
+    private
+
+    def staging_branch
+      branch = config.options[:staging_branch].to_s.strip
+      return nil if branch.empty?
+
+      unless valid_staging_branch?(branch)
+        Shell.abort(
+          "Invalid --staging-branch value: #{branch.inspect}. " \
+          "Use a valid git branch name containing only alphanumerics, dots, slashes, underscores, hyphens, and @."
+        )
+      end
+
+      branch
+    end
+
+    def valid_staging_branch?(branch)
+      return false unless branch.match?(%r{\A[a-zA-Z0-9._/@-]+\z})
+
+      valid_git_branch_shape?(branch) && valid_git_branch_components?(branch)
+    end
+
+    def valid_git_branch_shape?(branch)
+      return false if branch.start_with?("-", "/", ".")
+      return false if branch.end_with?("/", ".")
+      return false if branch.include?("@{")
+
+      !branch.include?("..")
+    end
+
+    def valid_git_branch_components?(branch)
+      branch.split("/").none? do |component|
+        component.empty? || component.start_with?(".") || component.end_with?(".lock")
+      end
+    end
+  end
+end

data/lib/command/update_github_actions.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+require_relative "staging_branch_validation"
+
+module Command
+  class UpdateGithubActions < Base
+    include StagingBranchValidation
+
+    NAME = "update-github-actions"
+    OPTIONS = [staging_branch_option].freeze
+    DESCRIPTION = "Regenerates generated GitHub Actions wrappers for the installed cpflow version"
+    LONG_DESCRIPTION = <<~DESC.freeze
+      Regenerates the generated cpflow GitHub Actions wrappers and helper files
+      from the currently installed cpflow gem. Use this after updating the
+      cpflow gem so checked-in workflow wrappers move to the matching upstream
+      release tag, for example `v#{Cpflow::VERSION}`.
+
+      If the existing generated staging workflow uses a custom single staging
+      branch, the command preserves it. Pass `--staging-branch BRANCH` to set or
+      replace the generated staging branch explicitly.
+    DESC
+    EXAMPLES = <<~EX
+      ```sh
+      # After updating the cpflow gem, refresh generated GitHub Actions wrappers
+      cpflow update-github-actions
+
+      # When running cpflow through Bundler
+      bundle exec cpflow update-github-actions
+
+      # Preserve or set a custom staging branch
+      cpflow update-github-actions --staging-branch develop
+      ```
+    EX
+    WITH_INFO_HEADER = false
+    VALIDATIONS = [].freeze
+    REQUIRES_STARTUP_CHECKS = false
+
+    DEFAULT_STAGING_BRANCHES = %w[main master].freeze
+    STAGING_WORKFLOW_PATH = Pathname.new(".github/workflows/cpflow-deploy-staging.yml")
+
+    def call
+      GenerateGithubActions.ensure_template_root!
+      abort_if_no_generated_files!
+
+      branch = staging_branch || inferred_staging_branch
+      GithubActionsGenerator.start([branch].compact)
+
+      print_post_update_message
+    end
+
+    private
+
+    def abort_if_no_generated_files!
+      return if GenerateGithubActions.generated_files.any? { |path| File.exist?(path) }
+
+      Shell.abort(
+        "No generated cpflow GitHub Actions files found in this repository. " \
+        "Run `cpflow generate-github-actions` first to create the wrappers, " \
+        "then use `cpflow update-github-actions` after future gem upgrades."
+      )
+    end
+
+    def print_post_update_message
+      Shell.info("")
+      Shell.info("Updated cpflow GitHub Actions wrappers for cpflow #{Cpflow::VERSION}.")
+      Shell.info("Next: review the diff and run `bin/test-cpflow-github-flow`.")
+      Shell.info("If you run cpflow through Bundler, use `bin/test-cpflow-github-flow bundle exec cpflow`.")
+    end
+
+    def inferred_staging_branch
+      branches = existing_staging_branches
+      return if branches.empty? || branches.sort == DEFAULT_STAGING_BRANCHES.sort
+      return branches.first if branches.length == 1
+
+      Shell.warn(
+        "Existing staging workflow has multiple custom push branches: #{branches.join(', ')}. " \
+        "Run with --staging-branch BRANCH if only one branch should auto-deploy staging."
+      )
+
+      nil
+    end
+
+    def existing_staging_branches
+      Array(parsed_staging_workflow_on.dig("push", "branches")).map(&:to_s)
+    end
+
+    def parsed_staging_workflow_on
+      return {} unless STAGING_WORKFLOW_PATH.file?
+
+      workflow = YAML.load_file(STAGING_WORKFLOW_PATH, aliases: true)
+      return {} unless workflow.is_a?(Hash)
+
+      workflow_on = workflow["on"] || workflow[true]
+      workflow_on.is_a?(Hash) ? workflow_on : {}
+    rescue Psych::SyntaxError => e
+      warn_unparseable_staging_workflow(e)
+      {}
+    end
+
+    def warn_unparseable_staging_workflow(error)
+      Shell.warn(
+        "Could not parse #{STAGING_WORKFLOW_PATH}: #{error.message}. " \
+        "Run with --staging-branch BRANCH if staging should use a custom branch."
+      )
+    end
+  end
+end

data/lib/cpflow/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Cpflow
-  VERSION = "5.0.2"
+  VERSION = "5.0.3"
   MIN_CPLN_VERSION = "3.1.0"
 end

data/lib/github_flow_templates/.github/cpflow-help.md

@@ -88,6 +88,21 @@ checked-out upstream source. If you set `CPFLOW_VERSION`, it must match the
 release tag, for example `CPFLOW_VERSION=5.0.1` with a wrapper pinned to
 `uses: ...@v5.0.1`.
 
+After updating the `cpflow` gem in this repo, update the generated wrappers in
+the same PR:
+
+```sh
+cpflow update-github-actions
+bin/test-cpflow-github-flow
+```
+
+If `cpflow` is bundled by the app, use:
+
+```sh
+bundle exec cpflow update-github-actions
+bin/test-cpflow-github-flow bundle exec cpflow
+```
+
 Do not leave downstream apps pinned to a moving branch such as `main`. For a
 short-lived test of an unreleased upstream PR, pin to a full 40-character commit
 SHA and leave `CPFLOW_VERSION` unset:

data/rakelib/create_release.rake

@@ -101,6 +101,8 @@ task :release, %i[version dry_run override_version_policy] do |_t, args|
     puts "RELEASE COMPLETE"
     puts "Published cpflow #{released_gem_version} to RubyGems.org."
   end
+
+  Release.print_github_actions_update_reminder(released_gem_version)
 end
 
 desc("Compatibility alias for the old release task. Prefer `bundle exec rake release`.")
@@ -452,6 +454,21 @@ module Release
       abort "gem-release is required. Run `bundle install`.\n\n#{output}" unless status.success?
     end
 
+    def print_github_actions_update_reminder(version)
+      puts ""
+      puts "GitHub Actions follow-up:"
+      puts "  Downstream repos using generated cpflow GitHub Actions must update their checked-in wrappers."
+      puts "  Run this in each downstream repo after installing cpflow #{version}:"
+      puts ""
+      puts "    cpflow update-github-actions"
+      puts "    bin/test-cpflow-github-flow"
+      puts ""
+      puts "  If cpflow is bundled in the app:"
+      puts ""
+      puts "    bundle exec cpflow update-github-actions"
+      puts "    bin/test-cpflow-github-flow bundle exec cpflow"
+    end
+
     def github_repo_slug(gem_root)
       origin_url, status = Open3.capture2e("git", "-C", gem_root, "remote", "get-url", "origin")
       abort "Unable to determine git origin URL.\n\n#{origin_url}" unless status.success?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cpflow
 version: !ruby/object:Gem::Version
-  version: 5.0.2
+  version: 5.0.3
 platform: ruby
 authors:
 - Justin Gordon
@@ -177,10 +177,12 @@ files:
 - lib/command/ps_wait.rb
 - lib/command/run.rb
 - lib/command/setup_app.rb
+- lib/command/staging_branch_validation.rb
 - lib/command/terraform/base.rb
 - lib/command/terraform/generate.rb
 - lib/command/terraform/import.rb
 - lib/command/test.rb
+- lib/command/update_github_actions.rb
 - lib/command/version.rb
 - lib/constants/exit_code.rb
 - lib/core/config.rb
@@ -268,6 +270,22 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
+post_install_message: |
+  cpflow 5.0.3 installed.
+
+  If this repository already uses generated cpflow GitHub Actions, update the
+  checked-in wrappers so GitHub loads the matching control-plane-flow release tag:
+
+    cpflow update-github-actions
+    bin/test-cpflow-github-flow
+
+  If you run cpflow through Bundler:
+
+    bundle exec cpflow update-github-actions
+    bin/test-cpflow-github-flow bundle exec cpflow
+
+  New repository? Run `cpflow generate-github-actions` first to create the
+  wrappers (and the `bin/test-cpflow-github-flow` script referenced above).
 rdoc_options: []
 require_paths:
 - lib