Link repositories into a workspace
A threat that crosses a service boundary belongs to neither repository on its own. The gateway knows it proxies a refund; the billing service knows it debits a ledger; only together do they describe the risk.
You will link two repositories into a workspace, produce a report from each, and merge them into one model. Everything here was run against GuardLink 2.7.0, and the validate, merge, estate and application-view steps again on 2.7.1.
Before you start
Section titled “Before you start”- GuardLink installed. See Install GuardLink.
- Two repositories you can commit to. This page uses
gatewayandbilling. - Each one initialised with
guardlink init, and annotated. Runguardlink initin each repository yourself:link-projectwrites.guardlink/workspace.yamland agent instruction files, not a model. In the run below it labelled both repositoriesauto-initialized (no prior guardlink setup)even thoughguardlink inithad already run in each.
How a workspace fits together
Section titled “How a workspace fits together”Each repository stays self-contained. It parses, validates, and gates on its own model exactly as before. The workspace is a second pass over the reports those repositories publish.
flowchart TB
G["gateway<br/>its own annotations"] --> GR["guardlink report --format json"]
B["billing<br/>its own annotations"] --> BR["guardlink report --format json"]
GR --> M(["guardlink merge"])
BR --> M
M --> W["one model across both,<br/>plus a workspace dashboard"]
M --> U["cross-repo references<br/>it could not resolve"]
class W,U emphasis
Nothing about the per-repo loop changes. That matters for adoption: a service team keeps its own gate, and the workspace is assembled from what they already publish rather than from a central checkout of everything.
Link the repositories
Section titled “Link the repositories”-
Point
link-projectat the repositories and name the workspace.Terminal window npx guardlink link-project gateway billing -w paymentsLinking 2 repos into workspace "payments"...⚡ gateway — auto-initialized (no prior guardlink setup)⚡ billing — auto-initialized (no prior guardlink setup)✓ gateway — workspace.yaml written, agent files updated✓ billing — workspace.yaml written, agent files updated✓ Linked 2 repo(s) into "payments"↻ Updated 4 agent instruction file(s)Next steps:1. Review and commit .guardlink/workspace.yaml in each repo2. Add "guardlink report --format json -o guardlink-report.json" to each repo's CI3. Use "guardlink merge" to combine reports into a unified dashboard -
Read what it wrote. Each repository gets its own copy, naming itself and its siblings:
gateway/.guardlink/workspace.yaml workspace: paymentsthis_repo: gatewayrepos:- name: gateway- name: billingthis_repois what makes the file repository-specific, so the two copies are not identical and both are committed.
Each member is named after its directory. To use other names, such as the ones
a service registry already uses, give them on a fresh link with the repeatable
--member name=path, and name a member you add later with --name:
npx guardlink link-project --workspace shop --member frontend=./web --member accounts=./authnpx guardlink link-project --add ./billing-svc --name payments --from ./webworkspace: shopthis_repo: paymentsrepos: - name: frontend - name: accounts - name: paymentsAn existing workspace.yaml keeps the names it stores.
Reference an asset in another repository
Section titled “Reference an asset in another repository”A reference to another member’s definition is the plain #id that member
declares. Billing declares its ledger in its own definitions file:
// @asset Billing.Ledger (#ledger) -- "Account balances"// @control Refund_Permission_Check (#refund-check) -- "Caller must hold refund permission on the account"The gateway records that its edge flows into that ledger, with no repository prefix:
@source file:src/routes.js line:1 symbol:handleRefund@flows #edge -> #ledger via POST./billing/refund@exposes #edge to #unauth-refund [critical] -- "No authorization check before proxying"Ids are flat and must be unique across the whole workspace. Billing’s mitigation refers to the gateway’s threat the same way:
@source file:src/ledger.js line:1 symbol:refund@mitigates #ledger against #unauth-refund using #refund-check -- "canRefund checked before the balance changes"With billing checked out beside it, guardlink validate in the gateway names
where the reference is defined:
⚠ src/routes.js:1: Linked reference: #ledger is defined in sibling billing; resolved at merge, coverage is not checked here.That is a warning, and validate exits 0. Whether billing’s control
covers the gateway’s exposure is the merge step’s question, not this one’s.
Check every reference against the siblings
Section titled “Check every reference against the siblings”--workspace turns a reference no linked member defines into an error. With
#ledger misspelled as #ledgr:
npx guardlink validate . --workspace✗ src/routes.js:1: Workspace reference #ledgr is not defined in any linked member.⚠ src/routes.js:1: Dangling reference: #ledgr is never defined in any linked member checked
1 error(s), 1 warning(s)Truncated after the counts. It exits 1. Without --workspace, the same typo
is only the warning, and validate exits 0.
--workspace also fails when a sibling is not there to check. With billing
moved out of the parent directory:
✗ .guardlink/workspace.yaml:1: Workspace check incomplete: unavailable or unreadable sibling checkouts: billing.⚠ src/routes.js:1: Linked reference: #ledger is not defined locally; sibling resolution not checked for billing. Run guardlink validate --workspace with sibling checkouts present.Truncated after the two diagnostics. It exits 1, so a gate built on
--workspace cannot pass by not finding the other repository. Siblings are
found by the this_repo each one stores, not by directory name: renaming
billing’s directory beside the gateway did not hide it.
Merge the reports
Section titled “Merge the reports”Each repository publishes a JSON report. In CI that is a step; here it is one command each.
-
Produce a report per repository.
Terminal window (cd gateway && npx guardlink report . --format json -o guardlink-report.json)(cd billing && npx guardlink report . --format json -o guardlink-report.json) -
Merge them.
Terminal window npx guardlink merge gateway/guardlink-report.json billing/guardlink-report.json -w payments --summary-onlyMerging 2 report(s)...✓ payments — 2/2 repos loaded7 annotations | 2 assets | 1 threats | 1 controls1 mitigations | 1 exposures | 1 unmitigated0 confirmed | 1 flows | 2 refs resolved | 0 unresolved0 unreadable annotation(s) (0 error(s))⚠ Tag "#claude-code" defined in gateway (owner) and also in: billingTruncated after the console summary.
--summary-onlythen prints the same figures as a markdown summary, with a table per section, and ends with the advisory line below. The warning is explained under duplicate definitions.
The two counters at the end of the fourth line are the ones to watch.
refs resolved is how much of your cross-repo wiring joined up: here both
of it, the gateway’s #ledger and billing’s #unauth-refund.
unresolved is how much did not, with a warning per reference naming the
repository that wrote it. confirmed is counted separately from unmitigated because
an @accepts silences a reproduced exploit nowhere in the product, and the
unreadable annotation(s) line is the denominator for all of it: a repository
whose annotations did not parse is not a repository with nothing wrong.
--summary-only prints the text and skips the dashboard. Without it, merge
also writes workspace-dashboard.html, a self-contained page you can open
directly or publish from CI. --json <file> writes the merged model, and
--diff-against <file> compares against a previous merge for a weekly summary.
Advisory by default, and --strict exits 1 on an unmitigated exposure, a
reproduced @confirmed exploit, or a report it could not read:
Advisory — nothing here failed the build. Run with --strict to gate on it.Ask the merged model what is open
Section titled “Ask the merged model what is open”guardlink estate reads back the file merge --json wrote, so the estate answer
and the merge’s own totals come from one computation rather than two:
npx guardlink estate merged.jsonpayments — estate risk, from 2/2 repo report(s) merged 2026-11-17T10:07:29.428Z
Repositories ⚠ gateway — 1 open, 0 confirmed 4c4e631 ✓ billing — 0 open, 0 confirmed c0ebb59
1 open exposure(s) — 1 critical
gateway [critical] #edge → #unauth-refund gateway/src/routes.js:1 No authorization check before proxyingTruncated after the open list. The output continues with the merge’s warnings
under From the merge: and the advisory line. Each repository line ends with
the commit its report was taken at.
It says how much of the estate it read first, because “0 open” over 0 of 4
repositories is the same vacuous green one level up — an unexpanded glob and a
pipeline that never uploaded both reach it. --strict exits 1 on an estate
that read nothing. It also refuses a per-repo threat-model.json: both are
model-shaped JSON, and a lenient reader would answer “0 repos, 0 open” from a
file describing one repository.
Duplicate definitions get an owner
Section titled “Duplicate definitions get an owner”Two repositories that each declare the same tag are not an error. The merge picks one as authoritative and says which:
⚠ Tag "#claude-code" defined in gateway (owner) and also in: billingHere the shared id is #claude-code, the coding-agent actor that each
repository’s report records from its agent configuration. For a threat, asset
or control, read it rather than ignore it. Two services that both define the
same threat id usually mean two teams described it separately, and the merged
model will carry one description for both.
Read the application as one model
Section titled “Read the application as one model”merge joins reports after the fact. guardlink application-view reads the
member checkouts you select directly, and returns one model with a receipt of
what it read. List the members in a manifest:
{ "schema": "guardlink.application-manifest/v1", "name": "payments", "members": [ { "id": "gateway", "guardlinkIdentity": "gateway", "service": "gateway", "relativePath": "gateway" }, { "id": "billing", "guardlinkIdentity": "billing", "service": "billing", "relativePath": "billing" } ]}npx guardlink application-view . --manifest selected.json > view.jsonThe JSON carries schema: "guardlink.application-view/v1" and receipt,
model, diagnostics, references and flowGroups. Read the receipt first.
Here it said "completeness": "complete", and each member recorded its
revision: the commit, branch and dirty state, and digests of its source,
annotations and configuration.
With billing moved away, the same command still succeeded and kept billing in the roster with a reason:
"state": "missing", "components": { "model": { "state": "missing", "reason": "Selected checkout billing is missing." } }, "reasonCode": "member-missing",An excerpt of billing’s member entry. The receipt read "partial", and
diagnostics carried a workspace-incomplete error. Add --strict and the
partial collection exits 1 instead. --member <id> projects one member, and
--capabilities prints the contract without reading a project.
The global --application-manifest selects the same members for parse,
dashboard, report and sarif:
npx guardlink dashboard . --application-manifest selected.json -o app-dashboard.htmlA single --since ref is refused for an application, because each member needs
its own base:
--since HEAD: Application comparison requires per-member base revisions in the selected manifest; a single repository --since ref cannot describe the application.An agent gets the same view, read-only, from the
guardlink_application_view
MCP tool. GuardLink’s
application view notes
cover the receipt fields and the consumer manifest format.
Wire it into CI
Section titled “Wire it into CI”The pattern the tool suggests, and the one the counters are built for:
# in each service repository, on merge to the default branchnpx guardlink validate . # add --workspace where sibling checkouts are presentnpx guardlink report . --format json -o guardlink-report.json # publish this artifact
# in the workspace repository, on a schedulenpx guardlink merge reports/*.json -w payments \ --json merged.json --diff-against last-week.jsonKeep each service’s own gate as it is. The workspace pass answers a different question, and a service team should not have its build broken by a sibling’s annotations.
Both halves ship as workflow files you can copy rather than transcribe:
examples/ci/per-repo-report.yml
goes in each service repository, and
examples/ci/workspace-merge.yml
goes in the one that publishes the dashboard.
Their README
covers the personal access token the merge job needs to read artifacts across
repositories.
Related
Section titled “Related”- Annotate an existing codebase builds the per-repo model this assembles.
- The threat model as an artifact
covers the report schema and what
mergewarns about across versions. guardlink link-project,guardlink mergeandguardlink application-viewdocument every flag.

