Pull requests

When an engineering station opens a pull request, it is a draft, and it is linked to the card that caused it. That link is what keeps the workflow honest about what is actually in flight.

On the card

A card with a pull request shows it: the branch, the request itself, and its state — open, merged, closed — along with review and check status where the provider reports them.

This is the difference between a workflow that says In QA and one where In QA is backed by a specific diff somebody can open.

Webhooks

Repository webhooks keep that state current. A review left on the pull request, a check that fails, a merge — these arrive and update the card rather than waiting for somebody to notice.

An agent's pull request carries at most 30 files.

Where QA fits

QA verifies the story, and the card carries the pull request, so the QA agent's report is about a specific change rather than about the feature in general. When QA fails the card, the failure returns to Development with the pull request still attached — the engineer's next run is a revision, not a restart.

Conflicts and falling behind

When the base branch moves, a pull request that was fine can stop merging. Nobody has to tell the agents. Before every run on a card, and before every reply in its thread, CodeBook asks the repository host whether each open pull request linked to the card still merges, and the answer is one of the facts the agent is given: Pull request #73 conflicts with main. The engineer is told to bring it up to date before anything else; a reviewer is told not to pass it.

This works the same on GitHub, GitLab and Gitea / Forgejo. On GitHub the engineer merges the base branch into the pull request's branch and resolves each conflict in place; on the other hosts it opens a fresh pull request from the current base.

Cleaning up stale pull requests

An agent with write access can close a pull request without merging and remove its branch — for a stale or duplicate draft whose change is already on the default branch. It gives a reason, which is written on the pull request with the agent's name and the card it was working.

CodeBook decides what may be closed, not the agent:

• only a pull request the factory itself opened (its branch starts with codebook/). One a person opened is refused; a person closes that at the host.
• never one that a run on another card is still working on.

Nothing is lost: a closed pull request can be reopened, and its branch restored, from its page at the host. Agents can also list every pull request of the repository — which are open, which conflict, which card each belongs to — from a card run as well as from a conversation.

A card opens one pull request. Running the card again updates that pull request; a second one is refused while the first is open.

Merging

Agents never merge. One choice per factory, under Factory settings → Policies & budgets, decides what happens once a card has passed every station and rests in Done:

• CodeBook merges — the default. The pull request is merged as soon as the card finishes.
• CodeBook merges, except risky changes. Every finished change gets a risk score; below your line CodeBook merges, from your line up a person does. See Risk-based merging.
• A person merges. Nothing is merged for you; the pull request waits at your repository host.

The rules behind CodeBook merges are fixed:

• Your repository's own checks are respected. Where the repository runs CI, the checks must have passed. Where it runs none, the absence of CI does not block a merge. If the host’s check API fails, CodeBook waits for a successful read; an unavailable response is never treated as no checks. Your stations' review remains a gate, and any configured required runner commands must pass as described below. Test evidence comes from your testing service or command runner.
• A conflict or a failing check goes back to the developer. The card returns to the station that built it, with the reason, gets fixed, and comes round again. After three returns a person is asked instead.
• One merge at a time per repository. Each pull request is checked against the main branch again right before it is merged, so the second of two finished changes is judged against a main branch that already holds the first.
• Only work this factory's agents opened, into the repository's default branch. Anything else is left for a person.
• From now on. It applies to cards that finish after the factory chose it, never to what was already sitting in Done.

One optional setting sits under that choice: Paths a person always merges. List path patterns, one per line — migrations/**, src/auth/**, infrastructure/**, *.sql. A pull request that changes any of them is not merged by CodeBook even when everything else is in order: the card says which file, everyone is told once, and a person merges it at the host. Nothing is protected until you list something.

A second optional setting, Commands that must pass before CodeBook merges, uses a command runner on your own machine: list names such as test and build, and CodeBook runs them against the pull request merged with main as it is now. If another merge lands first, they run again against the new main before this one is merged. It waits for the answer, sends the card back to the developer with the output on a failure, and leaves the pull request for a person if a command cannot be run at all.

A draft is marked ready first, and what CodeBook did is written on the card. Stories that were waiting on that pull request start by themselves afterwards. Merging is done through GitHub today.

If your workflow has a Human review station, a card still waits there for your approval before it reaches Done. Remove that station and nothing waits for a person.

Risk-based merging

A list of protected paths covers what you can foresee. The risk score covers the rest.

When a card has passed every station, CodeBook scores the change from 0 to 100. The score is fixed rules — no AI model reads the change — and every point is a reason you are shown.

What is looked at	Points
What the System Map says the card touches: low, medium, high or critical impact	10, 30, 60 or 80
No impact has been computed for the card	20
It changes authentication or permissions code	+25
It changes billing or payment code	+25
It changes the database schema	+25
It changes infrastructure or the deploy pipeline	+20
It changes dependencies	+10
It is large: more than 400 lines, or more than 1,000	+10 or +20
It touches more than 20 files	+5
It was sent back from a merge on the way	+5 each time, up to 10
A reviewer failed it on the way	+5 each time, up to 15
Only documentation or tests changed	the whole score is 5 to 15

• 0–30, low — copy, styles, documentation, tests, a small contained change.
• 31–70, medium — ordinary product code.
• 71–100, high — authentication, payments, migrations, infrastructure, or a large change in a risky area.

Choose CodeBook merges, except risky changes and where the line is: a person merges high-risk changes, or medium- and high-risk changes.

At or above your line the card says so once: the score, every reason, and that everything else is in order. The people who answer for the workflow are told, and it appears under Needs you on the workspace home. Below the line the pull request merges as before. The score and its reasons are kept on the card's Evidence either way.

If the changed files cannot be read from your repository host, nothing is guessed: the pull request waits.

A merge moves the card

When the pull request is merged, the card can move on. The rule is conservative on purpose — a merge advances the card its pull request belongs to, and nothing else — so the workflow reflects what actually landed without anybody dragging a card to say so.

Where it moves to is set in the repository panel. Attaching a repository fills the target in with the workflow's ending station (its last station if none is marked) and never overwrites a target somebody chose. The card only moves forward, and not if someone already moved it there. Clear Merging a pull request moves its card to keep cards where they are.