Skip to content

Document cpflow app bootstrap #748

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
justin808 merged 1 commit into from
May 25, 2026
+43 −0
Merged

Document cpflow app bootstrap #748

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions .controlplane/readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,21 @@ The matching Control Plane resources are:
| Staging app | `react-webpack-rails-tutorial-staging` |
| Staging app secret dictionary | `react-webpack-rails-tutorial-staging-secrets` |

Bootstrap the persistent staging app once before the first merge-to-master
deploy:

```sh
cpflow setup-app -a react-webpack-rails-tutorial-staging --org shakacode-open-source-examples-staging --skip-post-creation-hook
```
Comment on lines +60 to +65
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot May 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Use apply-template for persistent app bootstrap

This new guidance tells operators to run cpflow setup-app for the persistent staging app, but the upstream command docs explicitly scope setup-app to temporary apps and direct persistent staging/production flows to cpflow apply-template. If someone follows this during first-time staging/production setup, they can run an unsupported path that creates/recreates full app resources instead of the documented persistent update flow, which risks unexpected infra changes in long-lived environments.

Useful? React with 👍 / 👎.


`setup-app` reads `setup_app_templates` from `.controlplane/controlplane.yml`
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 a Docker image exists. For
later template updates on an existing persistent app, use
`cpflow apply-template` and make sure the app identity still has `reveal`
permission on the app secret policy.

### Production Promotion

Production promotion is part of the default demo flow, but the production token
Expand All @@ -81,6 +96,9 @@ The matching Control Plane resources are:
| Production app | `react-webpack-rails-tutorial-production` |
| Production app secret dictionary | `react-webpack-rails-tutorial-production-secrets` |

Bootstrap production the same way before the first promotion, using the
Copy link
Copy Markdown

@claude claude Bot May 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The staging section above gives the full explicit command; this production note only says "the same way" without showing it. A reader who lands on the Production section directly (or who uses different org/app names) has to scroll up and mentally substitute values. Consider showing the production-specific command here, as shakacode-team.md already does:

Suggested change
Bootstrap production the same way before the first promotion, using the
Bootstrap production once before the first promotion:
```sh
cpflow setup-app -a react-webpack-rails-tutorial-production --org shakacode-open-source-examples-production --skip-post-creation-hook

Use the production org and production-only secret values.

production org and production-only secret values.

All review, staging, and production secret dictionaries need these app runtime
secrets:

Expand Down
12 changes: 12 additions & 0 deletions .controlplane/shakacode-team.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,18 @@ Generated caller workflows pass only the named secrets each upstream workflow
needs. They do not use `secrets: inherit`; `CPLN_TOKEN_PRODUCTION` is supplied
only by the protected `production` Environment after approval.

Persistent staging and production apps must be bootstrapped once before the
first deploy or promotion:

```sh
cpflow setup-app -a react-webpack-rails-tutorial-staging --org shakacode-open-source-examples-staging --skip-post-creation-hook
cpflow setup-app -a react-webpack-rails-tutorial-production --org shakacode-open-source-examples-production --skip-post-creation-hook
```

Use `setup-app` for first-time bootstrap because it creates the app secret
policy and identity binding. Use `cpflow apply-template` for later template
updates to existing persistent apps.

Advanced optional settings are documented upstream in the
[`control-plane-flow` CI automation guide](https://github.com/shakacode/control-plane-flow/blob/main/docs/ci-automation.md).

Expand Down
13 changes: 13 additions & 0 deletions .github/cpflow-help.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,16 @@ Optional overrides exist for forks, clones, and unusual apps:
## Staging And Production

Copy link
Copy Markdown

@claude claude Bot May 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's no blank line between the existing "Staging deploys use the same..." sentence and this new paragraph. Without one, the two sentences render as a single paragraph in Markdown. Adding a blank line makes the boundary between the context sentence and the action step clear.

Suggested change
Staging deploys use the same `CPLN_TOKEN_STAGING` secret plus `STAGING_APP_NAME`.
Before the first staging deploy, bootstrap the persistent staging app once:

Staging deploys use the same `CPLN_TOKEN_STAGING` secret plus `STAGING_APP_NAME`.
Before the first staging deploy, bootstrap the persistent staging app once:
Comment on lines 41 to +42
Copy link
Copy Markdown

@greptile-apps greptile-apps Bot May 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 The new paragraph starts immediately after the previous sentence with no blank line separating them, so Markdown renders both sentences as one flowing paragraph rather than two distinct ones. Adding a blank line preserves the intended paragraph break.

Suggested change
Staging deploys use the same `CPLN_TOKEN_STAGING` secret plus `STAGING_APP_NAME`.
Before the first staging deploy, bootstrap the persistent staging app once:
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` creates the app identity, app secret dictionary, app secret policy,
policy binding, and template resources. For later template updates on an
existing persistent app, use `cpflow apply-template` and make sure the app
identity has `reveal` permission on the app secret policy.

Production promotion is part of the generated flow, but keep it protected:

Expand All @@ -53,6 +63,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
Expand Down
Loading