cpflow 5.0.1 → 5.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1371f70bf636d92e0dacd78322ad6ef7d87e29fbec6c853e487a01205be1528
-  data.tar.gz: 9ad5116ccb84cc7e3757922c3c0580785caa1cfff96aed768c65d63c7ff01e93
+  metadata.gz: f6a3d49d8db4d5df28b82fa8cfb81af3470299d485169997c2904c683b1a56c6
+  data.tar.gz: 48cacf78f5d61ca95405b46e152b26547536a3862a06d93433efaa7c52f7f85d
 SHA512:
-  metadata.gz: 6c96a1db55e94a5e22efa0640d51129566aa6afb16c8ea9887f5cf709a313ef3b1a690d5b64ba932b50cb1fb72efe85e7fa3371f8941b60242486d6fc1322566
-  data.tar.gz: 5a91cc36014d13c3b36ea3af7620758821d1fa0000bab12b1742d47fe0240015353c59b5dae6d981680b7746bcaa9154bd44f00a1fc240dce651cd57926a253b
+  metadata.gz: 9158740f20c83981417325473f6f9d3b27fee1e0967b31746d44f32d4d6e0dca2d14ab17dfd05d2f27a10a745b33e663cc775c562919fdaa2311e554cddfb2af
+  data.tar.gz: c822be6375f28c6c01e13b397f5857fa4d3cd8463cc787cd6dc9be5a6f4967aa17a84af19f4e31c6b565e8325e19286de1c0fa398c22db4966a3f723e7adfb1a

data/CHANGELOG.md

@@ -12,6 +12,14 @@ In addition to the standard keepachangelog.com categories, this project uses a l
 
 ## [Unreleased]
 
+## [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 +382,8 @@ 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.2...HEAD
+[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.2)
       dotenv (~> 3.1)
       jwt (~> 3.1)
       psych (~> 5.2)

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. 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,

data/docs/commands.md

@@ -503,7 +503,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

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. 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/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/cpflow/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Cpflow
-  VERSION = "5.0.1"
+  VERSION = "5.0.2"
   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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cpflow
 version: !ruby/object:Gem::Version
-  version: 5.0.1
+  version: 5.0.2
 platform: ruby
 authors:
 - Justin Gordon