cpflow 4.1.1 → 5.0.0.rc.0

data/lib/github_flow_templates/.github/actions/cpflow-setup-environment/action.yml

@@ -0,0 +1,98 @@
+name: Setup Control Plane Environment
+description: Sets up Ruby, installs the Control Plane CLI and cpflow gem, and configures a default profile
+
+inputs:
+  token:
+    description: Control Plane token
+    required: true
+  org:
+    description: Control Plane organization
+    required: true
+  ruby_version:
+    description: >-
+      Ruby version used for cpflow. When empty (the default), ruby/setup-ruby auto-detects
+      from .ruby-version, .tool-versions, or the Gemfile.
+    required: false
+    default: ""
+  cpln_cli_version:
+    description: >-
+      @controlplane/cli version. Empty string falls back to the action's pinned default
+      so callers can pass `${{ vars.CPLN_CLI_VERSION }}` unconditionally.
+    required: false
+    default: ""
+  cpflow_version:
+    description: >-
+      cpflow gem version. Empty string falls back to the action's pinned default
+      so callers can pass `${{ vars.CPFLOW_VERSION }}` unconditionally.
+    required: false
+    default: ""
+
+runs:
+  using: composite
+  # Third-party actions are pinned to floating major tags (`@v4`, `@v1`, `@v7`) rather than
+  # immutable SHAs. SHA pinning is GitHub's stronger security recommendation, but for
+  # generated templates that ship into many downstream repositories floating tags are
+  # easier for users to keep current and Dependabot/Renovate already cover the SHA-pinning
+  # workflow for repositories that opt in. Repositories with stricter supply-chain
+  # requirements should replace each `uses: actions/...@vN` with the corresponding
+  # immutable commit SHA.
+  steps:
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ inputs.ruby_version }}
+
+    - name: Install Control Plane CLI and cpflow gem
+      shell: bash
+      env:
+        CPLN_CLI_VERSION: ${{ inputs.cpln_cli_version }}
+        CPFLOW_VERSION: ${{ inputs.cpflow_version }}
+      run: |
+        set -euo pipefail
+
+        # Bump these defaults when a new release lands that you want to roll out by default.
+        # Override per-repo by setting `CPLN_CLI_VERSION` / `CPFLOW_VERSION` repo variables;
+        # an empty input falls back to the action's pinned default below.
+        default_cpln_cli_version="3.3.1"
+        default_cpflow_version="__CPFLOW_VERSION__"
+
+        CPLN_CLI_VERSION="${CPLN_CLI_VERSION:-${default_cpln_cli_version}}"
+        CPFLOW_VERSION="${CPFLOW_VERSION:-${default_cpflow_version}}"
+
+        npm_global_prefix="${HOME}/.npm-global"
+        mkdir -p "${npm_global_prefix}"
+        echo "${npm_global_prefix}/bin" >> "$GITHUB_PATH"
+        export PATH="${npm_global_prefix}/bin:${PATH}"
+
+        npm install --global --prefix "${npm_global_prefix}" "@controlplane/cli@${CPLN_CLI_VERSION}"
+        cpln --version
+
+        gem install cpflow -v "${CPFLOW_VERSION}" --no-document
+        cpflow --version
+
+    - name: Setup Control Plane profile and registry login
+      shell: bash
+      env:
+        # Pass the token via CPLN_TOKEN so cpln picks it up from the environment
+        # rather than `--token`, which would leak it into /proc/<pid>/cmdline and ps output.
+        CPLN_TOKEN: ${{ inputs.token }}
+        ORG: ${{ inputs.org }}
+      run: |
+        set -euo pipefail
+
+        if [[ -z "$CPLN_TOKEN" ]]; then
+          echo "Error: Control Plane token not provided" >&2
+          exit 1
+        fi
+
+        if [[ -z "$ORG" ]]; then
+          echo "Error: Control Plane organization not provided" >&2
+          exit 1
+        fi
+
+        # `cpln profile update` lists `create` as an alias (cpln profile --help) and is
+        # idempotent: it creates the profile if missing and updates it otherwise. Calling
+        # update directly avoids parsing the CLI's "already exists" English error text,
+        # which would silently swallow a real failure if the wording ever changed.
+        cpln profile update default --org "$ORG"
+        cpln image docker-login --org "$ORG"

data/lib/github_flow_templates/.github/actions/cpflow-validate-config/action.yml

@@ -0,0 +1,85 @@
+name: Validate cpflow GitHub configuration
+description: >-
+  Validates that required secrets and repository variables are set before a workflow
+  proceeds. Pass each value via `env:` with the same NAME as the secret or variable,
+  then list the required entries in `required` as `type:NAME` pairs (type is `secret`
+  or `variable`). When `pull_request_friendly: true` and the current event is a
+  pull request event, missing config writes a step summary and exits 0 with
+  `ready=false` instead of failing the job.
+
+inputs:
+  required:
+    description: |
+      Newline-separated `type:NAME` pairs. Type is `secret` or `variable`. The
+      caller MUST export the matching values via `env:` using the same NAME.
+    required: true
+  pull_request_friendly:
+    description: When "true" and event is pull_request/pull_request_target, write summary and exit 0 with ready=false.
+    required: false
+    default: "false"
+
+outputs:
+  ready:
+    description: '"true" when all values are set, "false" when missing in PR-friendly mode.'
+    value: ${{ steps.check.outputs.ready }}
+
+runs:
+  using: composite
+  steps:
+    - name: Check required secrets and variables
+      id: check
+      shell: bash
+      env:
+        CPFLOW_REQUIRED: ${{ inputs.required }}
+        CPFLOW_PR_FRIENDLY: ${{ inputs.pull_request_friendly }}
+        CPFLOW_EVENT_NAME: ${{ github.event_name }}
+      run: |
+        set -euo pipefail
+
+        missing=()
+        while IFS= read -r entry; do
+          entry="${entry%$'\r'}"
+          entry="${entry## }"
+          entry="${entry%% }"
+          [[ -z "${entry}" ]] && continue
+
+          type="${entry%%:*}"
+          name="${entry#*:}"
+
+          # Reject names that are not plain SHELL_VAR identifiers before doing the
+          # indirect lookup below. Without this guard, ${!name} would expand whatever
+          # bash nameref/transformation a hand-edited generated workflow snuck in
+          # (e.g. `BASH_FUNC_foo%%`). Callers today are the generated templates, but
+          # the generated file lives in the user's repo and can be hand-edited.
+          if [[ ! "${name}" =~ ^[A-Z_][A-Z0-9_]*$ ]]; then
+            echo "Invalid config entry name: ${name}" >&2
+            exit 1
+          fi
+
+          # Indirect bash lookup: reads the env var named by ${name} (e.g. CPLN_TOKEN_STAGING)
+          # so the value never has to round-trip through workflow logs.
+          if [[ -z "${!name:-}" ]]; then
+            missing+=("${type}:${name}")
+          fi
+        done <<< "${CPFLOW_REQUIRED}"
+
+        if [[ ${#missing[@]} -eq 0 ]]; then
+          echo "ready=true" >> "$GITHUB_OUTPUT"
+          exit 0
+        fi
+
+        if [[ "${CPFLOW_PR_FRIENDLY}" == "true" && ( "${CPFLOW_EVENT_NAME}" == "pull_request" || "${CPFLOW_EVENT_NAME}" == "pull_request_target" ) ]]; then
+          echo "ready=false" >> "$GITHUB_OUTPUT"
+          {
+            echo "Control Plane review app automation is not configured yet."
+            echo
+            echo "Missing required GitHub configuration:"
+            printf -- '- `%s`\n' "${missing[@]}"
+            echo
+            echo "Pushes to this pull request will skip review app deploys until the repository is configured."
+          } >> "$GITHUB_STEP_SUMMARY"
+          exit 0
+        fi
+
+        printf 'Missing required GitHub configuration:\n- %s\n' "${missing[@]}" >&2
+        exit 1

data/lib/github_flow_templates/.github/actions/cpflow-wait-for-health/action.yml

@@ -0,0 +1,92 @@
+name: Wait for Control Plane workload health
+description: >-
+  Polls the workload's status endpoint with curl and exits success when the
+  HTTP response status is in the accepted list. Fails non-zero (and reports
+  `healthy=false`) once retries are exhausted.
+
+inputs:
+  workload_name:
+    description: Workload to query (e.g. `rails`).
+    required: true
+  app_name:
+    description: GVC / Control Plane app name the workload belongs to.
+    required: true
+  org:
+    description: Control Plane organization.
+    required: true
+  max_retries:
+    description: Number of attempts before giving up.
+    required: false
+    default: "24"
+  interval_seconds:
+    description: Seconds to sleep between attempts.
+    required: false
+    default: "15"
+  accepted_statuses:
+    description: >-
+      Space-separated list of HTTP status codes considered healthy. The default
+      `200 301 302` accepts redirects because curl is invoked without `-L`, so a
+      root path that auth-redirects looks like a redirect, not a failure.
+    required: false
+    default: "200 301 302"
+  curl_max_time:
+    description: Per-request curl timeout, seconds.
+    required: false
+    default: "10"
+
+outputs:
+  healthy:
+    description: '"true" once a healthy response was observed; "false" otherwise.'
+    value: ${{ steps.poll.outputs.healthy }}
+
+runs:
+  using: composite
+  steps:
+    - name: Poll workload endpoint
+      id: poll
+      shell: bash
+      env:
+        CPFLOW_WORKLOAD_NAME: ${{ inputs.workload_name }}
+        CPFLOW_APP_NAME: ${{ inputs.app_name }}
+        CPFLOW_ORG: ${{ inputs.org }}
+        CPFLOW_MAX_RETRIES: ${{ inputs.max_retries }}
+        CPFLOW_INTERVAL_SECONDS: ${{ inputs.interval_seconds }}
+        CPFLOW_ACCEPTED_STATUSES: ${{ inputs.accepted_statuses }}
+        CPFLOW_CURL_MAX_TIME: ${{ inputs.curl_max_time }}
+      run: |
+        set -euo pipefail
+
+        read -r -a accepted_statuses <<< "${CPFLOW_ACCEPTED_STATUSES}"
+
+        for attempt in $(seq 1 "${CPFLOW_MAX_RETRIES}"); do
+          echo "Health check attempt ${attempt}/${CPFLOW_MAX_RETRIES}"
+
+          if ! workload_json="$(cpln workload get "${CPFLOW_WORKLOAD_NAME}" --gvc "${CPFLOW_APP_NAME}" --org "${CPFLOW_ORG}" -o json 2>&1)"; then
+            echo "::error::Workload '${CPFLOW_WORKLOAD_NAME}' not found in GVC '${CPFLOW_APP_NAME}'. Set PRIMARY_WORKLOAD to the correct workload name." >&2
+            printf '%s\n' "${workload_json}" >&2
+            echo "healthy=false" >> "$GITHUB_OUTPUT"
+            exit 1
+          fi
+
+          endpoint="$(echo "${workload_json}" | jq -r '.status.endpoint // empty')"
+          if [[ -n "${endpoint}" ]]; then
+            http_status="$(curl -s -o /dev/null -w '%{http_code}' --max-time "${CPFLOW_CURL_MAX_TIME}" "${endpoint}" 2>/dev/null || echo 000)"
+            echo "Endpoint: ${endpoint}, HTTP status: ${http_status}"
+
+            for accepted in "${accepted_statuses[@]}"; do
+              if [[ "${http_status}" == "${accepted}" ]]; then
+                echo "healthy=true" >> "$GITHUB_OUTPUT"
+                exit 0
+              fi
+            done
+          else
+            echo "Workload '${CPFLOW_WORKLOAD_NAME}' has no endpoint yet; waiting for one to be assigned."
+          fi
+
+          if [[ "${attempt}" -lt "${CPFLOW_MAX_RETRIES}" ]]; then
+            sleep "${CPFLOW_INTERVAL_SECONDS}"
+          fi
+        done
+
+        echo "healthy=false" >> "$GITHUB_OUTPUT"
+        exit 1

data/lib/github_flow_templates/.github/cpflow-help.md

@@ -0,0 +1,47 @@
+# Control Plane GitHub Flow
+
+## PR commands
+
+`/deploy-review-app`
+- 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 `/deploy-review-app` — no surrounding text, trailing whitespace, or trailing newline. The trigger uses an exact-equality match, so a comment like `please /deploy-review-app now` or `/deploy-review-app ` (with a trailing space) silently no-ops.
+
+`/delete-review-app`
+- Deletes the review app when the PR is done
+- This also runs automatically when the PR closes
+- Same exact-match rule as `/deploy-review-app`: the comment body must be exactly `/delete-review-app`.
+
+## Repository secrets
+
+| Name | Required | Notes |
+| --- | --- | --- |
+| `CPLN_TOKEN_STAGING` | yes | Service-account token scoped to the staging org. |
+| `CPLN_TOKEN_PRODUCTION` | yes (for promote) | Service-account token scoped to the production org. |
+| `DOCKER_BUILD_SSH_KEY` | optional | Private SSH key used when Docker builds fetch private deps via `RUN --mount=type=ssh`. |
+
+## Repository variables
+
+| Name | Required | Notes |
+| --- | --- | --- |
+| `CPLN_ORG_STAGING` | yes | Control Plane org for staging and review apps. |
+| `CPLN_ORG_PRODUCTION` | yes (for promote) | Control Plane org 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`). |
+| `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 specific cpflow gem version; falls back to the generated default when unset. |
+
+## Workflow behavior
+
+- Review apps are opt-in and created with `/deploy-review-app`
+- 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

data/lib/github_flow_templates/.github/workflows/cpflow-cleanup-stale-review-apps.yml

@@ -0,0 +1,56 @@
+name: Cleanup Stale Review Apps
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 0 * * *"
+
+permissions:
+  contents: read
+
+concurrency:
+  # Single global group: only one cleanup sweep at a time. Independent of review-app
+  # deploy/delete groups (different keys), so cleanup will not block per-PR work.
+  group: cpflow-cleanup-stale-review-apps
+  # A cancelled `cpflow cleanup-stale-apps` can leave half-deleted review apps; let
+  # the in-flight run finish before the next scheduled tick begins.
+  cancel-in-progress: false
+
+jobs:
+  cleanup:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Validate required secrets and variables
+        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
+
+      - 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: Remove stale review apps
+        env:
+          REVIEW_APP_PREFIX: ${{ vars.REVIEW_APP_PREFIX }}
+          CPLN_ORG_STAGING: ${{ vars.CPLN_ORG_STAGING }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          cpflow cleanup-stale-apps -a "${REVIEW_APP_PREFIX}" --org "${CPLN_ORG_STAGING}" --yes

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

@@ -0,0 +1,142 @@
+name: Delete Review App
+
+on:
+  pull_request_target:
+    types: [closed]
+  issue_comment:
+    types: [created]
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: Pull request number targeted for deletion
+        required: true
+        type: number
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+concurrency:
+  group: cpflow-delete-review-app-${{ github.event.pull_request.number || github.event.issue.number || github.event.inputs.pr_number }}
+  # Deletions must not cancel each other mid-flight — a cancelled `cpln` delete can leave
+  # partial state behind. Let the in-progress deletion finish before the next run starts.
+  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 }}
+
+jobs:
+  delete-review-app:
+    if: |
+      (github.event_name == 'issue_comment' &&
+       github.event.issue.pull_request &&
+       github.event.comment.body == '/delete-review-app' &&
+       contains(fromJson('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)) ||
+      (github.event_name == 'pull_request_target' && github.event.action == 'closed') ||
+      github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      # pull_request_target is intentional: PR-close events from forks need access
+      # to staging secrets so this workflow can delete review apps and update PR
+      # comments. This checkout is safe because it does not set `ref:`; GitHub checks
+      # out the base branch's trusted workflow code, not the fork head. Do not add
+      # `ref: ${{ github.event.pull_request.head.sha }}` here without re-evaluating
+      # the trust boundary. All local composite actions below are therefore loaded from
+      # trusted base-branch code; keep them that way when changing this workflow.
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          # Delete only invokes `cpln`/`cpflow`; no git push happens, so drop the
+          # GITHUB_TOKEN credential helper to keep the token out of .git/config under
+          # `pull_request_target`, which has access to repository secrets.
+          persist-credentials: false
+
+      - name: Validate required secrets and variables
+        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: 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: Set workflow links
+        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}/-info`
+            );
+
+      - name: Create initial PR comment
+        id: create-comment
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const comment = await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: Number(process.env.PR_NUMBER),
+              body: "🗑️ Deleting Control Plane review app..."
+            });
+            core.setOutput("comment-id", comment.data.id);
+
+      - name: Delete review app
+        uses: ./.github/actions/cpflow-delete-control-plane-app
+        with:
+          app_name: ${{ env.APP_NAME }}
+          cpln_org: ${{ vars.CPLN_ORG_STAGING }}
+          review_app_prefix: ${{ vars.REVIEW_APP_PREFIX }}
+
+      - name: Finalize delete status
+        if: always()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const commentId = Number("${{ steps.create-comment.outputs.comment-id }}");
+            const success = "${{ job.status }}" === "success";
+            const body = success
+              ? [
+                  `✅ Review app for PR #${process.env.PR_NUMBER} is deleted`,
+                  "",
+                  `[Open organization console](${process.env.CONSOLE_URL})`,
+                  `[View workflow logs](${process.env.WORKFLOW_URL})`
+                ].join("\n")
+              : [
+                  `❌ Failed to delete review app for PR #${process.env.PR_NUMBER}`,
+                  "",
+                  `[Open organization console](${process.env.CONSOLE_URL})`,
+                  `[View workflow logs](${process.env.WORKFLOW_URL})`
+                ].join("\n");
+
+            if (!Number.isFinite(commentId) || commentId <= 0) {
+              core.warning("Skipping delete status 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
+            });