Skip to main content
VertaaUX Docs

Other CI Platforms

VertaaUX integration for GitLab CI, CircleCI, Jenkins, and Azure DevOps

Other CI Platforms

VertaaUX integrates with any CI platform that can run Node.js. This guide covers GitLab CI, CircleCI, Jenkins, Azure DevOps, and generic patterns.

GitLab CI

Basic Integration

.gitlab-ci.yml
stages:
  - test

ux-audit:
  stage: test
  image: node:20
  script:
    - npm install -g @vertaaux/cli
    - vertaa audit -u $CI_ENVIRONMENT_URL --fail-on error --threshold 80
  variables:
    VERTAA_API_KEY: $VERTAA_API_KEY
  only:
    - merge_requests
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_COMMIT_REF_SLUG.preview.example.com

Set VERTAA_API_KEY: Go to Settings > CI/CD > Variables. Add VERTAA_API_KEY and check "Mask variable".

With Artifacts

Save audit results as downloadable artifacts:

.gitlab-ci.yml
ux-audit:
  stage: test
  image: node:20
  script:
    - npm install -g @vertaaux/cli
    - vertaa audit -u $CI_ENVIRONMENT_URL --format json -o results.json
    - vertaa audit -u $CI_ENVIRONMENT_URL --format html -o report.html
  artifacts:
    paths:
      - results.json
      - report.html
    reports:
      junit: results.json
    expire_in: 1 week
  variables:
    VERTAA_API_KEY: $VERTAA_API_KEY

Merge Request Pipeline

Trigger only on merge requests with review environments:

.gitlab-ci.yml
stages:
  - deploy
  - test

deploy_review:
  stage: deploy
  script:
    - deploy-to-review-environment.sh
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_COMMIT_REF_SLUG.review.example.com
    on_stop: stop_review
  only:
    - merge_requests

ux-audit:
  stage: test
  image: node:20
  needs: [deploy_review]
  script:
    - npm install -g @vertaaux/cli
    - |
      vertaa audit \
        -u "https://$CI_COMMIT_REF_SLUG.review.example.com" \
        --baseline baseline.json \
        --max-new-errors 0 \
        --fail-on error
  variables:
    VERTAA_API_KEY: $VERTAA_API_KEY
  only:
    - merge_requests

stop_review:
  stage: deploy
  script:
    - stop-review-environment.sh
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop
  when: manual
  only:
    - merge_requests

Merge Request Comments

Post results as merge request comments:

.gitlab-ci.yml
ux-audit:
  stage: test
  image: node:20
  script:
    - npm install -g @vertaaux/cli
    - vertaa audit -u $CI_ENVIRONMENT_URL --format json -o results.json
    - vertaa comment --file results.json --format gitlab > comment.md
    - |
      curl --request POST \
        --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
        --data-urlencode "body@comment.md" \
        "$CI_API_V4_URL/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes"
  variables:
    VERTAA_API_KEY: $VERTAA_API_KEY
    GITLAB_TOKEN: $GITLAB_TOKEN
  only:
    - merge_requests

CircleCI

Basic Integration

.circleci/config.yml
version: 2.1

jobs:
  ux-audit:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - run:
          name: Install VertaaUX CLI
          command: npm install -g @vertaaux/cli
      - run:
          name: Run UX Audit
          command: |
            vertaa audit \
              -u $PREVIEW_URL \
              --fail-on error \
              --threshold 80
      - store_artifacts:
          path: results.json

workflows:
  ux-quality:
    jobs:
      - ux-audit:
          filters:
            branches:
              only:
                - main
                - /feature\/.*/

With Context for Secrets

Use CircleCI contexts for secure API key management:

.circleci/config.yml
version: 2.1

jobs:
  ux-audit:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - run:
          name: Install VertaaUX CLI
          command: npm install -g @vertaaux/cli
      - run:
          name: Run UX Audit
          command: |
            vertaa audit \
              -u $PREVIEW_URL \
              --baseline baseline.json \
              --max-new-errors 0 \
              --fail-on error \
              --format json \
              -o results.json
      - store_artifacts:
          path: results.json

workflows:
  ux-quality:
    jobs:
      - ux-audit:
          context:
            - vertaaux-credentials

Create context: Go to Organization Settings > Contexts > Create Context. Add VERTAA_API_KEY and PREVIEW_URL environment variables.

Multi-Page Audit

Audit multiple pages in parallel:

.circleci/config.yml
version: 2.1

jobs:
  audit-page:
    parameters:
      page:
        type: string
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - run:
          name: Install VertaaUX CLI
          command: npm install -g @vertaaux/cli
      - run:
          name: Audit << parameters.page >>
          command: vertaa audit -u "$PREVIEW_URL/<< parameters.page >>" --fail-on error

workflows:
  ux-quality:
    jobs:
      - audit-page:
          matrix:
            parameters:
              page: ["", "pricing", "docs", "dashboard"]
          context:
            - vertaaux-credentials

Jenkins

Declarative Pipeline

Jenkinsfile
pipeline {
    agent any

    environment {
        VERTAA_API_KEY = credentials('vertaaux-api-key')
    }

    stages {
        stage('Install') {
            steps {
                sh 'npm install -g @vertaaux/cli'
            }
        }

        stage('UX Audit') {
            steps {
                sh '''
                    vertaa audit \
                        -u ${PREVIEW_URL} \
                        --fail-on error \
                        --threshold 80 \
                        --format json \
                        -o results.json
                '''
            }
            post {
                always {
                    archiveArtifacts artifacts: 'results.json'
                }
            }
        }
    }
}

Add credentials: Go to Jenkins > Manage Jenkins > Credentials. Add a "Secret text" credential with ID vertaaux-api-key.

Scripted Pipeline

For more control, use a scripted pipeline:

Jenkinsfile
node {
    def vertaaApiKey = credentials('vertaaux-api-key')

    stage('Checkout') {
        checkout scm
    }

    stage('Install CLI') {
        sh 'npm install -g @vertaaux/cli'
    }

    stage('UX Audit') {
        withEnv(["VERTAA_API_KEY=${vertaaApiKey}"]) {
            try {
                sh '''
                    vertaa audit \
                        -u ${PREVIEW_URL} \
                        --baseline baseline.json \
                        --max-new-errors 0 \
                        --fail-on error \
                        --format json \
                        -o results.json
                '''
            } catch (e) {
                currentBuild.result = 'UNSTABLE'
            } finally {
                archiveArtifacts artifacts: 'results.json', allowEmptyArchive: true
            }
        }
    }

    stage('Update Baseline') {
        if (env.BRANCH_NAME == 'main') {
            withEnv(["VERTAA_API_KEY=${vertaaApiKey}"]) {
                sh 'vertaa baseline -u ${PRODUCTION_URL} --update baseline.json'
                sh '''
                    git config user.email "jenkins@example.com"
                    git config user.name "Jenkins"
                    git add baseline.json
                    git diff --staged --quiet || git commit -m "chore: update UX baseline"
                    git push origin main
                '''
            }
        }
    }
}

With Docker Agent

Use Docker for consistent Node.js version:

Jenkinsfile
pipeline {
    agent {
        docker {
            image 'node:20'
        }
    }

    environment {
        VERTAA_API_KEY = credentials('vertaaux-api-key')
    }

    stages {
        stage('UX Audit') {
            steps {
                sh 'npm install -g @vertaaux/cli'
                sh 'vertaa audit -u ${PREVIEW_URL} --fail-on error'
            }
        }
    }
}

Azure DevOps

Basic Pipeline

azure-pipelines.yml
trigger:
  branches:
    include:
      - main

pr:
  branches:
    include:
      - main

pool:
  vmImage: 'ubuntu-latest'

steps:
  - task: NodeTool@0
    inputs:
      versionSpec: '20.x'

  - script: npm install -g @vertaaux/cli
    displayName: 'Install VertaaUX CLI'

  - script: |
      vertaa audit \
        -u $(PREVIEW_URL) \
        --fail-on error \
        --threshold 80 \
        --format junit \
        -o results.xml
    displayName: 'Run UX Audit'
    env:
      VERTAA_API_KEY: $(VERTAA_API_KEY)

  - task: PublishTestResults@2
    inputs:
      testResultsFormat: 'JUnit'
      testResultsFiles: 'results.xml'
    condition: always()

Add variables: Go to Pipelines > Library > Variable groups. Create a group with VERTAA_API_KEY and PREVIEW_URL. Mark VERTAA_API_KEY as secret.

With Variable Groups

Use variable groups for environment-specific configuration:

azure-pipelines.yml
trigger:
  - main

variables:
  - group: vertaaux-production
  - name: isMain
    value: $[eq(variables['Build.SourceBranch'], 'refs/heads/main')]

stages:
  - stage: Audit
    jobs:
      - job: UXAudit
        pool:
          vmImage: 'ubuntu-latest'
        steps:
          - task: NodeTool@0
            inputs:
              versionSpec: '20.x'

          - script: npm install -g @vertaaux/cli
            displayName: 'Install CLI'

          - script: |
              vertaa audit \
                -u $(PREVIEW_URL) \
                --baseline baseline.json \
                --max-new-errors 0 \
                --fail-on error
            displayName: 'Audit Preview'
            env:
              VERTAA_API_KEY: $(VERTAA_API_KEY)

  - stage: UpdateBaseline
    condition: and(succeeded(), eq(variables.isMain, 'true'))
    jobs:
      - job: Update
        pool:
          vmImage: 'ubuntu-latest'
        steps:
          - checkout: self
            persistCredentials: true

          - task: NodeTool@0
            inputs:
              versionSpec: '20.x'

          - script: npm install -g @vertaaux/cli
            displayName: 'Install CLI'

          - script: vertaa baseline -u $(PRODUCTION_URL) --update baseline.json
            displayName: 'Update Baseline'
            env:
              VERTAA_API_KEY: $(VERTAA_API_KEY)

          - script: |
              git config user.email "azure@example.com"
              git config user.name "Azure Pipelines"
              git add baseline.json
              git diff --staged --quiet || git commit -m "chore: update UX baseline"
              git push
            displayName: 'Commit Baseline'

Generic CI Pattern

For any CI platform that supports Node.js, the pattern is:

# 1. Install the CLI
npm install -g @vertaaux/cli

# 2. Set environment variable
export VERTAA_API_KEY="vx_live_your_key"

# 3. Run audit
vertaa audit -u $PREVIEW_URL --fail-on error --threshold 80

# 4. Check exit code (0 = pass, 1 = issues, 2 = error, 3 = threshold)

Docker-based CI

If your CI uses Docker:

FROM node:20-alpine

RUN npm install -g @vertaaux/cli

ENTRYPOINT ["vertaa"]

Then run:

docker run -e VERTAA_API_KEY=$VERTAA_API_KEY vertaaux-cli audit -u $URL --fail-on error

Environment Variables Reference

All platforms use the same environment variables:

VariableRequiredDescription
VERTAA_API_KEYYesYour API key
PREVIEW_URLVariesURL to audit
PRODUCTION_URLNoURL for baseline updates

GitHub Actions

Detailed GitHub Actions workflows

Policy-as-Code

Branch-specific quality rules with vertaa.policy.yml

CLI Commands

All CLI command options

Was this page helpful?

GitHub Actions

Comprehensive GitHub Actions workflows for VertaaUX CI/CD integration

Policy-as-Code

Configure branch-specific quality gates with vertaa.policy.yml

On this page

Other CI PlatformsGitLab CIBasic IntegrationWith ArtifactsMerge Request PipelineMerge Request CommentsCircleCIBasic IntegrationWith Context for SecretsMulti-Page AuditJenkinsDeclarative PipelineScripted PipelineWith Docker AgentAzure DevOpsBasic PipelineWith Variable GroupsGeneric CI PatternDocker-based CIEnvironment Variables ReferenceRelated