cpflow 5.0.1 → 5.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1371f70bf636d92e0dacd78322ad6ef7d87e29fbec6c853e487a01205be1528
-  data.tar.gz: 9ad5116ccb84cc7e3757922c3c0580785caa1cfff96aed768c65d63c7ff01e93
+  metadata.gz: 4ae89eb9d37d93ce9d6e22fa42d4210cce3183505a00ee91cee172e47cb9750b
+  data.tar.gz: ba697c7e72c80ae792feb52b47f42db38180c63af42ab7959650ce1b757d0201
 SHA512:
-  metadata.gz: 6c96a1db55e94a5e22efa0640d51129566aa6afb16c8ea9887f5cf709a313ef3b1a690d5b64ba932b50cb1fb72efe85e7fa3371f8941b60242486d6fc1322566
-  data.tar.gz: 5a91cc36014d13c3b36ea3af7620758821d1fa0000bab12b1742d47fe0240015353c59b5dae6d981680b7746bcaa9154bd44f00a1fc240dce651cd57926a253b
+  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,24 @@ 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
+
+- **Fixed generated Dockerfiles so Node package-manager shims (`npm`, `npx`, and `corepack`) remain working symlinks in the final Ruby image instead of broken dereferenced files.** [PR 322](https://github.com/shakacode/control-plane-flow/pull/322) by [Justin Gordon](https://github.com/justin808). Generated Dockerfiles now fail fast if the Node shim paths are no longer valid.
+- **Fixed generated Control Plane templates so app workloads receive app identity links, templated YAML scalars are parseable, and generated Postgres resources/secrets are app-scoped.** [PR 322](https://github.com/shakacode/control-plane-flow/pull/322) by [Justin Gordon](https://github.com/justin808). This lets review apps resolve `cpln://secret/...` values reliably from Rails, worker, renderer, and release jobs.
+- **Fixed `cpflow run` so existing runner workloads stay in sync with the source workload `identityLink`.** [PR 322](https://github.com/shakacode/control-plane-flow/pull/322) by [Justin Gordon](https://github.com/justin808). Existing runner jobs now gain or drop the app identity as the source workload changes.
+
 ## [5.0.1] - 2026-05-24
 
 ### Breaking Changes
@@ -374,7 +392,9 @@ Deprecated `cpl` gem. New gem is `cpflow`.
 
 First release.
 
-[Unreleased]: https://github.com/shakacode/control-plane-flow/compare/v5.0.1...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
 [5.0.0.rc.3]: https://github.com/shakacode/control-plane-flow/compare/v5.0.0.rc.1...v5.0.0.rc.3

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cpflow (5.0.1)
+    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. 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

@@ -214,6 +214,56 @@ needs. They do not use `secrets: inherit`; the production token is supplied by
 the protected `production` Environment after approval, not forwarded from a
 repository secret.
 
+## First-Time Control Plane Bootstrap
+
+GitHub settings only give the workflows permission to act. They do not create
+the persistent staging or production GVCs for you on the first merge.
+
+Before the first staging deploy, bootstrap the staging app once:
+
+```sh
+cpflow setup-app -a my-app-staging --org my-org-staging --skip-post-creation-hook
+```
+
+`setup-app` reads the `setup_app_templates` list from
+`.controlplane/controlplane.yml`. It creates the persistent staging GVC,
+workloads, app identity, app secret dictionary, app secret policy, and policy
+binding that grants the app identity `reveal` permission on that dictionary.
+Use `--skip-post-creation-hook` for first-time bootstrap so a database hook does
+not try to run before the first image exists.
+
+After the persistent app exists, use `apply-template` for later template
+updates. Adjust the template list to match your repo, such as adding `worker`,
+`sidekiq`, `renderer`, `redis`, or other templates present under
+`.controlplane/templates`:
+
+```sh
+cpflow apply-template app postgres rails -a my-app-staging --org my-org-staging --yes --add-app-identity
+```
+
+If you use `apply-template` to create or repair an existing app, also confirm
+that the app identity has `reveal` permission on the app secret policy. Without
+that binding, workloads that reference `cpln://secret/<app-secrets>.*` stay
+paused until the policy is fixed.
+
+Before the first production promotion, run the same kind of bootstrap for the
+production app in the production org:
+
+```sh
+cpflow setup-app -a my-app-production --org my-org-production --skip-post-creation-hook
+```
+
+Use production-only runtime secrets and values for the production app. The
+protected GitHub Environment controls who can run the promotion workflow, but
+the production app resources still need to exist before the first promotion.
+
+Review apps are different: the generated `+review-app-deploy` workflow creates
+temporary PR apps as needed, including the identity and secret policy binding.
+You still need the shared review-app runtime secret values described by your
+templates, and the staging token must have access to create and update
+review-app GVCs, workloads, images, identities, policies, and secrets in the
+staging org.
+
 ### Production Promotion Safety
 
 `CPLN_TOKEN_PRODUCTION` can change live production workloads, images, releases,
@@ -405,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`
@@ -503,7 +509,7 @@ cpflow run -a $APP_NAME --entrypoint /app/alternative-entrypoint.sh -- rails db:
 
 - Creates an app and all its workloads
 - Specify the templates for the app and workloads through `setup_app_templates` in the `.controlplane/controlplane.yml` file
-- This should only be used for temporary apps like review apps, never for persistent apps like production or staging (to update workloads for those, use 'cpflow apply-template' instead)
+- Use this for temporary apps like review apps and for first-time bootstrap of persistent staging or production apps; after a persistent app exists, use 'cpflow apply-template' for template updates
 - Configures app to have org-level secrets with default name `"{APP_PREFIX}-secrets"`
   using org-level policy with default name `"{APP_PREFIX}-secrets-policy"` (names can be customized, see docs)
 - Creates identity for secrets if it does not exist
@@ -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. 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/run.rb

@@ -197,7 +197,7 @@ module Command
       spec = nil
 
       step("Checking if runner workload '#{runner_workload}' needs to be updated") do # rubocop:disable Metrics/BlockLength
-        _, original_container_spec = base_workload_specs(original_workload)
+        original_spec, original_container_spec = base_workload_specs(original_workload)
         spec, container_spec = base_workload_specs(runner_workload)
 
         # Keep ENV synced between original and runner workloads
@@ -208,6 +208,16 @@ module Command
           should_update = true
         end
 
+        # Keep the app identity in sync so runner jobs can resolve GVC-level secrets.
+        if spec["identityLink"] != original_spec["identityLink"]
+          if original_spec["identityLink"]
+            spec["identityLink"] = original_spec["identityLink"]
+          else
+            spec.delete("identityLink")
+          end
+          should_update = true
+        end
+
         if container_spec["image"] != default_image
           container_spec["image"] = default_image
           should_update = true

data/lib/command/setup_app.rb

@@ -13,7 +13,7 @@ module Command
     LONG_DESCRIPTION = <<~DESC
       - Creates an app and all its workloads
       - Specify the templates for the app and workloads through `setup_app_templates` in the `.controlplane/controlplane.yml` file
-      - This should only be used for temporary apps like review apps, never for persistent apps like production or staging (to update workloads for those, use 'cpflow apply-template' instead)
+      - Use this for temporary apps like review apps and for first-time bootstrap of persistent staging or production apps; after a persistent app exists, use 'cpflow apply-template' for template updates
       - Configures app to have org-level secrets with default name `"{APP_PREFIX}-secrets"`
         using org-level policy with default name `"{APP_PREFIX}-secrets-policy"` (names can be customized, see docs)
       - Creates identity for secrets if it does not exist

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.1"
+  VERSION = "5.0.3"
   MIN_CPLN_VERSION = "3.1.0"
 end

data/lib/generator_templates/Dockerfile

@@ -17,12 +17,17 @@ WORKDIR /app
 # rely on ExecJS in production. Narrowed to just what the node stage actually
 # ships under /usr/local so we don't drag in unused Debian libs from that image.
 COPY --from=node /usr/local/bin/node /usr/local/bin/node
-COPY --from=node /usr/local/bin/npm /usr/local/bin/npm
-COPY --from=node /usr/local/bin/npx /usr/local/bin/npx
-COPY --from=node /usr/local/bin/corepack /usr/local/bin/corepack
 COPY --from=node /usr/local/lib/node_modules /usr/local/lib/node_modules
 COPY --from=node /usr/local/include/node /usr/local/include/node
 
+RUN ln -sf ../lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm && \
+    ln -sf ../lib/node_modules/npm/bin/npx-cli.js /usr/local/bin/npx && \
+    ln -sf ../lib/node_modules/corepack/dist/corepack.js /usr/local/bin/corepack && \
+    chmod +x /usr/local/lib/node_modules/npm/bin/npm-cli.js \
+             /usr/local/lib/node_modules/npm/bin/npx-cli.js \
+             /usr/local/lib/node_modules/corepack/dist/corepack.js && \
+    node --version && npm --version && corepack --version
+
 # Expose Corepack-managed shims so later build steps can call yarn/pnpm
 # directly during asset precompilation hooks.
 RUN printf '%s\n' '#!/bin/sh' 'exec corepack yarn "$@"' > /usr/bin/yarn && \

data/lib/generator_templates/templates/app.yml

@@ -1,6 +1,6 @@
 # Template setup of the GVC, roughly corresponding to a Heroku app
 kind: gvc
-name: {{APP_NAME}}
+name: "{{APP_NAME}}"
 spec:
   env:
     - name: DATABASE_URL
@@ -12,7 +12,7 @@ spec:
     - name: RAILS_SERVE_STATIC_FILES
       value: "true"
     - name: SECRET_KEY_BASE
-      value: cpln://secret/{{APP_SECRETS}}.SECRET_KEY_BASE
+      value: "cpln://secret/{{APP_SECRETS}}.SECRET_KEY_BASE"
   staticPlacement:
     locationLinks:
-      - {{APP_LOCATION_LINK}}
+      - "{{APP_LOCATION_LINK}}"

data/lib/generator_templates/templates/postgres.yml

@@ -2,8 +2,8 @@
 # https://github.com/controlplane-com/examples/blob/main/examples/postgres/manifest.yaml
 
 kind: volumeset
-name: postgres-poc-vs
-description: postgres-poc-vs
+name: "{{APP_NAME}}-pg-vs"
+description: "{{APP_NAME}}-pg-vs"
 spec:
   autoscaling:
     maxCapacity: 1000
@@ -18,7 +18,7 @@ spec:
 
 ---
 kind: secret
-name: postgres-poc-credentials
+name: "{{APP_NAME}}-pg"
 description: ''
 type: dictionary
 data:
@@ -27,7 +27,7 @@ data:
 
 ---
 kind: secret
-name: postgres-poc-entrypoint-script
+name: "{{APP_NAME}}-pg-script"
 type: opaque
 data:
   encoding: base64
@@ -92,13 +92,13 @@ data:
 
 ---
 kind: identity
-name: postgres-poc-identity
-description: postgres-poc-identity
+name: "{{APP_NAME}}-pg-identity"
+description: "{{APP_NAME}}-pg-identity"
 
 ---
 kind: policy
-name: postgres-poc-access
-description: postgres-poc-access
+name: "{{APP_NAME}}-pg-access"
+description: "{{APP_NAME}}-pg-access"
 bindings:
   - permissions:
       - reveal
@@ -106,11 +106,14 @@ bindings:
 #      - use
 #      - view
     principalLinks:
-      - //gvc/{{APP_NAME}}/identity/postgres-poc-identity
+      - "//gvc/{{APP_NAME}}/identity/{{APP_NAME}}-pg-identity"
+      # cpflow apply-template replaces {{APP_IDENTITY_LINK}} with the full app workload identity link.
+      # Example: //gvc/{{APP_NAME}}/identity/{{APP_NAME}}-identity.
+      - "{{APP_IDENTITY_LINK}}"
 targetKind: secret
 targetLinks:
-  - //secret/postgres-poc-credentials
-  - //secret/postgres-poc-entrypoint-script
+  - "//secret/{{APP_NAME}}-pg"
+  - "//secret/{{APP_NAME}}-pg-script"
 
 ---
 kind: workload
@@ -130,9 +133,9 @@ spec:
         - name: PGDATA #The location postgres stores the db. This can be anything other than /var/lib/postgresql/data, but it must be inside the mount point for the volume set
           value: "/var/lib/postgresql/data/pg_data"
         - name: POSTGRES_PASSWORD #The password for the default user
-          value: cpln://secret/postgres-poc-credentials.password
+          value: "cpln://secret/{{APP_NAME}}-pg.password"
         - name: POSTGRES_USER #The name of the default user
-          value: cpln://secret/postgres-poc-credentials.username
+          value: "cpln://secret/{{APP_NAME}}-pg.username"
       name: postgres
       image: postgres:15
       command: /bin/bash
@@ -146,10 +149,10 @@ spec:
         - number: 5432
           protocol: tcp
       volumes:
-        - uri: cpln://volumeset/postgres-poc-vs
+        - uri: "cpln://volumeset/{{APP_NAME}}-pg-vs"
           path: "/var/lib/postgresql/data"
         # Make the ENV value for the entry script a file
-        - uri: cpln://secret/postgres-poc-entrypoint-script
+        - uri: "cpln://secret/{{APP_NAME}}-pg-script"
           path: "/usr/local/bin/cpln-entrypoint.sh"
       inheritEnv: false
       livenessProbe:
@@ -160,7 +163,7 @@ spec:
         tcpSocket:
           port: 5432
         failureThreshold: 1
-  identityLink: //identity/postgres-poc-identity
+  identityLink: "//identity/{{APP_NAME}}-pg-identity"
   defaultOptions:
     capacityAI: false
     autoscaling:

data/lib/generator_templates/templates/rails.yml

@@ -8,7 +8,7 @@ spec:
     - name: rails
       cpu: 300m
       inheritEnv: true
-      image: {{APP_IMAGE_LINK}}
+      image: "{{APP_IMAGE_LINK}}"
       memory: 512Mi
       ports:
         - number: 3000
@@ -29,3 +29,5 @@ spec:
         - 0.0.0.0/0
       outboundAllowCIDR:
         - 0.0.0.0/0
+  # cpflow apply-template replaces {{APP_IDENTITY_LINK}} with the app workload identity link.
+  identityLink: "{{APP_IDENTITY_LINK}}"

data/lib/generator_templates_sqlite/templates/app.yml

@@ -1,5 +1,5 @@
 kind: gvc
-name: {{APP_NAME}}
+name: "{{APP_NAME}}"
 spec:
   env:
     - name: RAILS_ENV
@@ -9,7 +9,7 @@ spec:
     - name: RAILS_SERVE_STATIC_FILES
       value: "true"
     - name: SECRET_KEY_BASE
-      value: cpln://secret/{{APP_SECRETS}}.SECRET_KEY_BASE
+      value: "cpln://secret/{{APP_SECRETS}}.SECRET_KEY_BASE"
   staticPlacement:
     locationLinks:
-      - {{APP_LOCATION_LINK}}
+      - "{{APP_LOCATION_LINK}}"

data/lib/generator_templates_sqlite/templates/rails.yml

@@ -6,7 +6,7 @@ spec:
     - name: rails
       cpu: 300m
       inheritEnv: true
-      image: {{APP_IMAGE_LINK}}
+      image: "{{APP_IMAGE_LINK}}"
       memory: 512Mi
       ports:
         - number: 3000
@@ -34,3 +34,5 @@ spec:
         - 0.0.0.0/0
       outboundAllowCIDR:
         - 0.0.0.0/0
+  # cpflow apply-template replaces {{APP_IDENTITY_LINK}} with the app workload identity link.
+  identityLink: "{{APP_IDENTITY_LINK}}"

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

@@ -39,6 +39,23 @@ Optional overrides exist for forks, clones, and unusual apps:
 ## Staging And Production
 
 Staging deploys use the same `CPLN_TOKEN_STAGING` secret plus `STAGING_APP_NAME`.
+Before the first staging deploy, bootstrap the persistent staging app once:
+
+```sh
+cpflow setup-app -a "$STAGING_APP_NAME" --org "$CPLN_ORG_STAGING" --skip-post-creation-hook
+```
+
+`setup-app` reads `.controlplane/controlplane.yml`'s `setup_app_templates` and
+creates the app identity, app secret dictionary, app secret policy, policy
+binding, and template resources. Use `--skip-post-creation-hook` so first-time
+bootstrap does not try to run database setup before an image exists. For later
+template updates on an existing persistent app, use `cpflow apply-template`
+with the same template list and make sure the app identity has `reveal`
+permission on the app secret policy.
+
+Review apps are temporary and are created by the `+review-app-deploy` workflow,
+but staging and production are persistent apps and should be bootstrapped
+explicitly.
 
 Production promotion is part of the generated flow, but keep it protected:
 
@@ -53,6 +70,9 @@ prevent self-review. The generated promotion wrapper passes only the staging
 token from repository secrets; GitHub injects `CPLN_TOKEN_PRODUCTION` only after
 the environment approval gate passes.
 
+Before the first promotion, bootstrap the production app the same way in the
+production org, using production-only secrets and values.
+
 ## Version Locking
 
 Generated wrappers pin Control Plane Flow once with the reusable workflow
@@ -68,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.1
+  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