cpflow 4.1.1 → 5.0.0.rc.0

data/lib/github_flow_templates/.github/workflows/cpflow-deploy-review-app.yml

@@ -0,0 +1,445 @@
+name: Deploy Review App to Control Plane
+
+run-name: "Deploy Review App - PR #${{ github.event.pull_request.number || github.event.issue.number || github.event.inputs.pr_number }}"
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  issue_comment:
+    types: [created]
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: Pull request number to deploy
+        required: true
+        type: number
+
+permissions:
+  contents: read
+  deployments: write
+  issues: write
+  pull-requests: write
+
+concurrency:
+  group: cpflow-review-app-${{ github.event.pull_request.number || github.event.issue.number || github.event.inputs.pr_number }}
+  # Match the delete workflow: a cancelled `cpflow deploy-image` mid-rollout can leave the
+  # review app in a partially-deployed state (workload update in progress, rollout not
+  # settled). Let an in-flight deploy finish before the next push starts a new run.
+  cancel-in-progress: false
+
+env:
+  APP_NAME: ${{ vars.REVIEW_APP_PREFIX }}-${{ github.event.pull_request.number || github.event.issue.number || github.event.inputs.pr_number }}
+  CPLN_ORG: ${{ vars.CPLN_ORG_STAGING }}
+  PR_NUMBER: ${{ github.event.pull_request.number || github.event.issue.number || github.event.inputs.pr_number }}
+  PRIMARY_WORKLOAD: ${{ vars.PRIMARY_WORKLOAD }}
+
+jobs:
+  deploy:
+    # Skip synchronize/opened events from fork PRs at the job level — they cannot access
+    # repository secrets anyway, so running any steps just burns billable minutes. Users
+    # can still manually deploy a fork PR via `/deploy-review-app` (gated below by
+    # author_association) or workflow_dispatch.
+    if: |
+      (github.event_name == 'pull_request' &&
+       github.event.pull_request.head.repo.full_name == github.repository) ||
+      github.event_name == 'workflow_dispatch' ||
+      (github.event_name == 'issue_comment' &&
+       github.event.issue.pull_request &&
+       github.event.comment.body == '/deploy-review-app' &&
+       contains(fromJson('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association))
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+
+    steps:
+      - name: Checkout trusted workflow sources
+        uses: actions/checkout@v4
+        with:
+          # Keep generated composite actions on the trusted base branch. The PR
+          # application code is checked out separately under ./app after source
+          # validation so same-repo PRs cannot replace local actions before
+          # staging secrets are passed to them.
+          ref: ${{ github.event.repository.default_branch }}
+          persist-credentials: false
+
+      - name: Validate required secrets and variables
+        id: config
+        uses: ./.github/actions/cpflow-validate-config
+        env:
+          CPLN_TOKEN_STAGING: ${{ secrets.CPLN_TOKEN_STAGING }}
+          CPLN_ORG_STAGING: ${{ vars.CPLN_ORG_STAGING }}
+          REVIEW_APP_PREFIX: ${{ vars.REVIEW_APP_PREFIX }}
+        with:
+          required: |
+            secret:CPLN_TOKEN_STAGING
+            variable:CPLN_ORG_STAGING
+            variable:REVIEW_APP_PREFIX
+          pull_request_friendly: "true"
+
+      - name: Resolve PR ref and commit
+        if: steps.config.outputs.ready == 'true'
+        id: resolve-pr
+        env:
+          # Route every GitHub-controlled input through env so the run script never
+          # interpolates ${{ ... }} into shell. All values here are GitHub-controlled
+          # (not user-influenced), so this is for consistency with the rest of the
+          # workflow and to quiet actionlint/StepSecurity, not a fix for an
+          # exploitable injection.
+          EVENT_NAME: ${{ github.event_name }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DISPATCH_PR_NUMBER: ${{ github.event.inputs.pr_number }}
+          ISSUE_NUMBER: ${{ github.event.issue.number }}
+          PR_EVENT_NUMBER: ${{ github.event.pull_request.number }}
+          REVIEW_APP_PREFIX: ${{ vars.REVIEW_APP_PREFIX }}
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          case "${EVENT_NAME}" in
+            workflow_dispatch)
+              pr_number="${DISPATCH_PR_NUMBER}"
+              ;;
+            issue_comment)
+              pr_number="${ISSUE_NUMBER}"
+              ;;
+            pull_request)
+              pr_number="${PR_EVENT_NUMBER}"
+              ;;
+            *)
+              echo "Unsupported event type: ${EVENT_NAME}" >&2
+              exit 1
+              ;;
+          esac
+
+          pr_data="$(gh pr view "$pr_number" --json headRefOid,headRepository,headRepositoryOwner)"
+          pr_sha="$(echo "$pr_data" | jq -r '.headRefOid')"
+          pr_repository="$(echo "$pr_data" | jq -r '[.headRepositoryOwner.login, .headRepository.name] | join("/")')"
+          same_repo="false"
+
+          if [[ "$pr_repository" == "$GITHUB_REPOSITORY" ]]; then
+            same_repo="true"
+          fi
+
+          echo "PR_NUMBER=$pr_number" >> "$GITHUB_ENV"
+          echo "APP_NAME=${REVIEW_APP_PREFIX}-$pr_number" >> "$GITHUB_ENV"
+          echo "PR_SHA=$pr_sha" >> "$GITHUB_ENV"
+          echo "same_repo=${same_repo}" >> "$GITHUB_OUTPUT"
+
+      - name: Validate review app deployment source
+        if: steps.config.outputs.ready == 'true'
+        id: source
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          # Same env-routing pattern as Resolve PR ref and commit above: keep all
+          # ${{ ... }} values out of the run script.
+          SAME_REPO: ${{ steps.resolve-pr.outputs.same_repo }}
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          if [[ "${SAME_REPO}" == "true" ]]; then
+            echo "allowed=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          if [[ "${EVENT_NAME}" == "pull_request" ]]; then
+            echo "allowed=false" >> "$GITHUB_OUTPUT"
+            {
+              echo "Review app deploys are skipped for fork pull requests."
+              echo "This workflow builds Docker images with repository secrets, so review app deploys only run for branches in the base repository."
+            } >> "$GITHUB_STEP_SUMMARY"
+            exit 0
+          fi
+
+          if [[ "${EVENT_NAME}" == "issue_comment" ]]; then
+            echo "allowed=false" >> "$GITHUB_OUTPUT"
+            {
+              echo "Review app deploys from fork pull requests require a branch in ${GITHUB_REPOSITORY}."
+              echo "This workflow builds Docker images with repository secrets, so comment-triggered deploys only run for branches in the base repository."
+            } >> "$GITHUB_STEP_SUMMARY"
+            exit 0
+          fi
+
+          echo "Review app deploys from fork pull requests are not allowed for workflow_dispatch because this workflow uses repository secrets." >&2
+          exit 1
+
+      - name: Checkout PR commit
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true'
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ env.PR_SHA }}
+          path: app
+          persist-credentials: false
+
+      - name: Remove PR checkout Git metadata
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true'
+        shell: bash
+        run: |
+          set -euo pipefail
+          rm -rf app/.git
+
+      - name: Setup environment
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true'
+        uses: ./.github/actions/cpflow-setup-environment
+        with:
+          token: ${{ secrets.CPLN_TOKEN_STAGING }}
+          org: ${{ vars.CPLN_ORG_STAGING }}
+          cpln_cli_version: ${{ vars.CPLN_CLI_VERSION }}
+          cpflow_version: ${{ vars.CPFLOW_VERSION }}
+
+      - name: Detect release phase support
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true'
+        id: release-phase
+        uses: ./.github/actions/cpflow-detect-release-phase
+        with:
+          app_name: ${{ env.APP_NAME }}
+          working_directory: app
+
+      - name: Check if review app exists
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true'
+        id: check-app
+        working-directory: app
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          exists_output=""
+          set +e
+          exists_output="$(cpflow exists -a "${APP_NAME}" --org "${CPLN_ORG}" 2>&1)"
+          exists_status=$?
+          set -e
+
+          case "${exists_status}" in
+            0)
+              if [[ -n "${exists_output}" ]]; then
+                printf '%s\n' "${exists_output}"
+              fi
+              echo "exists=true" >> "$GITHUB_OUTPUT"
+              ;;
+            3)
+              if [[ -n "${exists_output}" ]]; then
+                printf '%s\n' "${exists_output}"
+              fi
+              echo "exists=false" >> "$GITHUB_OUTPUT"
+              ;;
+            *)
+              echo "::error::cpflow exists returned unexpected exit code ${exists_status} for ${APP_NAME}" >&2
+              if [[ -n "${exists_output}" ]]; then
+                printf '%s\n' "${exists_output}" >&2
+              fi
+              exit "${exists_status}"
+              ;;
+          esac
+
+      - name: Skip auto deploy until a review app is created
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true' && steps.check-app.outputs.exists != 'true' && github.event_name == 'pull_request'
+        shell: bash
+        run: |
+          {
+            echo "Review app ${APP_NAME} does not exist yet."
+            echo "Create it with a PR comment that is exactly /deploy-review-app."
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Setup review app if it does not exist yet
+        id: setup-review-app
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true' && steps.check-app.outputs.exists != 'true' && github.event_name != 'pull_request'
+        working-directory: app
+        shell: bash
+        run: |
+          set -euo pipefail
+          cpflow setup-app -a "${APP_NAME}" --org "${CPLN_ORG}"
+
+      - name: Create initial PR comment
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true' && (steps.check-app.outputs.exists == 'true' || steps.setup-review-app.outcome == 'success')
+        id: create-comment
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const result = await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: Number(process.env.PR_NUMBER),
+              body: "🚀 Starting Control Plane review app deployment..."
+            });
+            core.setOutput("comment-id", result.data.id);
+
+      - name: Set deployment links
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true' && (steps.check-app.outputs.exists == 'true' || steps.setup-review-app.outcome == 'success')
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const workflowUrl = `${process.env.GITHUB_SERVER_URL}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
+            core.exportVariable("WORKFLOW_URL", workflowUrl);
+            core.exportVariable(
+              "CONSOLE_URL",
+              `https://console.cpln.io/console/org/${process.env.CPLN_ORG}/gvc/${process.env.APP_NAME}/-info`
+            );
+
+      - name: Initialize GitHub deployment
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true' && (steps.check-app.outputs.exists == 'true' || steps.setup-review-app.outcome == 'success')
+        id: init-deployment
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const deployment = await github.rest.repos.createDeployment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              ref: process.env.PR_SHA,
+              environment: `review/${process.env.APP_NAME}`,
+              auto_merge: false,
+              required_contexts: [], // intentional: review apps deploy regardless of required status checks
+              description: `Control Plane review app for PR #${process.env.PR_NUMBER}`
+            });
+
+            await github.rest.repos.createDeploymentStatus({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              deployment_id: deployment.data.id,
+              state: "in_progress",
+              description: "Deployment started"
+            });
+
+            return deployment.data.id;
+
+      - name: Update PR comment with build status
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true' && (steps.check-app.outputs.exists == 'true' || steps.setup-review-app.outcome == 'success')
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const commentId = Number("${{ steps.create-comment.outputs.comment-id }}");
+            if (!Number.isFinite(commentId) || commentId <= 0) {
+              core.warning("Skipping PR comment update because no comment id was created.");
+              return;
+            }
+
+            const body = [
+              `🏗️ Building Docker image for PR #${process.env.PR_NUMBER}, commit ${process.env.PR_SHA}`,
+              "",
+              `[View build logs](${process.env.WORKFLOW_URL})`,
+              "",
+              `[Open Control Plane console](${process.env.CONSOLE_URL})`
+            ].join("\n");
+
+            await github.rest.issues.updateComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              comment_id: commentId,
+              body
+            });
+
+      - name: Build Docker image
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true' && (steps.check-app.outputs.exists == 'true' || steps.setup-review-app.outcome == 'success')
+        uses: ./.github/actions/cpflow-build-docker-image
+        with:
+          app_name: ${{ env.APP_NAME }}
+          org: ${{ vars.CPLN_ORG_STAGING }}
+          commit: ${{ env.PR_SHA }}
+          pr_number: ${{ env.PR_NUMBER }}
+          docker_build_extra_args: ${{ vars.DOCKER_BUILD_EXTRA_ARGS }}
+          docker_build_ssh_key: ${{ secrets.DOCKER_BUILD_SSH_KEY }}
+          docker_build_ssh_known_hosts: ${{ vars.DOCKER_BUILD_SSH_KNOWN_HOSTS }}
+          working_directory: app
+
+      - name: Update PR comment with deploy status
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true' && (steps.check-app.outputs.exists == 'true' || steps.setup-review-app.outcome == 'success')
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const commentId = Number("${{ steps.create-comment.outputs.comment-id }}");
+            if (!Number.isFinite(commentId) || commentId <= 0) {
+              core.warning("Skipping PR comment update because no comment id was created.");
+              return;
+            }
+
+            const body = [
+              "🚀 Deploying review app to Control Plane...",
+              "",
+              `[View deploy logs](${process.env.WORKFLOW_URL})`,
+              "",
+              `[Open Control Plane console](${process.env.CONSOLE_URL})`
+            ].join("\n");
+
+            await github.rest.issues.updateComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              comment_id: commentId,
+              body
+            });
+
+      - name: Deploy to Control Plane
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true' && (steps.check-app.outputs.exists == 'true' || steps.setup-review-app.outcome == 'success')
+        working-directory: app
+        env:
+          RELEASE_PHASE_FLAG: ${{ steps.release-phase.outputs.flag }}
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          deploy_args=(-a "${APP_NAME}")
+          if [[ -n "${RELEASE_PHASE_FLAG}" ]]; then
+            deploy_args+=("${RELEASE_PHASE_FLAG}")
+          fi
+          deploy_args+=(--org "${CPLN_ORG}" --verbose)
+
+          cpflow deploy-image "${deploy_args[@]}"
+
+      - name: Retrieve app URL
+        if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true' && (steps.check-app.outputs.exists == 'true' || steps.setup-review-app.outcome == 'success')
+        id: workload
+        working-directory: app
+        shell: bash
+        run: |
+          set -euo pipefail
+          workload_name="${PRIMARY_WORKLOAD:-rails}"
+          workload_url="$(cpln workload get "${workload_name}" --gvc "${APP_NAME}" --org "${CPLN_ORG}" -o json | jq -r '.status.endpoint // empty')"
+          echo "workload_url=${workload_url}" >> "$GITHUB_OUTPUT"
+
+      - name: Finalize deployment status
+        if: always() && steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true' && (steps.check-app.outputs.exists == 'true' || steps.setup-review-app.outcome == 'success')
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const commentId = Number("${{ steps.create-comment.outputs.comment-id }}");
+            const deploymentId = "${{ steps.init-deployment.outputs.result }}";
+            const appUrl = "${{ steps.workload.outputs.workload_url }}";
+            const success = "${{ job.status }}" === "success";
+
+            if (deploymentId) {
+              await github.rest.repos.createDeploymentStatus({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                deployment_id: Number(deploymentId),
+                state: success ? "success" : "failure",
+                environment: `review/${process.env.APP_NAME}`,
+                environment_url: success && appUrl ? appUrl : undefined,
+                log_url: process.env.WORKFLOW_URL,
+                description: success ? "Review app ready" : "Review app deployment failed"
+              });
+            }
+
+            const successBody = [
+              "## Review app ready",
+              "",
+              appUrl ? `[Open review app](${appUrl})` : "Review app deployed, but no endpoint URL was detected.",
+              "",
+              `[Open Control Plane console](${process.env.CONSOLE_URL})`,
+              `[View workflow logs](${process.env.WORKFLOW_URL})`
+            ].join("\n");
+
+            const failureBody = [
+              `❌ Review app deployment failed for PR #${process.env.PR_NUMBER}`,
+              "",
+              `[Open Control Plane console](${process.env.CONSOLE_URL})`,
+              `[View workflow logs](${process.env.WORKFLOW_URL})`
+            ].join("\n");
+
+            if (!Number.isFinite(commentId) || commentId <= 0) {
+              core.warning("Skipping PR comment update because no comment id was created.");
+              return;
+            }
+
+            await github.rest.issues.updateComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              comment_id: commentId,
+              body: success ? successBody : failureBody
+            });

data/lib/github_flow_templates/.github/workflows/cpflow-deploy-staging.yml

@@ -0,0 +1,140 @@
+name: Deploy Staging to Control Plane
+
+run-name: Deploy Control Plane staging app
+
+on:
+  push:
+    # GitHub does not allow repository vars in branch filters. Default to the common
+    # deploy branches unless `cpflow generate-github-actions --staging-branch BRANCH`
+    # was used. If STAGING_APP_BRANCH is later changed in repository variables, keep
+    # this list in sync so pushes to that branch actually trigger the workflow.
+    branches: [__STAGING_BRANCH_FILTER__]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  APP_NAME: ${{ vars.STAGING_APP_NAME }}
+  CPLN_ORG: ${{ vars.CPLN_ORG_STAGING }}
+  STAGING_APP_BRANCH: __STAGING_APP_BRANCH_EXPRESSION__
+
+concurrency:
+  group: cpflow-deploy-staging-${{ github.ref_name }}
+  # Match the review-app and delete workflows: a cancelled `cpflow deploy-image` mid-rollout
+  # can leave the staging GVC in a partially-deployed state (some workloads on the new image,
+  # others on the old). Let an in-flight deploy finish before the next push starts a new run.
+  cancel-in-progress: false
+
+jobs:
+  validate-branch:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      is_deployable: ${{ steps.check-branch.outputs.is_deployable }}
+    steps:
+      - name: Check whether this branch should deploy staging
+        id: check-branch
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          if [[ -n "${STAGING_APP_BRANCH}" ]]; then
+            if [[ "${GITHUB_REF_NAME}" == "${STAGING_APP_BRANCH}" ]]; then
+              echo "is_deployable=true" >> "$GITHUB_OUTPUT"
+            else
+              echo "Branch '${GITHUB_REF_NAME}' does not match STAGING_APP_BRANCH='${STAGING_APP_BRANCH}'"
+              echo "is_deployable=false" >> "$GITHUB_OUTPUT"
+            fi
+          elif [[ "${GITHUB_REF_NAME}" == "main" || "${GITHUB_REF_NAME}" == "master" ]]; then
+            echo "is_deployable=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "Branch '${GITHUB_REF_NAME}' is not main/master and no STAGING_APP_BRANCH is configured"
+            echo "is_deployable=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Checkout repository
+        if: steps.check-branch.outputs.is_deployable == 'true'
+        uses: actions/checkout@v4
+
+      - name: Validate required secrets and variables
+        if: steps.check-branch.outputs.is_deployable == 'true'
+        uses: ./.github/actions/cpflow-validate-config
+        env:
+          CPLN_TOKEN_STAGING: ${{ secrets.CPLN_TOKEN_STAGING }}
+          CPLN_ORG_STAGING: ${{ vars.CPLN_ORG_STAGING }}
+          STAGING_APP_NAME: ${{ vars.STAGING_APP_NAME }}
+        with:
+          required: |
+            secret:CPLN_TOKEN_STAGING
+            variable:CPLN_ORG_STAGING
+            variable:STAGING_APP_NAME
+
+  build:
+    needs: validate-branch
+    if: needs.validate-branch.outputs.is_deployable == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Setup environment
+        uses: ./.github/actions/cpflow-setup-environment
+        with:
+          token: ${{ secrets.CPLN_TOKEN_STAGING }}
+          org: ${{ vars.CPLN_ORG_STAGING }}
+          cpln_cli_version: ${{ vars.CPLN_CLI_VERSION }}
+          cpflow_version: ${{ vars.CPFLOW_VERSION }}
+
+      - name: Build Docker image
+        uses: ./.github/actions/cpflow-build-docker-image
+        with:
+          app_name: ${{ env.APP_NAME }}
+          org: ${{ vars.CPLN_ORG_STAGING }}
+          commit: ${{ github.sha }}
+          docker_build_extra_args: ${{ vars.DOCKER_BUILD_EXTRA_ARGS }}
+          docker_build_ssh_key: ${{ secrets.DOCKER_BUILD_SSH_KEY }}
+          docker_build_ssh_known_hosts: ${{ vars.DOCKER_BUILD_SSH_KNOWN_HOSTS }}
+
+  deploy:
+    needs: [validate-branch, build]
+    if: needs.validate-branch.outputs.is_deployable == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Setup environment
+        uses: ./.github/actions/cpflow-setup-environment
+        with:
+          token: ${{ secrets.CPLN_TOKEN_STAGING }}
+          org: ${{ vars.CPLN_ORG_STAGING }}
+          cpln_cli_version: ${{ vars.CPLN_CLI_VERSION }}
+          cpflow_version: ${{ vars.CPFLOW_VERSION }}
+
+      - name: Detect release phase support
+        id: release-phase
+        uses: ./.github/actions/cpflow-detect-release-phase
+        with:
+          app_name: ${{ env.APP_NAME }}
+
+      - name: Deploy staging image
+        env:
+          RELEASE_PHASE_FLAG: ${{ steps.release-phase.outputs.flag }}
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          deploy_args=(-a "${APP_NAME}")
+          if [[ -n "${RELEASE_PHASE_FLAG}" ]]; then
+            deploy_args+=("${RELEASE_PHASE_FLAG}")
+          fi
+          deploy_args+=(--org "${CPLN_ORG}" --verbose)
+
+          cpflow deploy-image "${deploy_args[@]}"

data/lib/github_flow_templates/.github/workflows/cpflow-help-command.yml

@@ -0,0 +1,53 @@
+name: Review App Help Command
+
+on:
+  issue_comment:
+    types: [created]
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: Pull request number to post help on
+        required: true
+        type: number
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+jobs:
+  help:
+    if: |
+      (github.event_name == 'issue_comment' &&
+       github.event.issue.pull_request &&
+       github.event.comment.body == '/help' &&
+       contains(fromJson('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)) ||
+      github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          # Help only reads `.github/cpflow-help.md`; no git push happens, so drop the
+          # GITHUB_TOKEN credential helper to keep the token out of .git/config.
+          persist-credentials: false
+
+      - name: Post help message
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require("fs");
+            const helpText = fs.readFileSync(".github/cpflow-help.md", "utf8");
+
+            const prNumber = context.eventName === "workflow_dispatch"
+              ? Number(context.payload.inputs.pr_number)
+              : context.issue.number;
+
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: prNumber,
+              body: helpText
+            });