Skip to main content

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

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

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), link each repo:
1

Open the project's repositories settings

Dashboard → Settings → Repositories. You’ll see every repo the installation can access.
2

Link each repo

Click Link next to each repo you want in the project. Repos can be unlinked later without losing data.
3

Set the default

From the linked list, click the star icon next to the repo that owns the requirement set and config.
4

Verify the link

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. 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: 
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 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: 
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 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

TierRepos per project
Free3 (1 private)
TeamUnlimited
EnterpriseUnlimited
SponsoredUnlimited
For projects above ~50 linked repos, contact us — there are server-side index optimisations we flip on per project.

​
Next

Matrix

The Repository column and filter.

Coverage

The rollup rules in detail.

Installation

Connecting more repos to a project.

Snapshotting

Multi-repo SHA pinning in releases.