Issues & triage

File a defect against a test, run and step, move it through triage, reproduce it as a failing test, and push it to GitHub, Jira or Linear.

A red run tells you a test failed. It does not survive the next green run, it does not carry a decision, and it cannot be handed to somebody. An issue is the record that does: a defect filed against a test, a run and a step, with a status somebody moved it to.

Issues are org-wide, not per project — the board at /issues is one queue for the whole workspace, filterable down to a project. They are not plan-gated: every plan can file, read and triage them. Only pushing one to an external tracker needs Pro.

Where an issue comes from

Three paths exist, and it is worth knowing that is all three.

From a failed run. Open a failing run, Report issue. Vera copies the test, the run, the failing step index and the error into the issue, and titles it "{test} failed at step N" if you do not. This is the only way to create an issue from the dashboard — there is no blank "New issue" button.

From an agent. report_issue over MCP files one with source: mcp, taking a title, description, severity, labels and any of the project / test / run / step / chain-run pointers. When the token belongs to a person, the issue is attributed to them rather than to "a token".

From Vera itself. When the repair ladder exhausts every strategy without getting a test green, it files the failure as an issue with source: ai, naming the strategies it tried and the last error. At most one open AI issue exists per test, so a nightly gardener cannot fill your board.

A fourth exists at the API — POST /api/issues creates one with arbitrary context — but it is reachable only from a dashboard session, not from a vera_ token, so CI cannot file issues today.

What an issue holds

Field	Values
Severity	`critical`, `major`, `minor` — defaults to `major`
Status	`open` → `acknowledged` → `resolved` / `wont_fix` → `closed`, and `reopen` from any of them
Source	`user`, `mcp`, `ai` — always set by the server, never by the caller
Links	project, test, run, failing step index, chain run — kept as plain ids

Those pointers are deliberately not foreign keys. An issue outlives the run it was filed from, and retention deleting that run must not delete the record of the bug.

Closed is terminal in the sense that the only move out of it is Reopen.

There are no comments, assignees, due dates or attachments. An issue is a pointer and a decision, and the discussion belongs in the tracker you push it to.

Triage

The board at /issues filters on project, status, severity and source, all carried in the URL so a filtered view is a link you can send. Twenty rows a page. A row shows the severity, the title, its project, an AI badge when Vera filed it, and its status; the overflow menu offers only the transitions that are legal from where it is.

Opening one is a dialog, addressable as ?issue=<id> — the issue is fetched by id, so a link to something on page four still opens.

From an agent, list_issues reads the queue with the same filters, and update_issue moves one. update_issue requires confirm: true: Vera does not change the state of your defect tracker because a model thought it should.

Nothing here is deduplicated

Two people reporting the same bug produce two issues. There is no fingerprint, no hash, no merge. The single exception is the one-open-AI-issue-per-test rule above, which exists to bound an automated writer rather than to tidy a human queue.

If that matters to you, the tracker you push to is the place with the merge button.

Reproducing an issue as a test

This is the part worth the ritual. A bug report is prose; a failing test is evidence. Vera will turn one into the other, and it will not save anything until you say so.

Propose a repro on an open issue composes the issue text, the linked failing run and step, and live page context, and asks the model for one test that fails the way the issue describes. You can steer it:

Option	What it does
Page URL	Where to ground the proposal, when the issue does not say
Extra guidance	Free text handed to the generator
Depth	Single page, or Multi-page journey — a live walk, bounded by your plan's journey caps

Nothing is persisted at this stage. You get steps to read. If no page can be derived from the issue at all, the proposal refuses with insufficient context rather than inventing a starting point.

Approve, save & run writes the test — tagged regression — links it to the issue, and runs it once. What that run does decides the issue's repro status:

Status	Meaning
Reproduced	It ran red. This is the success case: you now have the bug under test.
Not reproduced	It passed on the first run, and that is flagged loudly. A green "repro" proves nothing about the bug.
Passing	It was red, and has since run green. Evidence the fix landed.
Not run	Saved and linked, but this deployment could not run it inline.

Only a repro that was actually observed reproduced can later flip to passing. A test that never failed cannot prove a fix.

And a green repro does not close the issue. The chip changes; the status does not. A passing run is evidence, and only a person decides a defect is done.

One issue carries one repro. Relinking over an existing one is an explicit replace, not a silent overwrite.

Over MCP the same two steps are generate_repro_test and approve_repro_test. The first blocks while it drives a browser — expect tens of seconds, up to four minutes — so raise your client's tool timeout rather than firing it twice.

Pushing to GitHub, Jira or Linear

Push to… in the row or detail menu creates the issue in your tracker and records the link on the Vera issue. Configure credentials once at Settings → Trackers; they are sealed at rest and never read back.

Vendor	What it needs
GitHub	The Vera GitHub App with `issues: write`, or a stored token; plus the repo
Jira	Base URL, account email and API token; plus the project key
Linear	An API key; plus the team id

The pushed body carries the description plus back-links to the Vera issue, its project, test, run and failing step. (Set a public URL for the deployment or those come out as bare ids.)

Two honest limits: pushing twice adds a second link and warns rather than refusing, and the sync is one-way. Closing the GitHub issue does nothing to the Vera one.

Push requires the Pro notifications feature. Everything else on this page does not.

Getting told

Filing an issue emits an issue-created event to the notifications hub, which fans out to whatever rules you have configured — webhook, Slack, or email — at Settings → Notifications. Rules can be org-wide or scoped to one project.

The repro-passing chip is deliberately quieter: it updates the issue and sends nothing, because "a test went green" is not news until a person calls it a fix.