Skip to content

cpflow-help.md

Latest commit

 

History

History
74 lines (56 loc) · 4.55 KB

cpflow-help.md

File metadata and controls

74 lines (56 loc) · 4.55 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) Service-account token scoped to the production Control Plane org on controlplane.com.
DOCKER_BUILD_SSH_KEY optional Private SSH key used when Docker builds fetch private deps via RUN --mount=type=ssh.

GitHub Actions variables

Name Required Notes
CPLN_ORG_STAGING yes Control Plane org on controlplane.com for staging and review apps.
CPLN_ORG_PRODUCTION yes (for promote) Control Plane org on controlplane.com for production.
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.
REVIEW_APP_PREFIX yes Prefix for per-PR review app names (e.g. review-app).
REVIEW_APP_DEPLOYING_ICON_URL optional 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 Runtime gem-install override. When unset, cpflow is built from the pinned upstream workflow ref. When set, use the RubyGems version without a leading v.
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.