> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roboticks.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Multi-Repo Projects
> How a single Roboticks project spans multiple GitHub repositories — the many-to-one repo→project model, aggregated coverage rollup, default repo, and per-repo columns in the matrix.
# Multi-Repo Projects
Real robotics systems live in many repos. The perception stack, the motion stack, the simulation harness, the shared interfaces — each gets its own repo, its own release cadence, its own owners. Roboticks projects accept that reality: one project can be linked to many repos, and coverage rolls up across them.
The model is **many-to-one**: many repositories belong to one project. The reverse is not supported — a repository cannot be split across projects. If you need that, factor the shared code into a third repo and connect it to its own project.
## The model
```mermaid theme={null}
%%{init: {"theme": "neutral", "themeVariables": {"primaryColor": "#4040ff"}} }%%
flowchart LR
P["Project: warehouse-amr"] --> R1["repo: amr-perception
(default)"]
P --> R2["repo: amr-motion"]
P --> R3["repo: amr-simulation"]
P --> R4["repo: amr-interfaces"]
R1 -- tests --> Reqs["Shared requirement set
(REQ-001 ... REQ-200)"]
R2 -- tests --> Reqs
R3 -- tests --> Reqs
R4 -- tests --> Reqs
```
All four repos write into the same project's requirement set. Tests in any repo can `@confirms` any requirement. The matrix shows them all in a single grid with a **Repository** column for drill-in.
## The default repo
One repo per project is designated **default**. The default repo is where Roboticks reads:
* `roboticks/requirements.yaml` (or `requirements.d/`) — the project's authoritative requirement set if you use inline YAML.
* `roboticks.yaml` — the project-level configuration (test commands per OS, runner pool selection, evidence pack policy).
* Standards pin manifests.
Tests can live in **any** linked repo. Only configuration lives in the default. Pick the default on project creation; change it later in **Settings → Repositories → Set as default**.
Most teams pick the repo with the highest contributor count as the default — the one engineers naturally edit first. For monorepo-adjacent layouts, the "interfaces" repo is often the right home for the requirement set.
## Connecting multiple repos
After installing the GitHub App (see [Installation](/github-app/installation)), link each repo:
Dashboard → **Settings → Repositories**. You'll see every repo the installation can access.
Click **Link** next to each repo you want in the project. Repos can be unlinked later without losing data.
From the linked list, click the star icon next to the repo that owns the requirement set and config.
Push to any linked repo and watch a Check Run land. Same Roboticks check name across all repos in the project.
## Coverage rollup across repos
A requirement is **confirmed** if any confirming test in any linked repo passes on its repo's current SHA.
```mermaid theme={null}
%%{init: {"theme": "neutral", "themeVariables": {"primaryColor": "#4040ff"}} }%%
flowchart LR
REQ["REQ-014
'E-stop in 100 ms'"]
T1["amr-motion/tests/test_estop.py
@confirms(REQ-014) — PASS on abcd..."] --> REQ
T2["amr-simulation/tests/test_estop_sim.py
@confirms(REQ-014) — PASS on 9876..."] --> REQ
REQ -- "all PASS" --> S["state: confirmed"]
```
Inputs to the rollup:
* The **current SHA** on each linked repo's default branch.
* The **last-known-good result** of each confirming test on that SHA.
If `amr-motion` is at SHA `abcd1234` with `test_estop` passing, and `amr-simulation` is at SHA `9876fedc` with `test_estop_sim` passing, REQ-014 is `confirmed`. If either fails on its current SHA, the rollup degrades.
## Freshness rules
Each linked repo has an **last-run-at** timestamp on its default branch. The dashboard shows it under **Settings → Repositories**. A repo with stale results (older than the project's `freshness_threshold`, default 7 days) shows an amber warning — its results still count toward the rollup, but the warning prompts you to either re-run the suite or accept that the repo is intentionally dormant.
To force a re-run on all repos at once:
```bash theme={null}
rbtk project rerun-all
```
This dispatches a fresh test job per repo at the current SHA of the default branch. Useful before cutting a release that depends on all repos being green.
## Per-repo column in the matrix
The matrix gets a **Repository** column when the project has more than one linked repo. Each cell in the grid shows the repo the confirming test lives in:
```
tests →
┌────────────────────────────────────────────────────────┐
│ amr-motion/ amr-simulation/ amr-perception/ │
│ test_estop.py test_estop_sim.py test_obstacle.py │
requirements
REQ-014 │ ✅ pass ✅ pass — │ confirmed
REQ-027 │ ✅ pass — — │ confirmed
REQ-101 │ — — ❌ fail │ regression
└────────────────────────────────────────────────────────┘
```
Filter the **Repository** column to scope the matrix to a single repo — useful for repo-specific code review.
## Affected-requirement detection across repos
[Change-impact analysis](/traceability/change-impact) crosses repo boundaries. If `amr-interfaces` changes the message definition for `EStopState.msg`, the change-impact step finds every test in every linked repo that imports it, then maps those tests to requirements.
The deterministic path needs the import graphs of all repos. The platform refreshes these lazily — first PR after a code addition rebuilds the graph and caches it.
## Per-repo Check Runs vs project-level
Each PR on a linked repo gets its own Roboticks Check Run on that PR. The Check Run summary shows:
* The affected requirements **specific to this PR**.
* The project-level coverage state — how this PR moves the needle across the full system.
This is the right balance: the developer working in `amr-perception` sees only the requirements their PR could affect, but is reminded that the project as a whole has 12 gaps still open in the safety set.
## Releases and snapshots
A release in a multi-repo project pins **one SHA per linked repo**. The CLI:
```bash theme={null}
rbtk release create v1.2.0 \
--repo amr-perception=abcd1234 \
--repo amr-motion=9876fedc \
--repo amr-simulation=11112222 \
--repo amr-interfaces=33334444
```
The snapshot records all four SHAs. The evidence pack embeds them. To replay later, the CLI checks out all four at the recorded SHAs and re-dispatches the test suite per repo.
See [Snapshotting](/requirements/snapshotting) for the snapshot mechanics.
## Permissions
The GitHub App installation needs access to **every** linked repo. If the installation is org-wide, this is automatic; if per-repo, you need to explicitly grant access to each repo on the GitHub side. The dashboard surfaces any repo where the link exists but the App can't read — usually a sign the installation lost access.
## Limits
| Tier | Repos per project |
| ---------- | ----------------- |
| Free | 3 (1 private) |
| Team | Unlimited |
| Enterprise | Unlimited |
| Sponsored | Unlimited |
For projects above \~50 linked repos, contact us — there are server-side index optimisations we flip on per project.
## Next
The Repository column and filter.
The rollup rules in detail.
Connecting more repos to a project.
Multi-repo SHA pinning in releases.