🤖Intermediate15 minCI/CD

Run vxcli inside GitHub Actions

Authenticate vxcli with a scoped xc_* key, dry-run deploys on pull requests, apply on merge to main, and pull Terraform state for review jobs — all headless.

What you'll build

vxcli authenticating in CI with an environment-scoped key
A dry-run on every PR and a real apply on merge to main
Terraform state pulled into a review job

Before you begin

A pipeline or deployable app already working from the dashboard
Repo admin access to add a GitHub Actions secret
Completed the blue-green CI/CD tutorial (recommended)

Issue a scoped API key

Keys are environment-scoped by prefix, so a leaked CI key can’t touch production unless you let it:

key prefixes

xc_dev_…    DEVELOPMENT
xc_stg_…    STAGING
xc_live_…   PRODUCTION
xc_sbx_…    SANDBOX

Mint one via Settings → Developer keys or the API. Use DEVELOPMENT for PR dry-runs and a separate PRODUCTION key for the apply job.

POST /api/v1/auth/developer/keys

$ { "name": "github-actions-ci", "environment": "DEVELOPMENT" }{ "token": "xc_dev_8f3b…", "is_active": true }

Copy it once

The token is shown once. Store it immediately as a GitHub Actions secret — VXCLOUD_DEV_KEY and VXCLOUD_PROD_KEY. Rotation is deactivate-and-reissue, never in-place reset.

Store the key as an Actions secret

In the repo: Settings → Secrets and variables → Actions → New repository secret.

github.com/acme/orders-api/settings/secrets/actions

VXCLOUD_DEV_KEYUpdated now

VXCLOUD_PROD_KEYEnvironment: production

Two secrets: a dev key for PRs, a prod key gated to the main branch / an environment.

Add the workflow

Dry-run on PRs (no changes applied), real apply only on push to main:

.github/workflows/deploy.yml

name: deploy
on:
  pull_request:
  push: { branches: [main] }

jobs:
  vxcloud:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install vxcli
        run: curl -fsSL https://get.prodxcloud.com/vxcli | sh

      - name: Dry-run (PRs only)
        if: github.event_name == 'pull_request'
        env: { VXCLOUD_TOKEN: ${{ secrets.VXCLOUD_DEV_KEY }} }
        run: vxcli deploy --pipeline orders-api --dry-run

      - name: Apply (main only)
        if: github.ref == 'refs/heads/main'
        env: { VXCLOUD_TOKEN: ${{ secrets.VXCLOUD_PROD_KEY }} }
        run: vxcli deploy --pipeline orders-api

Why dry-run on PRs

--dry-run renders the plan and exits non-zero on drift, so reviewers see exactly what a merge would change — without changing anything.

Pull Terraform state for review

For infra-review jobs, pull the current state so a diff is reviewable in the PR:

vxcli in CI

$ vxcli terraform state pull > state.json

state pulled (workspace: acme/orders, 24 resources)

$ vxcli deploy --pipeline orders-api --dry-run

plan: 0 to add, 1 to change, 0 to destroy

dry-run clean — safe to merge

The same vxcli binary, the same plan engine the dashboard uses — just headless.

CI-driven, environment-safe

PRs preview, main applies, prod keys never leak into PR runs. Pair with the audit-stream tutorial to ship every deploy event to your SIEM.

Nice work — you're done!

You completed Run vxcli inside GitHub Actions. Keep the momentum going with the next walkthrough, or jump back to the full catalog.

Next: Lock down a workspace with SSO & RBAC All tutorials

Set up a CI/CD pipeline with blue-green deploys Lock down a workspace with SSO & RBAC