What is Multi-repo change?
A single change that must land in several repositories — for example, a web app and the API it calls.
Splitting it into unrelated tickets invites half-shipped features and hand-synced statuses.
On this page
A multi-repo change is one logical change that must land in several repositories to work at all — a client and the API it calls, a schema migration and the service that uses it, a shared library and each of its consumers. The unit of meaning spans repositories; the unit of review and delivery has to follow, or the change ships in pieces that do not work together.
Conventional tooling makes this case awkward by construction: pull requests are per-repository, so teams split the change into per-repo tickets and coordinate by hand — merge this after that, keep the branch names in sync, remember which status lives where. Every "after" and every "remember" is a place for the halves to drift.
Why agents raise the stakes
For human teams, multi-repo drift is an occasional coordination failure. For agent-driven work it is structural, because the costs compound differently:
- Two agents do not hallway-coordinate. Two tickets dispatched independently produce two changes optimised against two briefs, with nobody resolving the seam between them. Interfaces agreed in one run's head never reach the other run.
- Review sees fragments. A reviewing agent checking one repository's diff cannot see the contract violation that lives across the seam — the field the client expects and the API stopped sending.
- Bounces multiply. If one half is returned by review and the other is not, the tree is now inconsistent, and every subsequent dispatch starts from the mismatch.
- Status lies. Two tickets, each "done", describe a feature that does not work. The lie is local to neither ticket and invisible to both.
The unit-of-work principle from agentic engineering applies with full force: the ticket should carry the whole change — every repository it touches — because the brief is the only place the seam can be agreed before it is built.
What single-unit delivery looks like
| Concern | Fragmented (per-repo tickets) | Unified (one change, many repos) |
|---|---|---|
| Brief | Two briefs; the seam is prose in each | One brief; the contract is written once |
| Implementation | Two runs; the seam is improvised | One run in scope of every repository it touches |
| Review | Each half reviewed alone | The seam reviewed as part of the change |
| Delivery | Two PRs, hand-sequenced | One change; PRs per repository, ordered by the platform |
| "Done" | Two statuses that may disagree | One verdict over the whole change |
The implementation column deserves a note: a single agent working across repositories does not mean one giant commit. Repositories still get their own branches and pull requests — the change is one unit of work and review, delivered as the set of PRs that makes it land coherently.
Best practices for multi-repo work
1. Write the contract in the brief
The interface between the repositories — endpoint shape, field names, error semantics — belongs in the change's brief, stated once. Anything agreed only in one half's diff will be improvised by the other half.
2. Keep one unit of review
Review must see every repository the change touches. A change split across two reviews is two chances to miss the seam and no chance to check it.
3. Verify the whole, end-to-end
The QA pass that matters runs across the seam: client against API, consumer against schema. Per-repo suites going green proves less than one honest end-to-end request with the evidence attached.
4. Land with an order, not a race
When PRs must merge in sequence — schema before consumer — the ordering is part of the change. Platforms can enforce it; hand-synced status spreadsheets cannot.
Multi-repo changes in YATFA
YATFA treats the multi-repo change as a first-class unit: one ticket carries work across every repository in scope, one reviewing agent sees the whole change including the seam, and delivery tracks the set of pull requests as one verdict. The review design is described in how YATFA reviews changes.
Frequently asked questions
Shouldn't each repository just have its own ticket?
Only when the changes are genuinely independent. The test: if one half can ship and be correct while the other waits, they are two changes. If shipping one half alone breaks or dead-ends something, they are one change wearing two repository names — and splitting the ticket splits the accountability, not the risk.
Do monorepos solve this?
They dissolve the repository boundary, not the underlying problem: the change still needs one brief, one review, one delivery order. Monorepos make the tooling easier and hide the seam from the org chart; the review and QA discipline is the same either way.
How does review work when repositories have different owners?
The reviewing scope should follow the change, not the chart: a reviewing agent with read scope across the touched repositories can check the seam, while each repository's own protections still gate its merges. What must not happen is each owner reviewing only their half and the seam belonging to no one.