Skip to content

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.

  • GuardLink installed. See Install GuardLink.
  • Two repositories you can commit to. This page uses gateway and billing.
  • Each one initialised with guardlink init, and annotated. Run guardlink init in each repository yourself: link-project writes .guardlink/workspace.yaml and agent instruction files, not a model. In the run below it labelled both repositories auto-initialized (no prior guardlink setup) even though guardlink init had already run in each.

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.

  1. Point link-project at the repositories and name the workspace.

    Terminal window
    npx guardlink link-project gateway billing -w payments
    Linking 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 repo
    2. Add "guardlink report --format json -o guardlink-report.json" to each repo's CI
    3. Use "guardlink merge" to combine reports into a unified dashboard
  2. Read what it wrote. Each repository gets its own copy, naming itself and its siblings:

    gateway/.guardlink/workspace.yaml
    workspace: payments
    this_repo: gateway
    repos:
    - name: gateway
    - name: billing

    this_repo is 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:

Terminal window
npx guardlink link-project --workspace shop --member frontend=./web --member accounts=./auth
npx guardlink link-project --add ./billing-svc --name payments --from ./web
billing-svc/.guardlink/workspace.yaml
workspace: shop
this_repo: payments
repos:
- name: frontend
- name: accounts
- name: payments

An existing workspace.yaml keeps the names it stores.

A reference to another member’s definition is the plain #id that member declares. Billing declares its ledger in its own definitions file:

billing/.guardlink/definitions.ts
// @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:

gateway/.guardlink/annotations/src/routes.js.gal
@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:

billing/.guardlink/annotations/src/ledger.js.gal
@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:

Terminal window
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.

Each repository publishes a JSON report. In CI that is a step; here it is one command each.

  1. 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)
  2. Merge them.

    Terminal window
    npx guardlink merge gateway/guardlink-report.json billing/guardlink-report.json -w payments --summary-only
    Merging 2 report(s)...
    ✓ payments — 2/2 repos loaded
    7 annotations | 2 assets | 1 threats | 1 controls
    1 mitigations | 1 exposures | 1 unmitigated
    0 confirmed | 1 flows | 2 refs resolved | 0 unresolved
    0 unreadable annotation(s) (0 error(s))
    ⚠ Tag "#claude-code" defined in gateway (owner) and also in: billing

    Truncated after the console summary. --summary-only then 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.

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:

Terminal window
npx guardlink estate merged.json
payments — 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 proxying

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

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

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

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:

selected.json
{
"schema": "guardlink.application-manifest/v1",
"name": "payments",
"members": [
{ "id": "gateway", "guardlinkIdentity": "gateway", "service": "gateway", "relativePath": "gateway" },
{ "id": "billing", "guardlinkIdentity": "billing", "service": "billing", "relativePath": "billing" }
]
}
Terminal window
npx guardlink application-view . --manifest selected.json > view.json

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

Terminal window
npx guardlink dashboard . --application-manifest selected.json -o app-dashboard.html

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

The pattern the tool suggests, and the one the counters are built for:

Terminal window
# in each service repository, on merge to the default branch
npx guardlink validate . # add --workspace where sibling checkouts are present
npx guardlink report . --format json -o guardlink-report.json # publish this artifact
# in the workspace repository, on a schedule
npx guardlink merge reports/*.json -w payments \
--json merged.json --diff-against last-week.json

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