CloudBoosterDocs
CLI

Run `cbx audit` in GitHub Actions

Run cbx audit aws inside a GitHub Actions workflow and gate merges on its exit code.

Run cbx audit in GitHub Actions

This recipe shows you how to run cbx audit aws inside a GitHub Actions workflow so that a non-zero exit code blocks the pull request from merging.

Live-account audits are usually a workstation task

cbx audit aws reads a live AWS account and grounds its findings by running a local LLM CLI (claude or codex). To run it in CI the runner needs AWS credentials, outbound reachability to api.cloudbooster.io, and the chosen LLM CLI installed and authenticated. Many teams run live-account audits from a developer workstation instead. If that's you, skip this page — the example below is for teams that have deliberately set up CI to carry those prerequisites.

Before you begin

  • cbx-cli installed in the runner. The workflow below installs it via the official install script.
  • AWS credentials available to the workflow (e.g. via aws-actions/configure-aws-credentials with OIDC).
  • The grounding LLM CLI (claude or codex) installed on the runner and authenticated via a secret. The CLI owns its own auth.
  • Network reachability from the runner to api.cloudbooster.io.

The workflow

Create .github/workflows/cbx-audit.yml in your repository and paste the contents below. A copy of the same file is also committed in this docs repo as cbx-audit.yml so you can download it directly.

# .github/workflows/cbx-audit.yml
# Run cbx audit aws on every pull request.
# A non-zero exit code from the audit step blocks the PR from merging.
 
name: cbx audit
 
on:
  pull_request:
    branches: [main]
 
permissions:
  id-token: write   # for AWS OIDC
  contents: read
 
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
 
      - name: Install cbx-cli
        run: |
          curl -fsSL https://install.cloudbooster.io | sh
          echo "$HOME/.cbx/bin" >> "$GITHUB_PATH"
 
      # cbx audit aws grounds findings via a local LLM CLI.
      # Install and authenticate claude (or codex) here; the CLI owns its own auth.
      # e.g. install the Claude Code CLI and provide its credentials via a repo secret.
 
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_AUDIT_ROLE_ARN }}
          aws-region: us-east-1
 
      - name: Run cbx audit aws
        run: cbx audit aws --region us-east-1 --no-tui --strict -o json
        # Exit-code gating:
        #   - exit 0  → no findings at/above the strict threshold; PR can merge
        #   - non-0   → findings detected; PR is blocked
        # continue-on-error is NOT set, so GitHub automatically prevents merging.

Key points

FeatureHow it works
Triggerpull_request on main audits before merge.
InstallThe official install script downloads the latest stable cbx-cli binary. Pin a version with CBX_VERSION if you need reproducible builds.
Grounding CLIcbx audit aws always grounds via a local LLM CLI (claude or codex). It must be on the runner's PATH and authenticated — the binary install alone is not enough.
--no-tuiDisables the interactive TUI (also implied in a non-TTY runner).
--strictTreats warnings as failures so they affect the exit code and the merge gate.
-o jsonEmits a machine-readable envelope you can archive as a workflow artifact.
Exit-code gatingThe step does not set continue-on-error: true. A non-zero exit fails the job and blocks merge (with branch protection requiring the check).

How PR gating works

GitHub Actions uses the job's exit code to decide whether a required status check passed. By default, any step that returns a non-zero exit code fails the whole job.

To enforce this as a merge gate:

  1. Open your repository's Settings → Branches.
  2. Add or edit a branch protection rule for main.
  3. Enable Require status checks to pass before merging.
  4. Search for and select the cbx audit check.

Now, when cbx audit aws reports findings at or above your threshold, the check fails and the PR cannot be merged until the issues are resolved or an administrator bypasses the protection.

Non-blocking mode

To see findings without blocking merges during an evaluation period, add continue-on-error: true to the audit step. The findings still surface in the logs, but the job reports success.

What if?

Audit step fails with "command not found"

If cbx isn't found, the install step didn't add it to PATH. Confirm the echo "$HOME/.cbx/bin" >> "$GITHUB_PATH" line ran, then cbx version.

Run aborts with E_LLM_PREFLIGHT

The grounding LLM CLI isn't installed or authenticated on the runner. cbx audit aws probes it before any AWS call. Install claude (or codex), supply its credentials via a repo secret, and re-run.

Can I run this on a schedule instead of per-PR?

Yes. Replace the on: trigger with a schedule event to audit nightly or weekly. Archive the -o json output as a workflow artifact for later review.

Next steps

Previous

Use `cbx audit`

Next

MCP

On this page