vertaa policy

Manage policy-as-code configuration for automated UX quality gates.

Synopsis

vertaa policy <subcommand> [options]

Description

The policy command manages vertaa.policy.yml files that define quality gates for your project. Policies let you:

Set different thresholds for different branches (stricter on main, lenient on feature branches)
Override rule severities (treat brand color contrast as warning instead of error)
Configure bypass labels for emergency deployments
Exclude paths from audit (legacy code, third-party pages)

Subcommands

Subcommand	Description
`init`	Create a starter policy file
`validate`	Check policy file syntax and semantics
`show`	Display effective policy (with all defaults)
`schema`	Output JSON schema for editor autocompletion

Quick Examples

Create starter vertaa.policy.yml

$vertaa policy init

Check policy file for errors

$vertaa policy validate

Display effective policy

$vertaa policy show

Subcommand Reference

vertaa policy init

Create a starter policy file in the current directory:

$vertaa policy init

Options:

init Options

Parameter	Type	Required	Description
-o, --output	`string`	optional	Output file pathDefault: `vertaa.policy.yml`
--preset	`string`	optional	Preset template: minimal, standard, strict, enterpriseDefault: `standard`
--force	`boolean`	optional	Overwrite existing policy fileDefault: `false`

Preset Templates:

Preset	Description
`minimal`	Basic fail-on-error only
`standard`	Balanced with branch rules
`strict`	Zero tolerance for new issues
`enterprise`	Full configuration with all options

vertaa policy validate

Check your policy file for syntax errors and semantic issues:

$vertaa policy validate

Validate specific file

$vertaa policy validate --file custom-policy.yml

Options:

validate Options

Parameter	Type	Required	Description
-f, --file	`string`	optional	Policy file to validateDefault: `vertaa.policy.yml`
--strict	`boolean`	optional	Fail on warnings (not just errors)Default: `false`

Validation checks:

YAML syntax validity
Schema compliance
Rule ID existence
Severity value validity
Branch pattern regex validity
No conflicting rules

vertaa policy show

Display the effective policy with all defaults filled in:

$vertaa policy show

Show policy for specific branch

$vertaa policy show --branch feature/new-ui

Options:

show Options

Parameter	Type	Required	Description
-f, --file	`string`	optional	Policy file to showDefault: `vertaa.policy.yml`
--branch	`string`	optional	Show policy as applied to specific branch
--format	`string`	optional	Output format: yaml, jsonDefault: `yaml`

vertaa policy schema

Output the JSON schema for IDE autocompletion:

$vertaa policy schema

Save schema to file

$vertaa policy schema > .vertaa-policy-schema.json

Add to your policy file for editor support:

$schema: "./.vertaa-policy-schema.json"
# or use the hosted version:
$schema: "https://vertaaux.ai/schemas/policy.json"

Policy File Format

Complete Example

# vertaa.policy.yml
$schema: https://vertaaux.ai/schemas/policy.json
version: 1

# Policy metadata
name: "My Project Policy"
description: "UX quality gates for the main application"

# Default assertions (apply to all branches unless overridden)
assertions:
  fail_on: error              # Fail on: error, warning, info, none
  overall_score: 75           # Minimum acceptable score (0-100)
  max_new_errors: 0           # Maximum new errors allowed
  max_new_warnings: 5         # Maximum new warnings allowed

# Branch-specific rules
branches:
  main:
    pattern: "^(main|master)$"
    assertions:
      fail_on: error
      overall_score: 80
      max_new_errors: 0
      max_new_warnings: 0     # Stricter on main

  release:
    pattern: "^release/.*$"
    assertions:
      fail_on: error
      overall_score: 85       # Even stricter for releases
      max_new_errors: 0
      max_new_warnings: 0

  feature:
    pattern: "^feature/.*$"
    assertions:
      fail_on: error
      overall_score: 70       # More lenient for WIP
      max_new_warnings: 10

  hotfix:
    pattern: "^hotfix/.*$"
    assertions:
      fail_on: error          # Still catch errors
      max_new_errors: 0
      # No score requirement for hotfixes

# Labels that bypass audit (emergency deployments)
bypass_labels:
  - "skip-audit"
  - "emergency"
  - "hotfix-bypass"

# Per-rule severity overrides
rules:
  color-contrast:
    severity: warning         # Override from error to warning
    reason: "Brand colors approved by accessibility team"

  touch-target-size:
    severity: info            # Informational only
    reason: "Design system handles this"

  skip-link:
    enabled: false            # Disable rule entirely
    reason: "Not applicable for single-page app"

# Paths to exclude from audits
exclude_paths:
  - "/legacy/**"              # Legacy code exempt
  - "/admin/**"               # Admin area separate audit
  - "/third-party/**"         # Third-party embeds
  - "**/*.storybook.*"        # Storybook frames

# Category-level configurations
categories:
  accessibility:
    weight: 1.5               # Weighted more heavily in score
  performance:
    weight: 0.8               # Weighted less heavily

Required Fields

Only version is strictly required:

version: 1

All other fields have sensible defaults.

Field Reference

Top-level Fields

Field	Type	Default	Description
`$schema`	string	-	JSON schema URL for editor support
`version`	number	1	Policy format version
`name`	string	-	Human-readable policy name
`description`	string	-	Policy description

assertions

Field	Type	Default	Description
`fail_on`	string	"error"	Minimum severity to fail: error, warning, info, none
`overall_score`	number	0	Minimum acceptable overall score (0-100)
`max_new_errors`	number	-1	Max new errors (-1 = unlimited)
`max_new_warnings`	number	-1	Max new warnings (-1 = unlimited)

branches

Each branch entry:

Field	Type	Required	Description
`pattern`	string	Yes	Regex pattern to match branch names
`assertions`	object	Yes	Assertions for matching branches

rules

Each rule entry:

Field	Type	Default	Description
`severity`	string	(rule default)	Override: error, warning, info
`enabled`	boolean	true	Enable/disable the rule
`reason`	string	-	Documentation for the override

Using Policies in Audits

Automatic Discovery

The CLI automatically finds vertaa.policy.yml in the current directory or any parent:

$vertaa audit -u https://example.com

Explicit Policy File

Specify a custom policy file:

$vertaa audit -u https://example.com --policy ./policies/strict.yml

CI/CD Integration

In CI, the policy applies based on the current branch:

# GitHub Actions
- name: UX Audit
  run: vertaa audit -u ${{ env.PREVIEW_URL }}
  env:
    VERTAA_API_KEY: ${{ secrets.VERTAA_API_KEY }}
    # Branch is auto-detected from GITHUB_REF

Branch Detection

The CLI automatically detects the current branch from:

GITHUB_REF (GitHub Actions)
CI_COMMIT_BRANCH (GitLab CI)
CIRCLE_BRANCH (CircleCI)
git rev-parse --abbrev-ref HEAD (local)

Workflow Examples

Setting Up Policies

Initialize a policy file:

$vertaa policy init --preset standard

Customize for your project (edit vertaa.policy.yml)
Validate the policy:

$vertaa policy validate

Commit to version control:

git add vertaa.policy.yml
git commit -m "Add UX audit policy"

Testing Policy Changes

Preview how a policy change affects a branch:

See effective policy for branch

$vertaa policy show --branch feature/new-ui

Gradual Strictness Increase

Start lenient, increase strictness over time:

# Week 1: Catch only errors
assertions:
  fail_on: error
  overall_score: 50

# Week 4: Increase score requirement
assertions:
  fail_on: error
  overall_score: 65

# Week 8: Start catching warnings too
assertions:
  fail_on: warning
  overall_score: 75

Exit Codes

Subcommand	Code	Meaning
`init`	0	Policy file created
`init`	1	File already exists (without --force)
`validate`	0	Policy is valid
`validate`	1	Validation errors found
`show`	0	Policy displayed
`show`	1	Policy file not found
`schema`	0	Schema output successfully

Also available

Policy configuration is CLI-only. The API and SDK use explicit parameters for quality gates.

audit

Use policies in audits

CI/CD Integration

Policies in CI/CD pipelines

baseline

Combine policies with baselines

Configuration

.vertaaux.yml configuration file

Was this page helpful?

policy

audit

CI/CD Integration

baseline

Configuration

On this page