cpflow 5.0.0 → 5.0.2

data/docs/ci-automation.md

@@ -150,29 +150,148 @@ apps:
 
 Important points:
 
-- `REVIEW_APP_PREFIX` in GitHub Actions must match the review config key prefix, for example `my-app-review`.
 - `match_if_app_name_starts_with: true` is what allows a single config entry to back `my-app-review-123`, `my-app-review-456`, and cleanup commands like `cpflow cleanup-stale-apps -a my-app-review`.
+- Review-app deploy, delete, and cleanup workflows infer the review app prefix from the single app entry with `match_if_app_name_starts_with: true`.
+- Review-app workflows infer the staging Control Plane org from that review app entry's `cpln_org`.
 - `upstream: my-app-staging` is what lets the production promotion workflow copy the exact staging artifact.
 - If your main web workload is not named `rails`, set the optional `PRIMARY_WORKLOAD` repository variable described below.
 
 ## Required GitHub Repository Settings
 
-Configure these repository secrets:
+For a normal generated review-app setup, configure one repository secret:
 
 - `CPLN_TOKEN_STAGING`: token for the staging Control Plane org
-- `CPLN_TOKEN_PRODUCTION`: token for the production Control Plane org
 
-Configure these repository variables:
+No GitHub repository variables are required for review apps when `.controlplane/controlplane.yml`
+has exactly one review app entry with `match_if_app_name_starts_with: true` and
+that entry has a `cpln_org`. The inferred values come from that config file:
+the review-app prefix is the app key with `match_if_app_name_starts_with: true`,
+and the staging org is that app's `cpln_org` value. Set these variables only
+when you need to test a fork or clone against a different Control Plane org,
+choose a different review-app prefix, expose a different public workload, or
+disambiguate generated review-app config:
+
+- `CPLN_ORG_STAGING`: override the staging/review org inferred from `cpln_org`, for example `company-staging`
+- `REVIEW_APP_PREFIX`: override the inferred review-app prefix; required only when multiple review app prefixes exist in `controlplane.yml`
+- `PRIMARY_WORKLOAD`: override the public workload used to discover the public endpoint and do production health checks; defaults to `rails`
+
+If `controlplane.yml` defines more than one app with
+`match_if_app_name_starts_with: true`, inference intentionally fails. Set
+`CPLN_ORG_STAGING` and `REVIEW_APP_PREFIX` to tell the workflow which review-app
+family to manage.
+
+For staging deploys, also configure:
 
 - `CPLN_ORG_STAGING`: staging org name, for example `company-staging`
-- `CPLN_ORG_PRODUCTION`: production org name, for example `company-production`
 - `STAGING_APP_NAME`: staging GVC name, for example `my-app-staging`
-- `PRODUCTION_APP_NAME`: production GVC name, for example `my-app-production`
-- `REVIEW_APP_PREFIX`: review-app prefix, for example `my-app-review`
 - `STAGING_APP_BRANCH`: optional branch that auto-deploys staging. If you use a custom branch, either pass it to `cpflow generate-github-actions --staging-branch BRANCH` during generation or edit `cpflow-deploy-staging.yml` so its `on.push.branches` list includes the same branch.
-- `PRIMARY_WORKLOAD`: optional workload name used to discover the public endpoint and do production health checks; defaults to `rails`
-- `DOCKER_BUILD_EXTRA_ARGS`: optional newline-delimited single `docker build` tokens passed through to `cpflow build-image`, for example `--build-arg=FOO=bar` or `--secret=id=npmrc,src=.npmrc`
-- `DOCKER_BUILD_SSH_KNOWN_HOSTS`: optional multi-line `known_hosts` content used with `DOCKER_BUILD_SSH_KEY` when the build needs SSH access to hosts other than GitHub.com
+
+For production promotion, also configure:
+
+- a GitHub Environment named `production`
+- required reviewers on that environment, limited to the people or team allowed to promote production
+- "Prevent self-review" on that environment, so the person who starts the promotion cannot approve it
+- optionally disable administrator bypass and restrict deployment branches/tags to your protected release branch
+- `CPLN_TOKEN_PRODUCTION` as an environment secret on `production`, not as a repository or organization secret
+- `CPLN_ORG_PRODUCTION` as a production environment variable, for example `company-production`
+- `PRODUCTION_APP_NAME` as a production environment variable, for example `my-app-production`
+
+Do not put `CPLN_TOKEN_PRODUCTION` in repository or organization secrets for
+sensitive production systems. The generated promotion reusable workflow declares
+`environment: production`; the generated caller passes that environment name
+through `production_environment`. GitHub waits for the `production`
+environment's protection rules before injecting `CPLN_TOKEN_PRODUCTION` into
+the upstream production job.
+
+GitHub's reusable-workflow syntax still requires the upstream workflow to
+declare `CPLN_TOKEN_PRODUCTION` as an optional `workflow_call` secret so static
+validation accepts `secrets.CPLN_TOKEN_PRODUCTION`, but the generated caller
+must not pass it. GitHub uses the secret from the reusable workflow job's
+`production` environment when that environment is configured.
+
+Generated caller workflows pass only the named secrets each reusable workflow
+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,
+and rollback state. Treat it differently from review-app and staging credentials.
+The standard path is:
+
+1. Create the `production` GitHub Environment before setting the production token.
+2. Add a small required-reviewer list or team with production authority.
+3. Enable prevent self-review.
+4. Disable administrator bypass if your org policy requires two-person control.
+5. Restrict deployable branches or tags to the protected release branch.
+6. Store `CPLN_TOKEN_PRODUCTION` only as a `production` environment secret.
+7. Store `CPLN_ORG_PRODUCTION` and `PRODUCTION_APP_NAME` as `production`
+   environment variables, or as repository variables only when those names are
+   intentionally non-sensitive.
+
+GitHub only exposes environment secrets to jobs that reference the environment
+after configured protection rules pass. GitHub also does not allow a caller job
+that directly invokes a reusable workflow to set `environment`; for that reason,
+the reusable promotion workflow itself declares `environment: production`. See
+GitHub's docs for [managing environments](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments),
+[deployment protection rules](https://docs.github.com/en/actions/reference/workflows-and-actions/deployments-and-environments),
+and [reusable workflow limitations](https://docs.github.com/en/actions/reference/reusable-workflows-reference#supported-keywords-for-jobs-that-call-a-reusable-workflow).
+
+Application runtime secrets such as `SECRET_KEY_BASE`, API keys, or private
+license keys belong in Control Plane secret dictionaries referenced by
+`controlplane.yml`. They are not GitHub repository variables unless your
+Docker build itself needs them.
 
 Recommended org layout:
 
@@ -183,6 +302,17 @@ Optional repository secret for private dependency builds:
 
 - `DOCKER_BUILD_SSH_KEY`: private SSH key used when the Dockerfile needs `RUN --mount=type=ssh` to fetch private GitHub dependencies during image build
 
+Optional repository variables for private dependency builds:
+
+- `DOCKER_BUILD_EXTRA_ARGS`: optional newline-delimited single `docker build` tokens passed through to `cpflow build-image`, for example `--build-arg=FOO=bar` or `--secret=id=npmrc,src=.npmrc`
+- `DOCKER_BUILD_SSH_KNOWN_HOSTS`: optional multi-line `known_hosts` content used with `DOCKER_BUILD_SSH_KEY` when the build needs SSH access to hosts other than GitHub.com
+
+Advanced optional repository variables:
+
+- `REVIEW_APP_DEPLOYING_ICON_URL`: custom image URL for the animated icon in review-app PR comments. Ignore this for the standard setup; it is cosmetic only.
+- `CPLN_CLI_VERSION`: pin only when Control Plane CLI compatibility requires it.
+- `CPFLOW_VERSION`: pin a published RubyGems version only when intentionally overriding the default build-from-ref behavior.
+
 ## Docker Builds with Private Dependencies
 
 Some apps need extra Docker build configuration before the generated workflows are turnkey. Common examples are:
@@ -212,6 +342,9 @@ The action will start an SSH agent, add the key, write `known_hosts`, and pass `
 `cpflow-review-app-help.yml`
 
 - Posts a quick reference when a pull request opens, including on fork-based PRs.
+- This is an onboarding comment only; it does not checkout PR code or receive
+  Control Plane secrets. Remove this wrapper if a repo does not want automatic
+  review-app command help on every new PR.
 
 `cpflow-help-command.yml`
 
@@ -242,6 +375,7 @@ The action will start an SSH agent, add the key, write `known_hosts`, and pass `
 `cpflow-promote-staging-to-production.yml`
 
 - Manually promotes the staging artifact to production with a confirmation input.
+- Runs the production job in the `production` GitHub Environment, so configured reviewers approve the job before production environment secrets are available.
 - Verifies that production has the env var names staging expects.
 - Runs a health check against `PRIMARY_WORKLOAD`.
 - Attempts a rollback of every configured application workload if the new production image does not come up healthy.
@@ -252,6 +386,25 @@ The action will start an SSH agent, add the key, write `known_hosts`, and pass `
 - Runs nightly and on demand.
 - Deletes stale review apps using `cpflow cleanup-stale-apps`.
 
+Generated review app names use `<review-app-prefix>-<PR number>`, for example
+`my-app-review-123`. If an existing repository is migrating from older local
+workflow glue that created names like `<review-app-prefix>-pr-123`, delete those
+old review apps manually after merging the generated flow; the cleanup workflow
+only targets the current prefix convention.
+
+To inventory old-prefix review apps before cleanup, run:
+
+```sh
+cpln gvc query --org <staging-org> -o yaml --prop name~<review-app-prefix>-pr-
+```
+
+The PR-open help workflow posts the short command reference whenever the
+generated wrapper exists. That is intentional for configured demo repos. Forks
+or clones that copy the workflow before configuring Control Plane can remove
+`.github/workflows/cpflow-review-app-help.yml` or uncomment and adapt the
+wrapper-level `if:` guard shown in that file, for example
+`vars.REVIEW_APP_PREFIX != '' || vars.CPLN_ORG_STAGING != ''`.
+
 ## Upstream Reusable Workflows
 
 The generated workflows are intentionally small wrappers. The deployment logic,
@@ -271,18 +424,26 @@ GitHub ref:
 
 ```yaml
 uses: shakacode/control-plane-flow/.github/workflows/cpflow-deploy-review-app.yml@<ref>
-with:
-  control_plane_flow_ref: <ref>
 ```
 
-Those two pins must stay in sync:
+That single `uses:` ref is the downstream lock. GitHub exposes the reusable
+workflow's own repository, ref, and SHA to the called job, so the upstream
+workflow checks out the matching `control-plane-flow` source automatically from
+that context. Downstream wrappers should not pass `control_plane_flow_ref`; if
+you see that input in generated wrappers, regenerate with a newer `cpflow`.
+
+There are two locks, and they protect different things:
 
-- `uses: ...@<ref>` chooses the upstream reusable workflow file.
-- `control_plane_flow_ref: <ref>` tells that reusable workflow which
-  `control-plane-flow` checkout to use for shared composite actions and, when
-  `CPFLOW_VERSION` is empty, for building and installing the `cpflow` gem.
+- The GitHub ref locks the reusable workflow and composite action code that
+  GitHub runs.
+- The RubyGems version locks the `cpflow` CLI/runtime code only when you install
+  or run that gem. It does not make GitHub load reusable workflow YAML from the
+  gem.
 
-The stable release path is still gem-driven:
+That means a downstream app cannot rely on the gem alone for GitHub Actions
+behavior. The safe stable path is still gem-driven for generation, but
+developers must commit generated wrappers that reference the matching upstream
+release tag:
 
 1. Publish a `cpflow` gem.
 2. Install or bundle that released gem in the downstream project.
@@ -297,9 +458,26 @@ feature-branch refs.
 `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
-`control-plane-flow` ref. For normal releases, leave `CPFLOW_VERSION` unset while
-pinning the wrappers to the matching `v<version>` tag, or set
-`CPFLOW_VERSION` to that same released gem version without the leading `v`.
+`control-plane-flow` source selected by the reusable workflow's own SHA. For
+normal releases, leave `CPFLOW_VERSION` unset while pinning the wrappers to the
+matching `v<version>` tag, or set `CPFLOW_VERSION` to that same released gem
+version without the leading `v`.
+When setting `CPFLOW_VERSION`, use RubyGems version syntax, for example
+`5.0.0` or `5.0.0.rc.1`; do not use `v5.0.0` or dash-separated prereleases
+because the value is passed directly to `gem install cpflow -v`.
+
+The setup action fails early when `CPFLOW_VERSION` and the reusable workflow tag
+are out of sync. `CPFLOW_VERSION=5.0.0` is accepted only when the wrapper uses a
+release tag such as `@v5.0.0` (or GitHub resolves it to `refs/tags/v5.0.0`).
+Release tags may use dot- or dash-separated prerelease suffixes, such as
+`v5.0.0.rc.1` or `v5.0.0-rc.1`; the gem version should still use dots. The
+action also checks the remote `control-plane-flow` tag and the checked-out
+action commit, so a moving branch named like `v5.0.0` cannot be used with
+`CPFLOW_VERSION=5.0.0`. That tag check uses outbound HTTPS to GitHub; restricted
+runners that cannot reach GitHub should leave `CPFLOW_VERSION` unset and build
+`cpflow` from the checked-out ref instead. When testing an unreleased upstream
+commit SHA, leave `CPFLOW_VERSION` unset so the workflow builds `cpflow` from the
+same source that supplies the reusable workflow and composite actions.
 
 ## Testing Unreleased Upstream Changes Downstream
 
@@ -319,7 +497,10 @@ releasing it. Use an immutable commit SHA from the upstream PR branch:
    local experiments that should not be committed.
 
 3. Keep `CPFLOW_VERSION` unset so the workflow builds `cpflow` from the same
-   upstream SHA that supplies the reusable workflow and composite actions.
+   upstream SHA that supplies the reusable workflow and composite actions. If
+   `CPFLOW_VERSION` is set while the wrapper is pinned to a SHA, the setup
+   action fails before deployment because the gem and action code cannot be
+   proven to match.
 4. Run:
 
    ```sh
@@ -343,8 +524,10 @@ releasing it. Use an immutable commit SHA from the upstream PR branch:
 6. Verify the deploy logs show the expected upstream commit SHA, the setup step
    prints the expected `cpflow` source/version, and the review app URL returns
    HTTP 200.
-7. After the upstream PR merges and a gem is released, regenerate or repin the
-   downstream wrappers to the release tag.
+7. After the upstream PR merges and a gem is released, regenerate the downstream
+   wrappers from that released gem and commit the release tag. Use
+   `bin/pin-cpflow-github-ref vX.Y.Z` only for a ref-only update when the
+   generated templates are already current.
 
 This tests the real reusable workflow, shared composite actions, and source-built
 `cpflow` gem from one immutable upstream commit. It avoids merging upstream blind
@@ -360,9 +543,12 @@ bin/test-cpflow-github-flow
 
 The helper runs `cpflow github-flow-readiness`, parses generated workflow YAML,
 checks composite action metadata for literal GitHub expressions in descriptions,
-checks that all generated wrappers use one upstream ref consistently, requires
-secret-inheriting reusable workflows to pass `control_plane_flow_ref`, and runs
-`actionlint -ignore "SC2129" .github/workflows/cpflow-*.yml`.
+checks that all generated wrappers use one upstream ref consistently, rejects
+broad `secrets: inherit` usage in generated cpflow wrappers, rejects obsolete
+`control_plane_flow_ref` wrapper inputs, and runs
+`actionlint` against `.github/workflows/cpflow-*.yml`. Its `actionlint` command
+keeps the existing shellcheck ignore and also ignores stale local `actionlint`
+false positives for GitHub's newer reusable-workflow `job.workflow_*` fields.
 
 ## Applying This to React on Rails Demo Apps
 
@@ -397,7 +583,7 @@ In practice, porting the flow into a demo app usually follows five phases.
 
 **Wire up GitHub secrets, variables, and private builds:**
 
-11. Make sure the repo variables and secrets line up with the configured app names.
+11. Make sure the repo variables and secrets line up with the configured app names. For production promotion, store `CPLN_TOKEN_PRODUCTION` only on a protected `production` GitHub Environment with required reviewers.
 12. If the Dockerfile pulls private dependencies over SSH, configure `DOCKER_BUILD_SSH_KEY`, add `DOCKER_BUILD_SSH_KNOWN_HOSTS` when the host is not GitHub.com, and validate that the image can build with `RUN --mount=type=ssh`.
 
 **Validate and push:**
@@ -417,7 +603,7 @@ current prompt with that repo's default app prefix already filled in.
 Short version:
 
 ```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, with published package versions and a production Dockerfile that can really build the app. Stop and report blockers for unpublished packages, inaccessible private dependencies, legacy toolchains, or missing production build paths instead of generating workflows blindly. Then run `cpflow generate` if `.controlplane/` is missing, run `cpflow generate-github-actions`, adapt the generated scaffold to the real workloads, document the required GitHub secrets and variables, validate the real build path locally, push the branch, and check the GitHub Actions results.
+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, with published package versions and a production Dockerfile that can really build the app. Stop and report blockers for unpublished packages, inaccessible private dependencies, legacy toolchains, or missing production build paths instead of generating workflows blindly. Then run `cpflow generate` if `.controlplane/` is missing, run `cpflow generate-github-actions`, adapt the generated scaffold to the real workloads, document the required GitHub secrets and variables, validate the real build path locally, push the branch, and check the GitHub Actions results. Keep production promotion safe by documenting `CPLN_TOKEN_PRODUCTION` as a protected `production` GitHub Environment secret, not a repository or organization secret.
 ```
 
 Expand that prompt with app-specific requirements before editing files:

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.
+        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.0"
+  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 && \
@@ -78,6 +83,7 @@ RUN rails assets:precompile
 
 # add entrypoint
 COPY .controlplane/entrypoint.sh ./
+RUN chmod +x /app/entrypoint.sh
 ENTRYPOINT ["/app/entrypoint.sh"]
 
 CMD ["rails", "s"]

data/lib/generator_templates/entrypoint.sh

@@ -1,8 +1,48 @@
 #!/bin/sh
+set -e
 # Runs before the main command
 
-echo " -- Preparing database"
-rails db:prepare
+is_rails_server_command() {
+  if [ "${1:-}" = "env" ]; then
+    shift
+    while [ "$#" -gt 0 ]; do
+      case "${1}" in
+        *=*) shift ;;
+        --) shift; break ;;
+        -*) return 1 ;;
+        *) break ;;
+      esac
+    done
+  fi
+
+  if [ "${1:-}" = "bundle" ] && [ "${2:-}" = "exec" ]; then
+    shift 2
+  fi
+
+  # Matches generated, optionally env-prefixed, flag-free Thruster invocations.
+  # Hand-edited commands with env flags or Thruster flags before rails skip
+  # generated DB prep.
+  if [ "${1:-}" = "thrust" ] || [ "${1:-}" = "bin/thrust" ] || [ "${1:-}" = "./bin/thrust" ]; then
+    shift
+  fi
+
+  # Thruster may be wrapped with its own `bundle exec`, and the Rails command
+  # it proxies may also be wrapped with `bundle exec`.
+  if [ "${1:-}" = "bundle" ] && [ "${2:-}" = "exec" ]; then
+    shift 2
+  fi
+
+  { [ "${1:-}" = "rails" ] || [ "${1:-}" = "bin/rails" ] || [ "${1:-}" = "./bin/rails" ]; } &&
+    { [ "${2:-}" = "server" ] || [ "${2:-}" = "s" ]; }
+}
+
+# Match generated Rails server commands; workers and renderers skip DB prep.
+# Generated Dockerfiles use WORKDIR /app; adjust this path if your hand-edited
+# image runs the entrypoint from a different working directory.
+if is_rails_server_command "$@"; then
+  echo " -- Preparing database"
+  ./bin/rails db:prepare
+fi
 
 echo " -- Finishing entrypoint.sh, executing command"
 exec "$@"

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}}"