GitHub Actions CLI

Previewops ships a standalone CLI (src/cli.ts → dist/cli.js) that provides the same deploy, delete, validate, and cleanup commands as the GitHub App — but driven entirely by GitHub Actions and repository secrets. No third-party app installation is required.

When to use the CLI instead of the App

Quick start

1. Allow your repo to call the reusable workflow

The reusable workflow lives at .github/workflows/previewops-deploy.yml in the previewops repository. To call it from your own repo, create .github/workflows/preview.yml:

name: Preview Environments

on:
  issue_comment:
    types: [created]
  pull_request:
    types: [closed]

jobs:
  # Step 1: parse the PR comment to determine the command
  parse-command:
    if: github.event_name == 'issue_comment' && github.event.issue.pull_request != null
    runs-on: ubuntu-latest
    outputs:
      command: ${{ steps.parse.outputs.command }}
      pr_number: ${{ steps.parse.outputs.pr_number }}
    steps:
      - id: parse
        run: |
          BODY="${{ github.event.comment.body }}"
          if echo "$BODY" | grep -qE '^/deploy-previewops'; then
            echo "command=deploy" >> $GITHUB_OUTPUT
          elif echo "$BODY" | grep -qE '^/delete-previewops'; then
            echo "command=delete" >> $GITHUB_OUTPUT
          elif echo "$BODY" | grep -qE '^/validate-previewops'; then
            echo "command=validate" >> $GITHUB_OUTPUT
          elif echo "$BODY" | grep -qE '^/perf-previewops'; then
            echo "command=perf" >> $GITHUB_OUTPUT
          fi
          echo "pr_number=${{ github.event.issue.number }}" >> $GITHUB_OUTPUT

  # Step 2: call the reusable workflow
  deploy:
    needs: parse-command
    if: needs.parse-command.outputs.command != '' && github.event_name == 'issue_comment'
    uses: YOUR_ORG/previewops/.github/workflows/previewops-deploy.yml@main
    with:
      command: ${{ needs.parse-command.outputs.command }}
      pr_number: ${{ fromJson(needs.parse-command.outputs.pr_number) }}
      owner: ${{ github.repository_owner }}
      repo: ${{ github.event.repository.name }}
      provider: cloud-run
      provider_config: '{}'   # non-secret providerConfig fields
    secrets:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      GCP_PROJECT_ID: ${{ secrets.GCP_PROJECT_ID }}

  # Step 3: delete preview when PR is closed
  cleanup-on-close:
    if: github.event_name == 'pull_request' && github.event.action == 'closed'
    uses: YOUR_ORG/previewops/.github/workflows/previewops-deploy.yml@main
    with:
      command: delete
      pr_number: ${{ github.event.pull_request.number }}
      owner: ${{ github.repository_owner }}
      repo: ${{ github.event.repository.name }}
      provider: cloud-run
      provider_config: '{}'
    secrets:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      GCP_PROJECT_ID: ${{ secrets.GCP_PROJECT_ID }}

2. Add scheduled TTL cleanup

Create a separate .github/workflows/preview-cleanup.yml:

name: Preview Cleanup

on:
  schedule:
    - cron: '0 * * * *'   # every hour
  workflow_dispatch:        # allow manual runs

jobs:
  cleanup:
    uses: YOUR_ORG/previewops/.github/workflows/previewops-deploy.yml@main
    with:
      command: cleanup
      owner: ${{ github.repository_owner }}
      repo: ${{ github.event.repository.name }}
      provider: cloud-run
      provider_config: '{}'
    secrets:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      GCP_PROJECT_ID: ${{ secrets.GCP_PROJECT_ID }}

Reusable workflow inputs

Required for all commands

Required for deploy

Secrets

Secrets are forwarded to the CLI as environment variables. Pass exactly the secrets your provider needs:

CLI commands

After building (npm run build), the CLI is at dist/cli.js.

deploy

Builds and deploys a preview environment for a PR.

PREVIEW_OWNER=acme \
PREVIEW_REPO=website \
PREVIEW_PR_NUMBER=42 \
PREVIEW_SHA=abc123def456 \
PREVIEW_BRANCH=feat/my-feature \
PREVIEW_CLONE_URL=https://github.com/acme/website \
PREVIEW_PROVIDER=cloud-run \
GCP_PROJECT_ID=my-project-123 \
GITHUB_TOKEN=ghp_... \
node dist/cli.js deploy

On success, prints the preview URL and TTL to stdout and updates the PR comment.

delete

Tears down all preview services for a PR.

PREVIEW_OWNER=acme \
PREVIEW_REPO=website \
PREVIEW_PR_NUMBER=42 \
PREVIEW_PROVIDER=cloud-run \
GCP_PROJECT_ID=my-project-123 \
GITHUB_TOKEN=ghp_... \
node dist/cli.js delete

validate

Checks that credentials and providerConfig are valid without deploying anything.

PREVIEW_OWNER=acme \
PREVIEW_REPO=website \
PREVIEW_PR_NUMBER=42 \
PREVIEW_PROVIDER=fly \
FLY_API_TOKEN=fo1_... \
PREVIEW_PROVIDER_CONFIG='{"orgSlug":"my-org"}' \
GITHUB_TOKEN=ghp_... \
node dist/cli.js validate

Posts a pass/fail comment on the PR. Exits with code 1 if validation fails.

cleanup

Scans all active previews for PREVIEW_PROVIDER and deletes any that have exceeded their TTL.

PREVIEW_PROVIDER=cloud-run \
GCP_PROJECT_ID=my-project-123 \
node dist/cli.js cleanup

Exits with code 1 if any deletions failed.

perf

Runs a k6 load test against an active preview URL and posts results to the PR.

PREVIEW_OWNER=acme \
PREVIEW_REPO=website \
PREVIEW_PR_NUMBER=42 \
PREVIEW_PROVIDER=cloud-run \
GCP_PROJECT_ID=my-project-123 \
GITHUB_TOKEN=ghp_... \
node dist/cli.js perf

Optional flags (set as env vars):

Posts a results comment with latency percentiles, throughput, error rate, and SLO evaluation. On paid plans, AI-generated insights and baseline comparison are included.

All CLI environment variables

AWS ECS example

uses: YOUR_ORG/previewops/.github/workflows/previewops-deploy.yml@main
with:
  command: ${{ needs.parse-command.outputs.command }}
  pr_number: ${{ fromJson(needs.parse-command.outputs.pr_number) }}
  owner: ${{ github.repository_owner }}
  repo: ${{ github.event.repository.name }}
  provider: aws-ecs
  provider_config: >-
    {
      "cluster": "my-preview-cluster",
      "vpc": "vpc-0abc123",
      "subnets": ["subnet-0abc123", "subnet-0def456"],
      "securityGroups": ["sg-0abc123"],
      "albListenerArn": "arn:aws:elasticloadbalancing:us-east-1:...",
      "executionRoleArn": "arn:aws:iam::123456789012:role/ecsTaskExecutionRole",
      "baseDomain": "previews.example.com"
    }
secrets:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
  AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

Differences from the GitHub App