Fix a board that doesn't build or ship
On this page
Use this page when your machine and desk are ready but cards are not built, a build fails, or a pull request does not ship. Work down the checks in order: the first one that fails is your answer.
Nothing is claimed
Check these five things, in this order:
opvs boards projects <board-id> # 1. resolution must be "resolved"
opvs tasks list --board <board-id> --status pending # 2. are the cards in Ready, or still in Backlog?
opvs boards health <board-id> --profile factory # 3-4. roles and claim wiring
opvs tasks get <REF> # 5. ready_for_buildersCheck | When it fails | What to do |
|---|---|---|
1. One project |
|
|
2. Ready, not Backlog | New cards land in Backlog, which builders never claim |
|
3. The builder's role | Ready is claimable by the role | Give the worker the role |
4. A column declares a role | A board that was only retyped to | Create the board as |
5. The builder switch | Board Settings → Builders is off | Switch it on. Every card that is truly ready is claimed at the next poll |
A dependency can also hold a card back. A card is not claimable until every card it waits on is done, and a card that waits on something that can never finish waits forever without an error. The dead_dependency check in opvs boards health finds those.
The card is in Ready but not ready for builders
opvs tasks get <REF> lists what is missing under ready_for_builders.missing. A builder needs a brief of at least 200 characters, a harness, the credential that harness needs, and a task type.
Fix: fill what missing names. If the card should stay with a person, set opvs tasks update <REF> --claimable-by human.
A build failed
Read the card first:
opvs tasks get <REF> # blocked_reason, and the gate output in the comments
opvs builds read <REF> # while it runs: the current command and recent stepsA first build that fails pushes nothing. A build sent back onto its own open pull request is different: a red test run can still push commits, and the pull request is labelled hold:red until a green push removes the label.
To run a failed card again, clear its blocked reason, then move it to Ready in one write. Two writes let a builder claim between them, and the card runs twice. Never move a Done card back to Ready: it is claimed and rebuilt within seconds.
A desk claims a card and fails within seconds
The desk is switched on but cannot run the card's engine. Read worker.harnesses in the desk's health: it lists which engines it can run and why the others are not available. Pin the card to an engine the desk has, or install that engine on the desk.
The pull request opened but the card is still Executing
Read the card's status, not only its column. If it did not move to review, move it yourself and note why in a comment.
The pull request is a draft
Changes in the risky set (migrations, auth, billing, security, money) open as draft pull requests. A builder never marks them ready. A person reviews and marks them ready in the same step as signing off. Your review policy decides what counts as risky for your repository.
Nothing merges
opvs ship status --project <project-id>What status shows | Why | What to do |
|---|---|---|
No ship line ( | The project has none yet |
|
| Practice watches and does not ship |
|
Ship app | GitHub is not connected for this repository |
|
The pull request is held | Someone ran |
|
An owner-class release waits | It needs approval of its exact head commit from a ship-line owner |
|
A slug that matches two projects is refused; pass the project's id from opvs projects list.
Related: How a card moves, Board health.