Skip to content

cpflow-help.md

Latest commit

 

History

History
125 lines (95 loc) · 7.31 KB

cpflow-help.md

File metadata and controls

125 lines (95 loc) · 7.31 KB
Raw

Review app help

You asked for review app help. These commands are generated by cpflow.

PR commands

+review-app-deploy

  • Creates the review app if it does not exist
  • Builds the PR commit image
  • Deploys the image and comments with the review URL
  • Comment body must be exactly +review-app-deploy, with no surrounding text or trailing spaces. A single trailing newline from GitHub's comment editor is accepted. Comments like please +review-app-deploy now or +review-app-deploy (with a trailing space) silently no-op.

+review-app-delete

  • Deletes the review app when the PR is done
  • This also runs automatically when the PR closes
  • Comment body must be exactly +review-app-delete, with no surrounding text or trailing spaces. A single trailing newline from GitHub's comment editor is accepted. Same command-match rule as +review-app-deploy.

+review-app-help

  • Posts this message on the PR.
  • Comment body must be exactly +review-app-help, with no surrounding text or trailing spaces. A single trailing newline from GitHub's comment editor is accepted. Same command-match rule as +review-app-deploy.

Workflow behavior

  • Review apps are opt-in and created with +review-app-deploy
  • New commits redeploy existing review apps automatically
  • Pushes to the staging branch deploy staging automatically
  • Promotion to production is manual via the Actions tab
  • A nightly workflow removes stale review apps
Advanced: GitHub Actions secrets and variables

GitHub Actions secrets

Name Required Notes
CPLN_TOKEN_STAGING yes Service-account token scoped to the staging Control Plane org on controlplane.com.
CPLN_TOKEN_PRODUCTION yes (for promote) Store this as a secret on the protected production GitHub Environment, not as a repository or organization secret.
DOCKER_BUILD_SSH_KEY optional Private SSH key used when Docker builds fetch private deps via RUN --mount=type=ssh.

For normal generated review apps, CPLN_TOKEN_STAGING is the only required GitHub setting. The review app prefix and staging org are inferred from .controlplane/controlplane.yml when it defines exactly one app with match_if_app_name_starts_with: true.

For production promotion, create a GitHub Environment named production, add required reviewers, enable prevent self-review, and store CPLN_TOKEN_PRODUCTION as an environment secret there. The generated promotion workflow uses that environment before it can access production secrets.

GitHub Actions variables

Name Required Notes
CPLN_ORG_STAGING optional for review apps; yes for staging Override the staging/review Control Plane org inferred from controlplane.yml.
CPLN_ORG_PRODUCTION yes (for promote) Control Plane org on controlplane.com for production. Prefer a production environment variable.
STAGING_APP_NAME yes App name in controlplane.yml used as the staging deploy target.
PRODUCTION_APP_NAME yes (for promote) App name in controlplane.yml used as the production deploy target. Prefer a production environment variable.
REVIEW_APP_PREFIX optional Override or disambiguate the review app prefix inferred from controlplane.yml.
REVIEW_APP_DEPLOYING_ICON_URL optional, advanced Cosmetic custom image URL for the animated deploying icon in review-app PR comments. Set to none to use the text fallback icon.
STAGING_APP_BRANCH optional Custom staging branch. Custom branches must also appear in cpflow-deploy-staging.yml's push filter.
PRIMARY_WORKLOAD optional Workload polled for health and rollback (defaults to rails).
DOCKER_BUILD_EXTRA_ARGS optional Newline-delimited extra docker build tokens (e.g. --build-arg=FOO=bar).
DOCKER_BUILD_SSH_KNOWN_HOSTS optional SSH known_hosts entries when SSH build hosts are not GitHub.com.
HEALTH_CHECK_ACCEPTED_STATUSES optional Space-separated HTTP statuses considered healthy on promote (default 200 301 302).
CPLN_CLI_VERSION optional Pin a specific @controlplane/cli version; falls back to the action default when unset.
CPFLOW_VERSION optional Pin a published RubyGems version such as 5.0.0 or 5.0.0.rc.1. Leave unset for normal generated workflows so the setup action builds cpflow from the same control-plane-flow GitHub ref used by the reusable workflow.
Advanced: testing unreleased control-plane-flow changes

Generated workflow wrappers have two related pins:

  • The uses: shakacode/control-plane-flow/...@<ref> GitHub ref selects the reusable workflow code.
  • The control_plane_flow_ref: <ref> input tells the setup action which control-plane-flow source to check out and build when CPFLOW_VERSION is empty.

The GitHub ref is the runtime lock for workflow and action behavior. The RubyGems version is used to generate/update these wrappers and, only when CPFLOW_VERSION is set, to install the cpflow CLI at runtime. A downstream repo cannot rely on the gem alone because GitHub loads reusable workflow YAML from shakacode/control-plane-flow, not from RubyGems.

For normal releases, point both pins at a release tag such as v5.0.0. You may leave CPFLOW_VERSION unset, or set it to the matching RubyGems version without the leading v, such as 5.0.0. If you set CPFLOW_VERSION for a prerelease, use RubyGems dot syntax such as 5.0.0.rc.1; the release tag may use either v5.0.0.rc.1 or v5.0.0-rc.1.

To update to a new stable release, install or bundle the new cpflow gem, run cpflow generate-github-actions, and commit the regenerated wrappers. Use bin/pin-cpflow-github-ref vX.Y.Z only when the generated files are already current and you only need to move the upstream GitHub ref.

For temporary downstream testing of an upstream PR before a gem is released, pin both values to the exact 40-character commit SHA and leave CPFLOW_VERSION unset:

bin/pin-cpflow-github-ref <40-character-control-plane-flow-commit-sha>
bin/test-cpflow-github-flow ruby /path/to/control-plane-flow/bin/cpflow

Do not leave downstream apps pinned to a moving branch such as main. A branch can pick up beta or work-in-progress changes without a downstream PR changing. Use commit SHAs for short-lived PR testing, then switch to the release tag once the gem and tag exist.

Advanced: testing changes to generated workflows

When iterating on the generated workflow YAML on a PR branch, comment-triggered runs (+review-app-deploy, +review-app-delete, +review-app-help) execute the workflow code from the repository's default branch — not your PR branch. To exercise the PR-branch workflow code before merging, dispatch the workflow manually with gh:

gh workflow run cpflow-deploy-review-app.yml --ref <your-pr-branch> -f pr_number=<pr-number>
gh workflow run cpflow-delete-review-app.yml --ref <your-pr-branch> -f pr_number=<pr-number>
gh workflow run cpflow-help-command.yml      --ref <your-pr-branch> -f pr_number=<pr-number>

workflow_dispatch runs use the workflow file from the --ref you pass, so this is the supported way to test PR-branch workflow edits before merge. After merge, comment triggers go back to running the default-branch workflow code as usual.