CI/CD Quickstart

Run your first CI audit in under 5 minutes. By the end of this guide, you'll have automated UX audits running on every pull request.

Prerequisites

Before starting, you need:

• A CI/CD platform (GitHub Actions, GitLab CI, etc.)
• A preview deployment URL (or production URL for testing)
• A VertaaUX API key

Step 1: Add Your API Key Secret

Add VERTAAUX_API_KEY as a secret in your CI platform:

Step 2: Create the Workflow File

Create a workflow file in your repository:

name: UX Audit

on:
  pull_request:
    branches: [main]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: Install VertaaUX CLI
        run: npm install -g @vertaaux/cli

      - name: Run UX Audit
        run: vertaa audit -u ${{ vars.PREVIEW_URL }} --fail-on error
        env:
          VERTAAUX_API_KEY: ${{ secrets.VERTAAUX_API_KEY }}

ux-audit:
  stage: test
  image: node:22
  script:
    - npm install -g @vertaaux/cli
    - vertaa audit -u $CI_ENVIRONMENT_URL --fail-on error
  only:
    - merge_requests

Step 3: Push and See Results

1. Commit and push your workflow file
2. Open a pull request (or trigger your CI)
3. Watch the CI output for audit results

Success Output

When the audit passes:

VertaaUX Audit Results
======================
URL: https://preview-abc123.vercel.app
Score: 87/100
Issues: 0 errors, 3 warnings, 5 info

Status: PASSED

Failure Output

When the audit finds errors:

VertaaUX Audit Results
======================
URL: https://preview-abc123.vercel.app
Score: 65/100
Issues: 2 errors, 8 warnings, 12 info

ERRORS:
  1. [WCAG-1.1.1] Image missing alt text
     Element: <img src="/hero.png">
     Fix: Add descriptive alt attribute

  2. [WCAG-2.4.4] Link has no accessible name
     Element: <a href="/docs"><svg>...</svg></a>
     Fix: Add aria-label or visible text

Status: FAILED (--fail-on error triggered)
Exit code: 1

What You'll See

After setup, every pull request will show:

1. CI check status - Pass/fail based on audit results
2. Audit summary - Score and issue counts in logs
3. Exit code - Determines CI pass/fail

Troubleshooting

"Unauthorized" Error

Your API key is missing or invalid:

Error: Unauthorized. Check your VERTAAUX_API_KEY.

Fix: Verify the secret is set correctly and the key is valid.

"Preview not ready" / Timeout

The preview URL isn't accessible when the audit runs:

Error: Failed to fetch https://preview-abc123.vercel.app (timeout)

Fix: Add a deployment status trigger (see GitHub Actions with Vercel) or wait for deployment:

- name: Wait for preview
  run: |
    for i in {1..30}; do
      curl -s -o /dev/null -w "%{http_code}" $PREVIEW_URL | grep -q "200" && exit 0
      sleep 10
    done
    exit 1

Score Below Expected

Audit runs but score is lower than expected:

Fix: Start with lenient thresholds and tighten over time:

# Start lenient
- run: vertaa audit -u $URL --threshold 60 --fail-on error

# Then tighten
- run: vertaa audit -u $URL --threshold 80 --fail-on error

Next Steps

Now that you have basic CI integration working: