.pixmoat.yaml reference
This page lists every key .pixmoat.yaml accepts. It is generated from the file’s JSON Schema, whose ID is https://pixmoat.com/schemas/pixmoat-config.schema.json. For how the file is read and applied, with examples, see Project configuration.
Each key has one of these scopes:
| Scope | Meaning |
|---|---|
| File | Describes the file itself. |
| Build-scoped | Read from the commit being tested and applied to that build only. A key you leave out keeps the project’s current setting. |
| Project-global | Applied to the project as a whole, and only from the default branch. |
| Client-only | Read by the Playwright capture client. The server ignores it. |
A Default of — means the key has no fixed default. For a build-scoped key, leaving it out keeps the project setting.
version
| Key | Type | Default | Scope | Description |
|---|---|---|---|---|
version | 1 | — | File | Schema version. Must be 1. Required. |
accessibility
| Key | Type | Default | Scope | Description |
|---|---|---|---|---|
accessibility | object | — | Build-scoped | Accessibility audit settings. |
accessibility.enabled | boolean | — | Build-scoped | Run accessibility audits. |
accessibility.gating | advisory or blocking | — | Build-scoped | Whether new violations only show in review (advisory) or block finishing it (blocking). Setting it in the file has no effect yet: pixmoat enforces the value from the project’s Settings. |
accessibility.preset | contrast_only, wcag_aa or wcag_aaa | — | Build-scoped | Which rule set to audit against. |
accessibility.regression_detection | boolean | — | Build-scoped | Compare violations with the baseline to find new and resolved ones. |
accessibility.rules | object | — | Build-scoped | Rule customisation. |
accessibility.rules.exclude | list of string | [] | Build-scoped | axe rule IDs to skip, for example region. |
accessibility.thresholds | object | — | Build-scoped | Violation thresholds. |
accessibility.thresholds.fail_on_new | boolean | — | Build-scoped | Require a review decision when any new violation appears. |
accessibility.thresholds.max_serious | integer, at least 0 | — | Build-scoped | Most serious or critical violations allowed before the result is violations (null = no limit). |
accessibility.thresholds.max_violations | integer, at least 0 | — | Build-scoped | Most violations allowed in total before the result is violations (null = no limit). |
agent_auto_approve
| Key | Type | Default | Scope | Description |
|---|---|---|---|---|
agent_auto_approve | none, intent_only or all | — | Project-global | Which changes an AI agent may approve. none: Agents can’t approve changes. intent_only: Agents can approve changes that match a declared intent. all: Agents can approve any change. |
blocking_mode
| Key | Type | Default | Scope | Description |
|---|---|---|---|---|
blocking_mode | blocking or report_only | — | Build-scoped | Whether builds with visual changes block the pipeline (blocking) or only report them (report_only). Setting it in the file has no effect yet: pixmoat enforces the value from the project’s Settings. |
browsers
| Key | Type | Default | Scope | Description |
|---|---|---|---|---|
browsers | list of chromium, firefox or webkit | — | Build-scoped | Browsers the build is expected to capture. |
capture
| Key | Type | Default | Scope | Description |
|---|---|---|---|---|
capture | object | — | Client-only | Screenshot stabilisation settings. Client-only: the Playwright capture client reads this section and the server ignores it. |
capture.animations | end, pause or allow | end | Client-only | How CSS and Web Animations are handled before capture. end: Freeze animations and jump them to their final frame. pause: Freeze animations at their current frame. allow: Leave animations running. |
capture.image_timeout_ms | integer, at least 0 | 3000 | Client-only | Longest time to wait for images, in milliseconds. |
capture.wait_for_fonts | boolean | true | Client-only | Wait for web fonts to finish loading. |
capture.wait_for_images | boolean | true | Client-only | Wait for images to finish decoding. |
console
| Key | Type | Default | Scope | Description |
|---|---|---|---|---|
console | object | — | Build-scoped | Console capture settings. |
console.allow_known | boolean | — | Build-scoped | Don’t raise violations for findings already in the baseline. |
console.capture_levels | list of string | — | Build-scoped | Console levels to keep, for example error and warning. Page errors and failed requests are always kept. |
console.enabled | boolean | — | Build-scoped | Record browser console messages, uncaught page errors and failed requests during each snapshot. |
console.fail_on | list of string | — | Build-scoped | Levels that count as violations when a new finding appears, for example pageerror, requestfailed and error. |
console.gating | advisory or blocking | — | Build-scoped | Whether new console findings only show in review (advisory) or block finishing it (blocking). Setting it in the file has no effect yet: pixmoat enforces the value from the project’s Settings. |
console.ignore | list of string | [] | Build-scoped | Regular expressions matched against the message text. Matching entries are dropped. |
default_reviewers
| Key | Type | Default | Scope | Description |
|---|---|---|---|---|
default_reviewers | list of string | — | Project-global | Emails or usernames of the reviewers used when no CODEOWNERS rule matches. |
default_tolerance
| Key | Type | Default | Scope | Description |
|---|---|---|---|---|
default_tolerance | number, 0 to 1 | — | Build-scoped | Mismatch ratio a snapshot may differ from its baseline and still pass (0.0 = exact match, 1.0 = accept any difference). |
diff
| Key | Type | Default | Scope | Description |
|---|---|---|---|---|
diff | object | — | Build-scoped | Diff engine settings. |
diff.detect_aa | boolean | — | Build-scoped | Treat pixels that look anti-aliased as matching. |
diff.diff_color | list of 4 × integer, 0 to 255 | — | Build-scoped | RGBA color [R, G, B, A] used to highlight changed pixels in the diff image. |
diff.dpr | integer, 1 to 3 | — | Build-scoped | Device pixel ratio of the screenshots (1, 2 or 3). |
diff.threshold | number, 0 to 1 | — | Build-scoped | Color sensitivity threshold (0.0–1.0). Lower values flag subtler color changes. |
flakiness
| Key | Type | Default | Scope | Description |
|---|---|---|---|---|
flakiness | object | — | Build-scoped | Flakiness detection settings. |
flakiness.captures | integer, 1 to 5 | — | Build-scoped | Captures per snapshot (1–5). More captures detect non-deterministic rendering more reliably but slow the test run down. |
flakiness.flakiness_threshold | number | — | Build-scoped | Mismatch ratio between captures above which a snapshot counts as flaky. |
flakiness.quarantine_after | integer, at least 0 | — | Build-scoped | Consecutive flaky builds before a snapshot is quarantined. |
flakiness.recovery_after | integer, at least 0 | — | Build-scoped | Consecutive stable builds before a quarantined snapshot returns to normal review. |
git_provider
| Key | Type | Default | Scope | Description |
|---|---|---|---|---|
git_provider | object | — | Project-global | Git provider connection settings. The token and webhook secret are set in the UI or environment variables, never in this file. |
git_provider.base_url | string | — | Project-global | Base URL of the git host API, for example https://gitlab.example.com. |
git_provider.comment_body | string | — | Project-global | Generic provider: body template for comments. |
git_provider.comment_url | string | — | Project-global | Generic provider: URL template for comments. |
git_provider.enabled | boolean | — | Project-global | Whether the integration is enabled. |
git_provider.event_match | object | — | Project-global | Generic provider: how to recognise an inbound merge event. |
git_provider.event_match.equals | string | — | Project-global | Header value that marks a merge, for example pullrequest:fulfilled. Required. |
git_provider.event_match.header | string | — | Project-global | Header name to check, for example X-Event-Key. Required. |
git_provider.kind | gitlab, bitbucket or generic | — | Project-global | Provider kind. Required. |
git_provider.merge_fields | object | — | Project-global | Generic provider: where to find merge event fields in the payload. |
git_provider.merge_fields.branch | string | — | Project-global | Path to the source branch. |
git_provider.merge_fields.commit_sha | string | — | Project-global | Path to the merge commit SHA. |
git_provider.merge_fields.merged_by | string | — | Project-global | Path to the user who merged. |
git_provider.merge_fields.repo_path | string | — | Project-global | Path to the repository path. |
git_provider.merge_fields.source_head_sha | string | — | Project-global | Path to the source branch head SHA. |
git_provider.merge_fields.target_branch | string | — | Project-global | Path to the target branch. |
git_provider.repo | string | — | Project-global | Repository slug or path, for example group/project. |
git_provider.signature | object | — | Project-global | Generic provider: how to verify inbound webhook signatures. |
git_provider.signature.header | string | — | Project-global | Header that carries the signature, for example X-Hub-Signature-256. Required. |
git_provider.signature.scheme | hmac-sha256 | — | Project-global | Verification scheme. Only hmac-sha256 is supported. Required. |
git_provider.state_map | map of name to string | — | Project-global | Generic provider: maps pixmoat states (for example approved) to the provider’s status strings. |
git_provider.status_body | string | — | Project-global | Generic provider: body template for commit statuses. |
git_provider.status_url | string | — | Project-global | Generic provider: URL template for commit statuses. |
git_provider.variant | cloud or server | — | Project-global | Bitbucket variant. Only used by the bitbucket provider. |
git_provider.workspace | string | — | Project-global | Workspace or namespace, for example a Bitbucket workspace. |
owner_map
| Key | Type | Default | Scope | Description |
|---|---|---|---|---|
owner_map | map of name to list of string | — | Project-global | Maps CODEOWNERS handles to the emails or usernames of project members, for example "@team-checkout": ["alice@example.com"]. |
performance
| Key | Type | Default | Scope | Description |
|---|---|---|---|---|
performance | object | — | Build-scoped | Performance metrics settings. |
performance.enabled | boolean | — | Build-scoped | Collect performance metrics (Core Web Vitals and resource sizes). |
performance.gating | advisory or blocking | — | Build-scoped | Whether performance regressions only show in review (advisory) or block finishing it (blocking). Setting it in the file has no effect yet: pixmoat enforces the value from the project’s Settings. |
performance.regression_threshold | number, 0 to 1 | — | Build-scoped | Allowed change from the baseline before a metric counts as a regression (0.0–1.0, where 0.15 means 15%). |
performance.thresholds | object | — | Build-scoped | Per-metric soft-fail and hard-fail thresholds. |
performance.thresholds.cls | object | — | Build-scoped | Cumulative Layout Shift, as a unitless score. |
performance.thresholds.cls.hard_fail | number, at least 0 | — | Build-scoped | Failure threshold. A value above it fails the metric; with blocking gating the build is rejected. Required. |
performance.thresholds.cls.soft_fail | number, at least 0 | — | Build-scoped | Warning threshold. A value above it marks the metric degraded. Required. |
performance.thresholds.fcp | object | — | Build-scoped | First Contentful Paint, in milliseconds. |
performance.thresholds.fcp.hard_fail | number, at least 0 | — | Build-scoped | Failure threshold. A value above it fails the metric; with blocking gating the build is rejected. Required. |
performance.thresholds.fcp.soft_fail | number, at least 0 | — | Build-scoped | Warning threshold. A value above it marks the metric degraded. Required. |
performance.thresholds.inp | object | — | Build-scoped | Interaction to Next Paint, in milliseconds. |
performance.thresholds.inp.hard_fail | number, at least 0 | — | Build-scoped | Failure threshold. A value above it fails the metric; with blocking gating the build is rejected. Required. |
performance.thresholds.inp.soft_fail | number, at least 0 | — | Build-scoped | Warning threshold. A value above it marks the metric degraded. Required. |
performance.thresholds.lcp | object | — | Build-scoped | Largest Contentful Paint, in milliseconds. |
performance.thresholds.lcp.hard_fail | number, at least 0 | — | Build-scoped | Failure threshold. A value above it fails the metric; with blocking gating the build is rejected. Required. |
performance.thresholds.lcp.soft_fail | number, at least 0 | — | Build-scoped | Warning threshold. A value above it marks the metric degraded. Required. |
performance.thresholds.total_js_size | object | — | Build-scoped | Total JavaScript size, in bytes. |
performance.thresholds.total_js_size.hard_fail | number, at least 0 | — | Build-scoped | Failure threshold. A value above it fails the metric; with blocking gating the build is rejected. Required. |
performance.thresholds.total_js_size.soft_fail | number, at least 0 | — | Build-scoped | Warning threshold. A value above it marks the metric degraded. Required. |
performance.thresholds.total_transfer_size | object | — | Build-scoped | Total transfer size, in bytes. |
performance.thresholds.total_transfer_size.hard_fail | number, at least 0 | — | Build-scoped | Failure threshold. A value above it fails the metric; with blocking gating the build is rejected. Required. |
performance.thresholds.total_transfer_size.soft_fail | number, at least 0 | — | Build-scoped | Warning threshold. A value above it marks the metric degraded. Required. |
performance.thresholds.ttfb | object | — | Build-scoped | Time to First Byte, in milliseconds. |
performance.thresholds.ttfb.hard_fail | number, at least 0 | — | Build-scoped | Failure threshold. A value above it fails the metric; with blocking gating the build is rejected. Required. |
performance.thresholds.ttfb.soft_fail | number, at least 0 | — | Build-scoped | Warning threshold. A value above it marks the metric degraded. Required. |
removal_gating
| Key | Type | Default | Scope | Description |
|---|---|---|---|---|
removal_gating | advisory or blocking | — | Build-scoped | How removed screenshots gate the review. Setting it in the file has no effect yet: pixmoat enforces the value from the project’s Settings. |
retention
| Key | Type | Default | Scope | Description |
|---|---|---|---|---|
retention | object | — | Project-global | Build retention policy. |
retention.branch_rules | list of object | [] | Project-global | Per-branch overrides of the retention settings. |
retention.branch_rules[].branch | string | — | Project-global | Branch name or glob pattern, for example release/*. Required. |
retention.branch_rules[].delete_after_days | integer, at least 0 | — | Project-global | Delete builds on matching branches older than N days. |
retention.branch_rules[].keep_builds | integer, at least 0 | — | Project-global | Keep the N most recent builds on matching branches. |
retention.delete_after_days | integer, at least 0 | — | Project-global | Delete builds older than N days. |
retention.keep_builds | integer, at least 0 | — | Project-global | Keep the N most recent builds per branch. |
review_policy
| Key | Type | Default | Scope | Description |
|---|---|---|---|---|
review_policy | object | — | Project-global | Review approval policy. Omit the section for no policy. |
review_policy.agent_may_finish | boolean | — | Project-global | Allow an AI agent to finish a review the policy covers. |
review_policy.applies_to_branches | list of string | — | Project-global | Branch names or glob patterns the policy applies to. Omit to apply it to every branch. |
review_policy.min_approvals | integer, at least 1 | — | Project-global | Approvals needed before a build can be approved (at least 1). |
review_policy.require_codeowner_approval | boolean | — | Project-global | Require an approval from a code owner of each changed snapshot. |
review_policy.require_distinct_from_author | boolean | — | Project-global | Don’t count approvals from the author of the change. |
review_policy.required_role | project_admin or org_admin | — | Project-global | Lowest role whose approvals count. |
themes
| Key | Type | Default | Scope | Description |
|---|---|---|---|---|
themes | map of name to object | — | Build-scoped | Named themes to capture each snapshot in, for example light and dark. |
themes.<name>.media | string | — | Build-scoped | Media feature to emulate, for example "(prefers-color-scheme: dark)". Required. |
viewports
| Key | Type | Default | Scope | Description |
|---|---|---|---|---|
viewports | map of name to string matching ^[1-9][0-9]*x[1-9][0-9]*$ | — | Build-scoped | Named viewport presets. Each value is a WIDTHxHEIGHT string of positive integers, for example desktop: "1280x720". |
webhook
| Key | Type | Default | Scope | Description |
|---|---|---|---|---|
webhook | object | — | Project-global | Webhook settings. The webhook secret is set in the UI or an environment variable, never in this file. |
webhook.on_approved | boolean | — | Project-global | Send a webhook when a build is approved. Stored but not used yet: pixmoat sends a webhook for every approved and rejected build. |
webhook.on_rejected | boolean | — | Project-global | Send a webhook when a build is rejected. Stored but not used yet: pixmoat sends a webhook for every approved and rejected build. |
webhook.provider | generic, github or gitlab | — | Project-global | Payload format sent to the endpoint. Stored but not used yet: every webhook is sent with the same JSON payload. |
webhook.url | string | — | Project-global | Endpoint that receives a POST request when a build is approved or rejected. |