ReferenceProduct contracts

Configuration and limits

Implemented workspace, repository, CI bridge, Agentic QA, and deployment settings for the current dogfood release. Values shown as defaults are the defaults enforced by the application.

Repository policy

Owners and administrators configure repository policy. Review finding severity, review job failure, and QA merge blocking are independent controls.

Setting	Values and default
`Review enabled`	true
`Review blocks at`	major by default; critical, major, advisory, or never
`Allow review CI job failure`	false; synchronized to GitLab independently of the finding threshold
`Enforce enabled`	false
`Agentic QA enabled`	false
`Agentic QA runs`	review_passed by default; review_passed, review_clean, or always
`QA required for run`	false
`QA blocks provider merge`	false
`QA advisory failure`	neutral by default; neutral, success_with_warning, or skipped
`Default target branch`	main by default; verify and change it for repositories whose target branch differs
`Allow fork runtime secrets`	false; reserved in the current release—enabling it does not permit fork QA or fork runtime secrets
`Publish policy`	dashboard_only by default; rich_mr_summary requires explicit publication-risk acknowledgement for every backend; safe_mr_summary requires acknowledgement for Codex dogfood and Codex subscription reviews
`Slack notifications`	Disabled by default; failures_only, blocking_findings, or all_completed when enabled
`Draft remediation MRs`	Disabled and unacknowledged by default; branch prefix code-voucher/fix

GitLab CI bridge setup

Input or output	Contract
`Runner tags`	0-50 unique tags; each tag is at most 255 characters
`Review stage`	Existing GitLab CI stage selected from the default branch; manual fallback defaults to test
`QA stage`	Existing GitLab CI stage selected from the default branch; manual fallback defaults to test
`CODE_VOUCHER_BASE_URL`	Managed non-secret GitLab project variable containing the public HTTPS origin
`CODE_VOUCHER_REVIEW_ALLOW_FAILURE`	Managed GitLab project variable synchronized from repository policy
`Review execution mode`	External status by default; native_ci_bridge only after verified default-branch setup
`Initial setup success`	Validates the proposed setup branch, manages project variables, opens a setup MR when needed, and activates native bridge mode
`Post-merge re-check`	Confirms the managed include is present for native mode or absent for external status before changing active ownership

Generated .gitlab-ci.yml include

include:
  - local: /.code-voucher/code-voucher-ci.yml
    inputs:
      review_stage: test
      qa_stage: test

Repository files

Path	Purpose
`.code-voucher.yml`	Agentic QA startup, exploration, authentication, secret policy, and browser scenarios
`docker-compose.qa.yml`	Attempt-local application topology and readiness dependencies
`Dockerfile.qa`	Optional QA-only application image
`qa/fixtures/**`	Synthetic test records and identities
`qa/stubs/**`	Attempt-local substitutes for external services

Agentic QA YAML keys

Unknown keys are rejected. Repository content can lower supported budgets but cannot enable host access, arbitrary JavaScript, or external secrets.

Key	Contract
`qa.startup`	Required: type=docker_compose, file, service, healthcheck_url, browser_url; build defaults true and timeout_seconds defaults 180
`qa.exploration`	entrypoints defaults [/], changed_routes defaults auto, max_minutes defaults 8, max_pages defaults 12
`qa.auth`	mode only; none is the only supported value and is the default
`qa.secrets`	profile may be none; allow_on_forks must remain false in the dogfood release
`qa.scenarios[]`	id, title, route, required (default true), and a non-empty steps list
`Locator`	Exactly one of test_id, role (+ required name), label, placeholder, or text (+ optional exact)
`Assertions`	visible, hidden, enabled, disabled, checked, selected, text, path, title, or no_actionable_browser_failures

Scenario operations

Each scenario step contains exactly one supported operation. Unknown operations or keys make the repository configuration invalid.

Allowed operations

goto
fill
click
select
check
uncheck
press
expect
screenshot

Press accepts Enter, Escape, Tab, ArrowUp, ArrowDown, ArrowLeft, and ArrowRight. JavaScript, CSS/XPath locators, arbitrary HTTP, file operations, downloads, popups, and cross-origin navigation are denied.

Compose restrictions

The Compose root may contain name, version, services, volumes, and networks. Every service requires an image or repository-relative build and a read-only root filesystem. Named volumes and networks cannot be external or host-controlled. Host ports, host mounts, privileged mode, devices, Docker API access, extra hosts, external secrets, custom network modes, and other host-control options are rejected.

Implemented ceilings

Resource	Platform ceiling
`.code-voucher.yml`	64 KiB; UTF-8 YAML; at most 50 aliases
`Compose file`	512 KiB; UTF-8 YAML; at most 50 aliases
`Exploration entrypoints`	1-20 application paths
`Exploration time`	1-15 minutes
`Exploration pages`	1-30 pages
`Startup timeout`	30-600 seconds
`Scenarios`	20 scenarios per repository
`Steps`	30 per scenario; 200 total per run
`Literal values`	512 characters per route, locator string, or value
`Screenshots`	2 per scenario; 30 total per run
`Navigation`	30 seconds
`Action or assertion`	10 seconds
`QA stage`	15 minutes

Repository configuration may reduce platform ceilings; it cannot increase them. Budget exhaustion is never recorded as a passing scenario.

Operator configuration

These are the main environment-variable families. Production also requires secure Django, Postgres, Redis, cookie, artifact-storage, and worker settings described in the deployment guide.

Area	Configuration
`Public origins`	FRONTEND_BASE_URL, BACKEND_BASE_URL, CORS_ALLOWED_ORIGINS, CSRF_TRUSTED_ORIGINS, DJANGO_ALLOWED_HOSTS
`GitLab identity`	GITLAB_OAUTH_CLIENT_ID, GITLAB_OAUTH_CLIENT_SECRET, GITLAB_OAUTH_REDIRECT_URI; sign-in requests read_user
`Credential encryption`	PROVIDER_TOKEN_MASTER_KEY; use a unique backed-up value per environment
`Workspace invitations`	ORGANIZATION_INVITATION_TTL_SECONDS; defaults to 604800 (seven days)
`Queues and state`	DATABASE_URL, REDIS_URL or the explicit Celery broker/result URLs, plus Celery beat
`Review execution`	REVIEW_EXECUTOR_BACKEND, REVIEW_EXECUTION_MODE, archive ceilings, workspace root, and executor resource limits
`Agentic QA`	QA_EXECUTOR_BACKEND, QA_EXECUTION_MODE, QA_DOGFOOD_ACKNOWLEDGED_RISK, and QA_DOGFOOD_REPOSITORIES
`Codex dogfood`	CODEX_DOGFOOD_ACKNOWLEDGED_RISK and CODEX_DOGFOOD_REPOSITORIES gate the backend; remediation additionally requires exact repository allowlist membership
`MCP server`	MCP_ALLOWED_HOSTS, MCP_ALLOWED_ORIGINS, HTTPS enforcement, and rate-limit settings

CI bridge exit codes

Code	Meaning
`0`	Passed or skipped by policy
`1`	Stage failure
`2`	Operational failure
`3`	Invalid configuration or authentication
`4`	Canceled or superseded