How-to guideOperations

Troubleshoot a run

Start with the durable run record. It distinguishes code findings, policy outcomes, repository setup failures, and platform failures.

GitLab rejects the service-account token

Create the token while signed in as the dedicated GitLab account, include the api scope, and confirm it has not expired. Add that account to the relevant group or project before reconnecting it in workspace Settings.

A repository is missing from discovery

Code Voucher only sees repositories available to the configured service account. Check the account's GitLab group/project membership, rotate the token if its scope changed, then refresh discovery.

repository_config_invalid

Check that .code-voucher.yml and docker-compose.qa.yml exist, contain only documented keys, and avoid ports, host volumes, env_file, custom networks, privileged mode, restart policies, and the Docker socket.

application_readiness_timeout

The health URL did not become successful before the startup budget expired. Check migrations, synthetic seeding, the service name in the health URL, and readiness of local substitutes.

browser_policy_violation

The browser attempted a cross-origin request, popup, download, additional page, blocked frame, or exceeded an evidence budget. Route browser-visible integration calls through the application origin.

pass_with_advisories

Required routes loaded, but an optional scenario failed or the browser observed an actionable same-origin console or request error. Open the private QA evidence for the affected route.

The GitLab job waits indefinitely

The bridge waits five seconds for the webhook, then attempts read-only recovery up to three times. Confirm Celery Beat and the webhooks/orchestrator queues are running, CODE_VOUCHER_BASE_URL is reachable over HTTPS, and the repository record matches the GitLab project path. An operational failure exits with code 2; review findings exit with code 1.

A patch proposal failed

Repository managers can retry failures marked retryable from the run page. Patch history is preserved and limited to three attempts; private prompts, model output, executor logs, and exception details are never shown in the dashboard.

Review passed but QA did not start

QA starts only after review approves the current commit. Superseded runs and reviews with blocking findings do not enqueue QA.

The app returns an internal server error

Treat this as an environment or scenario failure first. Verify migrations, seed completion, health readiness, and the synthetic dependency used by that route.

A finding is unrelated to the diff

Open the rejected observations section. Only findings anchored to trusted changed hunks may affect the review verdict; unanchored model observations remain non-gating.

An external integration fails in QA

Replace it with an attempt-local fail-closed adapter and declare the behavior exercised by each scenario. Do not add the production credential.

Bridge exit codes

code-voucher-ci

0  passed or policy-skipped
1  stage failure
2  operational failure
3  invalid configuration or authentication
4  canceled or superseded

The exit code controls GitLab job status. Full failure context remains in the Code Voucher run.