Riftmap Blog

Cross-repo blast radius in nine public platform orgs: the most depended-on repo at Grafana isn't Grafana

Daniel Westgaard — Tue, 14 Jul 2026 00:00:00 GMT

Spend a week on call for a platform team and you will meet the same outage twice. Someone bumps a base image, retags a shared Terraform module, edits a CI template that forty pipelines include. The PR is green. The repo it lives in is fine. Something two repositories away falls over an hour later, and the person who shipped the change had no way to know that repository existed, because nothing in the repo they were editing points outward to the things that depend on it.

I wanted to know how common that shape really is, so I stopped guessing and measured it. Across nine public platform and infrastructure organisations and 1,297 active repositories, roughly one in four repos is a dependency of at least one sibling repo in the same organisation, and that edge is invisible from inside the repo you are changing.

I should say the obvious thing first. I build Riftmap, and Riftmap is the scanner I used. That is a conflict of interest, so this post is written so you can check me rather than trust me. The sample rule is stated before the results. The confidence model is stated, including what it throws away and why. The two false positives my own tool produced are in here, named, with the mechanism. The one organisation that did not fit the finding is in here too, along with the spot-check I ran to make sure the result was not a bug in my own parser. The raw edge list is published. If any of it is wrong, it is wrong in public.

What I scanned, and what counts as an edge

I scanned nine public GitHub organisations in the platform and cloud-native space and parsed the dependency edges their manifests actually declare. The sample: cloudposse, prometheus, open-telemetry, fluxcd, argoproj, ansible-collections, crossplane-contrib, terraform-aws-modules, and grafana.

The rule, fixed before I looked at any result: public organisations in the platform, infrastructure, or cloud-native space, chosen to span three shapes rather than one. Module farms that exist to publish reusable components (cloudposse, ansible-collections, terraform-aws-modules, crossplane-contrib). Frameworks (fluxcd, open-telemetry). Product organisations that ship a thing (prometheus, argoproj, grafana). They range from 28 to 583 active repositories. I picked them for ecosystem and shape spread, not because I knew what they would look like.

The important word is parsed, not inferred. For every repo I read the edges declared in real manifest constructs. Terraform source blocks, including registry coordinates like terraform-aws-modules/vpc/aws. go.mod requires and replaces. Helm Chart.yaml dependencies. Dockerfile FROM lines. kustomization.yaml resources. GitHub Actions uses: references. npm package dependencies. Each reference is then resolved to the repo in the same organisation that actually produces it, so a Terraform source or a FROM becomes a real repo-to-repo edge rather than a string. This is not name-matching and it is not embeddings. It is the graph the repositories already describe about themselves.

Every edge carries a confidence score, and the score is a statement about how much resolution the edge needed, not a probability that a model assigned to it. A GitHub Actions uses: grafana/shared-workflows/actions/... reference has the organisation and the repository sitting in the string. There is nothing to resolve, so there is nothing to get wrong. A package coordinate is one step removed. A go.mod require, an npm package name, a Terraform registry source all have to be resolved to the repository that publishes them, which is deterministic but not free. A bare git URL sitting in a shell script or a README is a text signal rather than a declared dependency, so it scores 0.6 and never gets counted. Open-telemetry is the clearest illustration of what that bar throws away: 413 of its candidate edges were dropped, and 412 of them were bare git URL references.

Across the nine organisations the confidence bar discarded 1,698 of 4,843 candidate edges, 35% of everything the scanner saw. Every number below is computed on what survived, at confidence 0.8 or above, with archived repositories excluded, deduplicated to distinct repo-to-repo pairs, and counting direct dependents only.

One integrity check before the results, because it is cheap and it is the first thing I would ask. Every organisation's scanned repo count matched GitHub's live public_repos count. Grafana came back 586 of 586 with zero errors, of which 583 are active once the archived ones come out. No self-loops, and no workspace: or file: local-protocol residue leaking in as fake edges.

The most depended-on repo at Grafana isn't Grafana

Grafana is the largest organisation in the sample, 583 active repos. Here is its top ten by direct dependents, with the manifest construct each count came from, so you can see for yourself which rows have room to be wrong.

#	Repo	Direct dependents	What it is	Edge basis
1	`grafana/shared-workflows`	188	CI workflow definitions	Actions `uses:`, org and repo in the string
2	`grafana/scenes`	143	frontend framework	npm `@grafana/scenes`
3	`grafana/grafana`	92	the product	npm `@grafana/*` and `go.mod`
4	`grafana/plugin-tools`	83	plugin scaffolding	npm `@grafana/plugin-tools`
5	`grafana/pyroscope-go`	75	profiling SDK	`go.mod` require
6	`grafana/otel-profiling-go`	72	profiling bridge	`go.mod` require
7	`grafana/plugin-ci-workflows`	63	CI workflow definitions	Actions `uses:`
8	`grafana/grafana-plugin-sdk-go`	60	plugin SDK	`go.mod` require
9	`grafana/plugin-actions`	53	GitHub Actions	Actions `uses:`
10	`grafana/k6`	39	load testing	first-party product

The single most load-bearing repository in Grafana's organisation is a repo of CI workflow definitions, with 188 repos importing it. The flagship product is third, at 92. Three of the top ten are CI plumbing.

I want to be precise about why the top row is worth trusting more than the rest of the post. shared-workflows is consumed through uses: grafana/shared-workflows/actions/.... The organisation and the repository are literally in the string. There is no name resolution to get wrong, no upstream package to collide with, no heuristic anywhere in the path. It is the least ambiguous edge type there is, and it produced the largest hub in the sample.

Those ten repos also absorb 868 of the 1,596 cross-repo dependency edges inside Grafana's organisation, 54% of the coupling in an org of 583 repositories. The load is not spread evenly. It never is.

The hub is never the repo you would nominate

Ask a platform engineer which repo in their organisation is the scariest to change and they will name a service. Something with traffic. Something with a runbook.

In eight of the nine organisations I scanned, the most-depended-on repo is plumbing. grafana/shared-workflows, CI definitions, 188 dependents. cloudposse/terraform-null-label, a module whose entire job is generating consistent names and tags, 146. ansible-collections/ansible.netcommon, network utilities, 27. crossplane-contrib/provider-workflows, CI definitions again, 23. prometheus/common and prometheus/client_model, shared Go libraries and protobuf definitions, tied at 23, with procfs one behind them. fluxcd/pkg, a shared Go package, 16. open-telemetry/shared-workflows, CI definitions, 15. argoproj/pkg, a shared Go package, 4.

None of these are services. They are the naming module, the base image, the internal action, the shared utility package. They are also, and this is the part that matters operationally, exactly the repositories that nobody remembers owning. The blast radius concentrates in the things that were set up once, years ago, by an engineer who has since moved teams or left the company. The dependency that used to live only in someone's head is the same dependency that turns out to have 188 repos riding on it.

The ninth organisation, and the check I ran on my own parser

Terraform-aws-modules is the one organisation in the sample with no hub at all. Its busiest repos top out at two direct dependents apiece — a three-way tie between terraform-aws-lambda, terraform-aws-acm and terraform-aws-kms, which is another way of saying there is no hub. The entire organisation contains eleven same-org edges.

That is precisely the result you should be suspicious of, because it is also what a broken parser looks like. Modules in that org reference each other through registry coordinates, source = "terraform-aws-modules/alb/aws" rather than a git URL, and if my resolver quietly failed to follow registry coordinates back to the repository that publishes them, I would produce a near-empty graph and then write a confident paragraph explaining what it meant.

So I checked it against ground truth before I believed it. terraform-aws-atlantis/main.tf calls four sibling modules by registry source: terraform-aws-modules/alb/aws at 10.2.0, acm/aws at 6.1.1, ecs/aws at 6.7.0, and efs/aws at 2.0.0. Riftmap's graph contains all four, with the versions matching. The resolver follows registry coordinates. The sparsity is real.

The reason for it is dull and true. Most of the modules in that organisation are leaves. vpc, s3 and iam do not compose siblings, they compose AWS resources. Only the composers do, atlantis, eks, route53, notify-slack, and there are not many of them. So terraform-aws-modules is neither support nor counterexample for the hub finding. It is an organisation with no hub to find. I am telling you that rather than dropping it, because dropping the org that does not fit is how you end up with a finding that is not true.

One in four repos is load-bearing, and that is a floor

Across the sample, 320 of 1,297 active repositories are a dependency of at least one sibling in the same organisation. That is 24.7%, roughly one in four.

It holds three ways. Pooled across all repos it is 24.7%. The median organisation is 25.3%. The mean organisation is 24.8%. Drop the two largest organisations, grafana and cloudposse, which together are 64% of the sample, and the remaining seven still come to 20.5%. Grafana, the largest org in the sample, sits at 27.8%, above pooled, so this is not an artefact of small organisations either.

Here is every organisation, so you can do your own arithmetic on it.

Organisation	Shape	Active repos	Load-bearing	%	Busiest repo	Direct dependents	Largest SCC
grafana	product	583	162	27.8%	`shared-workflows`	188	53
cloudposse	module farm	241	61	25.3%	`terraform-null-label`	146	1
ansible-collections	module farm	137	26	19.0%	`ansible.netcommon`	27	1
crossplane-contrib	contrib farm	86	4	4.7%	`provider-workflows`	23	1
open-telemetry	framework	80	19	23.8%	`shared-workflows`	15	6
terraform-aws-modules	module farm	59	8	13.6%	`terraform-aws-lambda`	2	1
prometheus	product and libraries	51	17	33.3%	`common` / `client_model`	23	2
fluxcd	framework	32	15	46.9%	`pkg`	16	2
argoproj	product	28	8	28.6%	`pkg`	4	1
Pooled		1,297	320	24.7%	`grafana/shared-workflows`	188

One thing not to do with that table: do not average the percentages by shape. Two of the four module farms carry known measurement gaps. Crossplane-contrib's real hub lives in a different organisation, and terraform-aws-modules has eleven same-org edges in total. A class mean computed on top of two structural undercounts is arithmetic dressed up as a finding, and I would have to take it back the first time somebody actually looked.

What the number is not is stable. The per-org range runs from 4.7% to 46.9%, and anyone telling you a single percentage generalises to your estate is selling something. Treat 24.7% as the shape of the problem, not as an estimate of your number.

Now the objection I would raise if I were reading this. You picked organisations that publish shared modules, so of course their repos depend on each other. Except it runs the other way. Flux (46.9%) and Prometheus (33.3%), neither of which exists to publish reusable modules for siblings, top the table. Cloudposse, 241 Terraform modules built for nothing but reuse, sits at 25.3%, below both. The organisations built around sharing are not the ones that turned out to be most coupled.

And every methodological choice I made pushes the number down, not up. Archived repositories are excluded. The confidence bar dropped 35% of candidate edges before anything was counted. Only direct dependents are counted, not transitive. Only declared manifest edges are counted, which means runtime coupling is completely invisible: shared databases, internal APIs, message topics, none of it appears. Only same-organisation edges are counted, which is why crossplane-contrib reads a suspiciously low 4.7%. Its real hub, crossplane-runtime, lives in the crossplane organisation rather than crossplane-contrib, so a same-org scan structurally cannot see it. The organisational boundary is an accident of GitHub, and the dependency does not care.

Every choice makes the number smaller. It is still one in four.

Two false positives I had to throw out

Two entries in my first Grafana top ten were wrong, and both were wrong the same way. A fork that preserves the upstream package identity will absorb every same-org import of the upstream. That is the failure mode, stated up front, because it bites hardest on exactly the repos that look most important, and because if you are building this yourself you have the bug until you prove you do not.

grafana/opentelemetry-go came out at number two with 182 dependents. It is Grafana's fork of upstream OpenTelemetry Go, and a fork keeps the upstream module path, go.opentelemetry.io/otel. So when Grafana repos put a plain go.mod require on upstream otel at v1.43 and v1.44, the resolver matched that module path to the repo in the organisation that declares it, which is the fork. The repo carried 184 inbound edges from 182 distinct repositories. Exactly one of those edges was a genuine replace directive pointing at the fork. The other 183 were repos importing upstream and being told they depended on a sibling.

grafana/k6-DefinitelyTyped, number four at 137, is the same bug in npm. It is a fork of DefinitelyTyped, so it declares @types/lodash, @types/react, @types/jest and several hundred more. Every TypeScript repo at Grafana with @types/* in its devDependencies got an edge to it. That is not a hub. That is a fork of the type registry collecting an edge from everything that has ever installed types.

Both are resolver bugs in my own product and both are now filed.

Neither one touched the headline. shared-workflows is an Actions path, which is why I lead with it. Removing both leaves the pooled figure unchanged at 24.7%, takes Grafana's load-bearing count from 163 to 162, and moves grafana/grafana from fifth to third, which is a better story than the one I started with. In the other eight organisations the busiest repo is a first-party project with no upstream twin to collide with, so the bug had nowhere to bite.

I found this because I went looking for it. If I had not, the number two entry in my headline table would have been an artefact, and the first Grafana engineer to read the post would have said so.

Why I report direct dependents and not transitive

The first version of this analysis reported transitive blast radius, and the numbers were nonsense in a way that took me a while to see. Ninety-one repos in Grafana's organisation, more than half of everything I had counted as load-bearing, each came back with roughly the same figure. About 315 transitive dependents. Ninety-one different repositories, one answer.

That is not a distribution, it is a fixed point, and it has an obvious cause once you go looking for one. Grafana's Go repositories form a 53-repo strongly connected component. Alloy, Beyla, augurs, dataplane, Grafana core, the AWS and Azure SDK families, they all mutually import. Inside a strongly connected component every member reaches every other member, so reverse reachability collapses to roughly the same value for all of them, and a "transitive blast radius" stops measuring the repo and starts measuring the mesh. Removing the two forked repos above only took that component from 55 repos to 53, so the mesh is real and not an artefact of my own bug.

It splits cleanly by ecosystem. The Terraform and Ansible organisations are acyclic, largest strongly connected component of size 1. The Go organisations cycle: grafana 53, open-telemetry 6, prometheus 2, fluxcd 2. Terraform module graphs cannot contain import cycles. Go module graphs across sibling repositories very much can.

So I report direct dependents only. A transitive count would overstate blast radius in a Go mesh, and I would rather publish a smaller number I can defend than a bigger one I cannot.

A repository declares what it depends on, never what depends on it

Every manifest points outward. go.mod lists what this repo imports. Chart.yaml lists what this chart pulls in. The Dockerfile names the base image it starts from. Not one of them lists the repos on the other side of the arrow, because that half of every edge only exists at the organisation level. So no amount of looking inside a single repo, however good the linter or the agent, reconstructs it. This is structural. It is not a tooling gap that someone forgot to close.

A hand-maintained catalogue does not close it either, and this scan is a concrete demonstration of why. Nobody was ever going to file a catalogue entry for a CI workflow file. shared-workflows is not a service, it has no owner in anybody's mental model, and it accumulated 188 dependents without a single person deciding it was important enough to write down. A catalogue is only ever as accurate as the last engineer who remembered to update it, and the repos with the largest blast radius are precisely the ones nobody remembers. Parsed, never catalogued, is the only version of this that survives contact with a real estate.

Symbol graphs do not close it either, and I want to be fair here, because they are genuinely excellent at what they do. Sourcegraph indexes programming-language symbols across repositories, which is a real and hard thing to get right, and it answers "where is this function used" better than anything else. GitLab Orbit is the most serious thing to arrive in this space, a properly resourced property graph of the whole SDLC, and it is validating rather than threatening to see GitLab build it. But a Terraform module resolving to a repo, a base image built by another repo, a Helm value feeding a downstream chart, a GitHub Actions workflow imported by 188 repositories, those are artifact edges. They do not live in the symbol layer and they do not live in the SDLC metadata layer. Symbol graphs and artifact graphs are different categories, and everything above is entirely in the artifact layer. The 188 that started this post is an Actions uses: reference, which no symbol indexer has any reason to model.

Give an agent every repo in your organisation and you have solved access. You have not given it the map of which repos hold each other up. Those are different gifts, and the second one is the one that pages you at 2am.

What this is not

This is public open-source data, and it is public because it is the only data I can show my work on. I cannot publish a scan of a bank.

So be careful about the transfer. Cloudposse is a module vendor. Grafana is largely a plugin ecosystem. Neither is your enterprise polyrepo, and the 24.7% is not an estimate of your organisation. What does transfer is the mechanism, because the mechanism has nothing to do with whether your code is public. A repository declares what it imports and never what imports it. That is true of your private GitLab estate for exactly the same reason it is true of Grafana's.

Which means the honest conclusion is not a number. It is that you cannot know your number without looking, and almost nobody has looked.

Where this leaves you

If you operate more than about fifty repositories, the organisation-level dependency graph is not a nice-to-have visualisation. It is the missing half of every shared-component change you make. Before you bump that base image or retag that module, the question "which repos break" has a real answer, and it is very probably not the one in your head, because the answer is a CI workflow file that somebody set up in 2022 and nobody has thought about since.

That is the problem Riftmap exists to make boring. It scans a whole GitHub or GitLab organisation with one read-only token, parses the artifact edges, and answers the blast-radius question directly, for you and for the agents you point at your code. The data in this post came out of exactly that scan, bugs included. The raw edge list is here, together with a script that recomputes every number in the post from it. A live, clickable Grafana graph is planned and on the way; until it lands, you can poke a real one — the Cloud Posse org, where a single naming module holds up 146 of its repos.

About Riftmap

Riftmap maps cross-repo dependencies across your entire GitLab or GitHub organisation — Terraform, Docker, CI templates, Helm, and more. One read-only token. No YAML to maintain.

Frequently asked

What percentage of repos are shared dependencies in a typical organisation? In a scan of nine public platform organisations covering 1,297 active repositories, 320 repos, or 24.7%, were a dependency of at least one sibling repo in the same organisation. The per-org range was wide, from 4.7% to 46.9%, so treat it as the shape of the problem rather than an estimate of your own organisation. Every methodological choice in the scan biases the figure downward, including a confidence bar that discarded 35% of candidate edges before anything was counted, so 24.7% is a floor.

How do I find every repo that consumes a shared Terraform module? You cannot find it from the module's own repository, because a repo declares what it imports and never what imports it. You need the organisation-level dependency graph: parse the Terraform source blocks across every repo in the org, including registry coordinates like terraform-aws-modules/vpc/aws, and resolve each one to the repo that produces it. In the scan above, cloudposse/terraform-null-label turned out to have 146 direct consumers this way.

Can an AI coding agent see the blast radius of a cross-repo change? Not from a single repository's checkout. The edges that make a shared change risky are inbound cross-repo edges, and those do not exist anywhere inside the repo being edited. An agent needs an organisation-level artifact dependency graph served to it as a tool call to answer "what breaks if I change this".

Why not infer cross-repo dependencies from repo names or code search? Because the failure modes are subtle and they bite hardest on exactly the repos that look most important. In this scan, two of Grafana's apparent top hubs, grafana/opentelemetry-go and grafana/k6-DefinitelyTyped, were forks that preserved the upstream package identity, so they absorbed every same-org import of the upstream package. Parsing declared manifest edges and resolving them to a producing repo is what makes a count trustworthy, and even then you have to audit the hubs.

Which AI coding assistants can see blast radius before they change code?

Daniel Westgaard — Mon, 13 Jul 2026 00:00:00 GMT

I keep hitting the same moment, and if you run more than a handful of repositories you probably do too.

Claude Code is open in the platform repo. Cursor is open in a service two directories over. The base image both of them build on top of just shipped a CVE fix, so I want to bump the FROM line. Or a Terraform module half the stacks pull in through a source block needs one variable tightened. The edit itself is thirty seconds of work. The question that decides whether I make it before lunch or spend the afternoon in an incident channel is the one neither window will answer on its own: who else breaks.

So I went and checked what each of the assistants I actually drive can do about that question today. The honest finding is worth stating flat, because it is easy to lift and easy to misread.

As of July 2026, none of the three mainstream AI coding assistants, not Claude Code, not Cursor, not GitHub Copilot, resolves the cross-repo blast radius of a change, deterministically, completely, org-wide, on its own. The reason is not model quality, and it is not a feature any of them forgot to ship. The dependency edge that breaks the other repo was declared in a manifest none of them resolved into a graph, often in a repo the assistant never took in at all. Each of the three can answer the question. But only once you hand it a parsed dependency graph to query.

That is the whole post. The rest is why, and what "hand it a graph" actually means.

The question hides a conflation

The question "which assistant sees blast radius" smuggles in an assumption, and the assumption is the whole game: that an assistant which can see your repositories therefore knows how they depend on each other. Those are two different things, and the gap between them is where every one of these tools stops.

Access is not structure. Claude Code can read every file in seven repos you granted it and still not hold a single edge between them. A text match is not a resolved edge. Cursor can grep those repos and land on a FROM or a source line, and still not resolve it to the repo that produces the module, or walk the chain past the first hop. A curated context set is not a parsed graph. Copilot Spaces can hold exactly the repositories a task needs, but only if you already knew which ones to add.

The edge you actually care about is a specific, boring, declared thing. A Dockerfile FROM line in a downstream service. A go.mod require pinning a consumer to your module. A Terraform source block, a Helm value reference, a GitLab CI include. It was written down, in a manifest, in a repo. Just not the repo you happen to have open. The set of repositories on the far side of those edges is the blast radius of the change, and when an AI agent is the one making the change fast, that is AI-agent blast radius. It is exactly what a single repo's clone cannot show.

What each assistant can actually see today

Claude Code, Cursor, and GitHub Copilot have each shipped a real multi-repo capability in 2026, and being precise about what each one is matters, because they are three genuinely different mechanisms and none of them is a dependency graph. Capabilities in this space move fast, so treat everything below as re-checked on 13 July 2026 against each vendor's own current docs and roughly three months of changelog.

Claude Code: access, by design

Claude Code's cross-repo mechanism is directory access, and it is built to reach a dependency graph from somewhere else rather than construct one itself. The --add-dir flag grants Claude read and write access to directories outside the one it started in, and permissions.additionalDirectories makes that grant persistent. The /add-dir command does the same from inside a running session. Anthropic's own large-codebase guidance documents the cross-repo move under Grant access across packages or repositories: when a task spans multiple checkouts, you extend --add-dir or additionalDirectories to a separately-checked-out repository. All of it is genuinely useful. Point Claude Code at all seven repos and it can read and edit across them in one session.

What it gives you is access, and access is not the same as the answer. At a handful of repos the difference barely bites: grant Claude all of them and you can work out by hand which one breaks when you bump the base image, because the breaking edge is a real line in a real file, the FROM in a downstream service's Dockerfile, and once you have added that directory Claude can read it. The difference bites at scale. At an organisation's real size the repo on the far end of the edge is one you never added. Reconstructing the transitive closure across every manifest in the org, on demand, is the parser's deterministic job, not something the model does reliably or unprompted. Claude Code is the tool in this comparison best positioned to call an external dependency graph, and it is built to reach one: it connects to external services over MCP by design, and Anthropic's own guidance is to offload heavy search to an index exposed that way rather than read everything itself. That guidance names a search index, not a dependency graph, and the two are different objects. The architectural move is the same one, though, and a parsed dependency graph is exactly the kind of external service Claude Code is built to call. It is a consumer of the graph, not a rival to it.

Cursor: the agent can chase the chain, not resolve it

Cursor's agent can attempt the cross-repo chain-walk itself, and being precise about how is what keeps this fair. Alongside the embeddings, Cursor ships Instant Grep, which its docs describe as a custom search engine that "outperforms ripgrep on large codebases," and the agent reaches for grep automatically when you reference a specific symbol. A declared dependency is a literal string, FROM myorg/base-image or source = "cloudposse/ssm-parameter-store/aws", and grep finds literal strings, so Cursor really can surface a FROM or a source line. With a model in the loop it can go further than a bare grep. It can map the Registry shorthand cloudposse/ssm-parameter-store/aws to the repository terraform-aws-ssm-parameter-store, because the model knows the Terraform Registry's terraform-<provider>-<name> convention, then grep for that repository and chain outward a hop at a time. For a coordinated edit across a frontend, a backend, and a shared library I already know are related, I use it and it is good.

Concede the whole of that. The agent can attempt the chain-walk. The line is not whether it can try, it is what the attempt is. Chaining greps with a model resolving each shorthand by convention is inference. Partial, non-deterministic, bounded to the repositories you added to the workspace, and an expensive multi-grep crawl that gets shakier every hop, this chain running six hops deep and fanning out into several repositories along the way. The model might resolve the shorthand correctly. It might miss the second literal form of the same edge, the explicit git:: URL written elsewhere in the org. It might stop at hop three. One resolved query against a graph that already parsed and resolved every edge is right by construction, complete, and org-wide. The model might get it right. A parsed graph is right.

GitHub Copilot: a context set you assemble by hand

GitHub Copilot reaches across repositories through a curated context set and a cloud agent, and each stops short of a dependency graph for the same underlying reason. Copilot Spaces let you assemble a set that can hold whole repositories alongside files, issues, PRs, and free-text notes, and share it across the org. GitHub's docs describe a Space's sources as "automatically updated as they change, making Copilot an evergreen expert in your project," which is a real strength: the set stays fresh without anyone re-uploading. The Copilot cloud agent, renamed from Copilot coding agent in GitHub's own changelog on 1 April 2026, will pick up a task and open a pull request for you.

Each has a real edge and the same wall. A Space is only ever as good as its curation, because you assemble it by hand: it holds exactly the repositories you decided to add. The cloud agent is scoped tighter still. GitHub's own documentation is blunt about the limit: Copilot "cannot make changes across multiple repositories in one run," works one branch at a time, and opens exactly one pull request per task. You can widen what it reads by naming sibling repositories, and I have written up how to wire that. But it reads the repositories you point it at, and no mechanism here tells you which those are.

The comparison, in one table

Put Claude Code, Cursor, and GitHub Copilot side by side on the one axis that matters here, cross-repo blast radius, and the pattern is not three different amounts of the same capability. It is three tools solving access and reasoning, and a fourth kind of thing solving structure. The last row is not a competing assistant. It is the parsed graph the other three can call.

	How it reaches across repos	What that answers well	What it structurally cannot resolve
Claude Code	Directory access: `--add-dir`, `/add-dir`, or `permissions.additionalDirectories`. You grant it the clones.	Reading and editing across every repo you have checked out, in one session.	Which of those repos breaks if a shared manifest edge changes, and which repo to add in the first place.
Cursor	Instant Grep and an embeddings index across the folders in a multi-root workspace.	Finding a declared line or a semantically related chunk across the folders you added.	The agent can infer the chain hop by hop, but that stays non-deterministic and bounded to the workspace, never a resolved, deduplicated graph.
GitHub Copilot	A curated Copilot Space and a cloud agent scoped to one repo per task.	Answering over a context set you assembled by hand.	Which repositories to put in that set. The cloud agent touches one repo and opens one PR.
A parsed artifact graph (e.g. Riftmap)	Parses the declared manifest edges across the whole org from one read-only token. No clone needed.	Which repositories transitively depend on a given repo, returned before you touch it.	Which function or CI job inside a downstream repo breaks. It resolves repositories, not symbols.

Read down the last column. Every "cannot" in the first three rows is the same shape: an edge whose far end is in a repo the tool never took in, or never resolved past the string. Read the last row's "cannot" and it is a different shape entirely. A real limit, but a limit of resolution, repositories rather than functions, not a limit of reach.

Why none of them can resolve it

None of Claude Code, Cursor, or GitHub Copilot resolves cross-repo blast radius on its own, and the reason is structural. Two walls stand in the way, and each of the three hits both. The first is resolution. Reading a repo is not resolving its edges. An edge only enters a graph when something parses the manifest that declares it and resolves the shorthand back to the producing repository. Cursor's agent can chain greps and walk the composition outward, which is real, but a chain-walk is inference, partial, non-deterministic, stopping wherever the crawl runs out. None of the three parses and resolves on its own.

The second wall is reach, and it is where every cross-repo mechanism the three ship bottoms out. Granting Claude Code the clones. Adding folders to a Cursor workspace. Curating a Copilot Space. Configuring one of Cursor's new cloud multi-repo environments. Fanning Copilot tasks across repositories over the new agent-tasks API. Each terminates in a list of repositories a human chose, and choosing that list is the blast-radius question itself. The agent can try to extend that list by discovery, grepping outward and cloning what it finds. But discovery is bounded to what the agent already reached, it is non-deterministic, and it cannot add the repo that breaks until it already knows it breaks. That last constraint is the resolution wall in the reach wall's clothing, and it is the thing you were trying to find out.

This is why "just use a bigger context window" and "just embed everything" do not close the gap. Embeddings retrieve by resemblance, and a declared dependency is not a resemblance; that is the argument I make at length in inferred context is not a dependency graph. Symbol graphs, the Sourcegraph-style index of where a function is defined and called, are genuinely excellent and also the wrong layer here: they resolve code symbols, not the infrastructure edges declared in Terraform, Docker, Helm, and CI, which is a different category of graph entirely. And this is not a hypothetical failure mode. It is the mechanism behind a measurable rise in change-failure rate as AI-accelerated changes outrun anyone's ability to see their consequences, which I have written up with the 2026 data.

One honest caveat, because a sharp reader will have it ready. Step one category over from the daily-driver assistants and a tool did ship real cross-repo awareness on this exact layer: Qodo's Cross Repo Review, announced in June 2026. It is not a lightweight player and I want to be fair to it. Its docs define a relationship type where, in their words, "One repository depends on a build artifact, container image, or pipeline output produced by the other." That is the artifact layer, named explicitly. Qodo reaches it, it is well funded, and it belongs in this conversation. And it is worth being precise about how Qodo comes to know those relationships: its docs say a relationship can be discovered automatically or defined by hand, which puts it across inferred and registered both, not one clean regime. The line I draw is not capability, it is mechanism and moment. Where a relationship feeds the impact call, Qodo's docs disclose the mechanism: "The agent reads the related repositories and traces the impact in both directions: code that depends on the change, and code in the PR that may conflict with the other repository." That is an LLM tracing at review time, which is inference, not a deterministic parser resolving a declared source = edge the build already executes. And the moment is the other half. Qodo acts on pull requests already opened, and "By default, Qodo targets the main branch of each connected repository," not at the point a developer is deciding what to change in an interactive session. Qodo does not break the argument here. It sharpens it. Hand a tool the cross-repo relationships and it will reason over them. The whole question is where those relationships come from and how they are resolved.

What changes the answer: hand it the graph

What changes the answer is not a smarter assistant but a parsed dependency graph the assistant can query, and the effect is the same for all three. Here is the shape of it, with a receipt from a real scan rather than an adjective.

Take one repository an assistant might plausibly have open. Cloud Posse's terraform-aws-ssm-parameter-store, a thin wrapper around AWS SSM Parameter Store, the kind of small shared module nobody thinks about until it changes. On its own, any of the three sees one repo. Point a parsed cross-repo graph at the same repo and ask what depends on it, and the answer comes back as a set of repositories.

# 1. resolve the one repo the assistant already has
curl -s -H "X-API-Key: $RIFTMAP_API_KEY" \
  "https://api.riftmap.dev/api/v1/repositories/lookup?url=https://github.com/cloudposse/terraform-aws-ssm-parameter-store"
# → { "id": "54052e08-b43f-4b67-975b-d869e9cdc62a", ... }

# 2. ask the graph what transitively depends on it
curl -s -H "X-API-Key: $RIFTMAP_API_KEY" \
  "https://api.riftmap.dev/api/v1/repositories/54052e08-b43f-4b67-975b-d869e9cdc62a/impact"
# → { "total_affected": 22, "max_depth_reached": 6, ... }

As scanned on 7 July 2026, terraform-aws-ssm-parameter-store sits upstream of 22 other repositories inside the same Cloud Posse GitHub org, reached across six hops of Terraform module composition. Every edge on the path is a Terraform source = reference, parsed out of the manifest and resolved back to the repository that produces the module, never a go.mod or package.json require. The chain is legible if you walk it. The source in terraform-aws-iam-system-user, at main.tf line 63, points back at the parameter-store module. That module is pulled in by iam-s3-user, which is pulled in by s3-bucket, then s3-log-storage, then lb-s3-bucket, and six hops out you reach the org's load-balancer modules: terraform-aws-alb, terraform-aws-nlb, and terraform-aws-elastic-beanstalk-environment. None of those load balancers names the parameter-store module anywhere in its own files. The edge is real, declared, and six hops removed from anything a human editing that module would think to grep for.

That is the number none of the three produces on its own, and the one all three can retrieve in a single call once the graph exists. Two things keep it honest. The call is repo-level, so it tells you which repositories are downstream, not which function or job inside them; for the pre-change question, which repos do I need to think about, that is exactly the resolution you want. And the 22 is a transitive closure, not 22 breaks at once.

The reason is the pin, and there is a further distinction hiding in it. Cloud Posse pins every one of these edges, this chain's first hop at 0.13.0, the far-end terraform-aws-alb at 0.19.0, so a bump to the shared module is a migration you schedule, not an outage you wake up to. Each hop propagates only as it bumps its own pin. That pinned case is what this receipt demonstrates. The estate that actually needs this graph is the other one, the source that is a bare git:: URL with no ?ref=, the FROM pinned to :latest, the CI include that tracks main. Those edges do not wait for a coordinated bump. They break on the next apply. And the same graph tells the two apart, because Riftmap carries the version constraint and its pin state on every edge, a version_constraint_state of pinned, floating, or branch. Point Riftmap at your own estate and it splits the affected set in two: the consumers you coordinate an upgrade across, and the ones that break unannounced. That second set is the afternoon in an incident channel this post opened on. That split is Riftmap's to make and hard for the others to reach. Grep finds the string but not the pin semantics behind it. An agent chain-walk has to read and correctly interpret a version constraint at every single hop. Qodo's LLM traces the impact at review time and never reads the pin semantics that decide which case an edge is in.

What 22 gives you is the set you must consider and coordinate a fix across, which for the kind of shared-module change that opened this post is exactly the right set, four of them direct dependents and the rest transitive, the chain necking through one repository mid-way before it fans out to the load balancers. And 22 is the count inside the one org Riftmap has connected here, the 242-repo Cloud Posse org. Anyone vendoring these modules into their own private infrastructure is invisible to that scan, so the honest figure is at least 22, not exactly 22. The assistant, meanwhile, is only ever one caller of that graph: when I am the one bumping the module, those same two calls run from my own terminal, no agent in the loop at all.

It matters that the graph is parsed rather than guessed, and the confidence floor is where that shows. In the depth-six graph around this module there are 254 edges, and 79 of them sit below the default 0.8 confidence floor and are excluded from the answer. Every one of those 79 is a git_url_reference, a heuristic text match at confidence 0.6 to 0.7, a script mentioning a repo URL in passing rather than a manifest declaring a dependency. The eight edges on the spine all resolve at 0.9, the deterministic score for a Terraform Registry shorthand matched against the Registry's naming convention, the same transform the Cursor agent runs hop by hop, here applied mechanically across the whole org and comfortably above the floor. Parsed, not inferred, is not a slogan here. It is the line between the edge the build actually executes and a string that happened to look like one.

There is no first-party Riftmap MCP server yet, and I would rather say that plainly than dress it up. What exists today is not a workaround, it is the path I actually run. Riftmap publishes an OpenAPI schema, so you point a generic OpenAPI-to-MCP bridge at it and each endpoint becomes a tool the assistant can call, no bespoke server to build. The one thing worth doing is scoping it: the --tag flags below hand the agent only the read-only graph endpoints (the repositories and impact tags — lookup, dependencies, dependents, impact), so it gets the tools it needs to answer "who else breaks" and nothing else, no billing or workspace-admin surface from the rest of the schema. One config block, your key in an X-API-Key header:

{
  "mcpServers": {
    "riftmap": {
      "command": "npx",
      "args": [
        "-y", "@ivotoby/openapi-mcp-server",
        "--tag", "repositories", "--tag", "impact"
      ],
      "env": {
        "OPENAPI_SPEC_PATH": "https://app.riftmap.dev/openapi.json",
        "API_BASE_URL": "https://api.riftmap.dev/api/v1",
        "API_HEADERS": "X-API-Key:${RIFTMAP_API_KEY}"
      }
    }
  }
}

That is the setup I walk through for Claude Code and Cursor, against the endpoints an agent calls. The same graph answers at merge time, not just at planning time, and checking a PR's blast radius as a gate is its own piece, organised by graph layer.

Other parsed graphs an agent can call over MCP already exist. The line Riftmap draws is narrower and, I think, more durable. It is the artifact layer, resolved. Dockerfile FROM, Terraform source, Helm value references, GitLab CI include, each edge followed back to the repository that actually produces the image or the module, and served across an entire GitHub or GitLab org from one read-only, org-level token, not a per-developer index of the repos you happened to clone. The receipt above walks one Terraform source chain; the same parse-and-resolve step runs across the parser suite, so a Dockerfile FROM line, a Helm value reference, or a GitLab CI include resolves back to its producing repository the same deterministic way. That is the layer an assistant structurally cannot rebuild from a single repo's checkout, which is the whole reason the answer to who else breaks was never in the box to begin with.

This is all Riftmap is. It parses the edges your manifests already declare, a dozen ecosystems in all, across an entire GitHub or GitLab org from one read-only token, and serves the graph over an API. It is not a fourth assistant competing with the three. It is the substrate they were always going to have to call. The map of the dependency that used to live only in the head of the engineer who wired that shared module in last time and has since left. If you want that map for your own org rather than Cloud Posse's, that is what Riftmap is for.

The assistant was never the limitation

The race between Claude Code, Cursor, and Copilot is real, and it is a race about access and reasoning, and both of those keep getting better every month. Neither is the thing standing between you and the answer to "who else breaks." The edge that breaks the other repo was declared in a manifest, in a repo none of them opened, and no amount of model improvement puts it back in the box. Give any of the three that parsed graph and all three can answer. The assistant was never the limitation. The missing graph was.

Questions I get asked

Which AI coding assistants can see blast radius before they change code?

As of July 2026, none of the three mainstream assistants resolves cross-repo blast radius on its own: not Claude Code, not Cursor, not GitHub Copilot. Each has a real multi-repo mechanism (directory access, grep plus a semantic index, curated context sets), but none reads and resolves the declared manifest edges that decide which repositories break when a shared base image, module, or CI template changes. Hand one a parsed graph and it can: pointed at Cloud Posse's terraform-aws-ssm-parameter-store, that graph returned 22 downstream repositories across the org, six hops out along Terraform source references resolved back to the producing repo, as scanned on 7 July 2026. The honest answer is whichever assistant you give the graph to.

Are there AI assistants that show blast radius before code changes?

Not among the daily-driver assistants, on their own. The closest is one category over: Qodo's Cross Repo Review, a PR-review feature, has an LLM read the related repositories and trace cross-repo impact on already-opened pull requests, on the main branch by default, which is inference at review time rather than a parsed graph queried at planning time. It reaches the artifact layer, which is real, but through tracing, not a deterministic parser resolving the source = and FROM edges a build already executes. For an interactive assistant to show blast radius before it opens a PR, you point it at a parsed cross-repo graph, and the affected repositories come back before the change is made.

Can Claude Code, Cursor, or Copilot analyse the blast radius of a change on their own?

No. Claude Code sees the directories you grant it, Cursor greps and embeds the folders you added to the workspace, and Copilot reasons over a context set you curate, and none of the three resolves a dependency edge whose far end lives in a repo the tool never took in. The limit is structural, not a matter of model quality: a stronger model reading the same single repo still cannot recover an edge that was declared in a manifest somewhere else. They can all answer the question once you hand them a parsed cross-repo dependency graph to query. On their own, they cannot build one.

How do you give an AI coding assistant cross-repo blast-radius awareness?

You give it a queryable dependency graph, let it resolve the repository it is about to change, and ask which repositories transitively depend on that one. Riftmap builds that graph by parsing the declared edges (Dockerfile FROM, Terraform source, go.mod requires, Helm, CI) across an entire org from one read-only token, and serves it over an HTTP API any assistant can call; there is no first-party MCP server yet, so you point the assistant at the API directly or through a generic OpenAPI-to-MCP bridge pointed at the published schema. Pointed at cloudposse/terraform-aws-ssm-parameter-store, that graph returned 22 repositories across the org that depend on it, six hops out through Terraform source references, as scanned on 7 July 2026.

About Riftmap

Riftmap maps cross-repo dependencies across your entire GitLab or GitHub organisation — Terraform, Docker, CI templates, Helm, and more. One read-only token. No YAML to maintain.

Blast radius in software engineering: what it is, how to measure it, how to contain it

Daniel Westgaard — Wed, 08 Jul 2026 00:00:00 GMT

You change one small shared module. Tests are green. The type-checker is happy. You merge, because everything you can see from inside that repository says the change is safe. Then a pipeline fails in a repo you had forgotten existed, owned by a team you have never spoken to, that pulls your module in through a line nobody remembers writing.

Every engineer who has worked in a multi-repo estate has lived some version of this. The canonical public version is left-pad: eleven lines of JavaScript, unpublished by one author in 2016 and used as a transitive dependency by everything from small projects to major companies including Facebook, Netflix, and Spotify. When it vanished, dependent builds across the ecosystem received 404s and failed, because almost nobody knew how many things quietly depended on it. Left-pad was an unpublish, an availability event rather than a breaking change, but the shape is identical: transitive consumers nobody had counted. The action was trivially safe from where its author stood. The damage happened everywhere else.

That gap has a name now, and the name is doing too much work. Blast radius is not one measurement. It is two, and most of the tooling that promises to measure it only sees the one that stays inside a single checkout.

The word is doing two jobs at once

"Blast radius" quietly conflates two different measurements: the code blast radius your tests, type-checker, and impact-analysis tools already catch inside one repository, and the artifact blast radius that crosses repository boundaries through base images, Terraform source blocks, and the like, which nothing in a single checkout can see.

These two live at different layers and fail in different ways. The code radius is the set of functions, files, and callers inside your repo that your change touches. It is real, and it is largely solved for the static edges. Your test suite runs it. Your language server draws it. A file-level import graph traverses it. If your change breaks something one import away, you find out before you merge.

The artifact radius is the set of other repositories, services, and pipelines wired to the thing you changed through a manifest edge that lives in someone else's repo. From your checkout, that edge is invisible. You cannot grep for it, because the file that references your module is not on your disk. The consuming repo declares the dependency, in its manifest, on its side of the boundary. This is the radius that pages you at 2am, and it is the one your CI never saw.

The reason this matters more every quarter is speed. AI coding agents now make small, plausible, locally-correct cross-repo changes faster than any human reviewer can trace them, and a 2026 Cortex benchmark of engineering leaders reported change failure rates up roughly 30% and incidents per pull request up 23.5% alongside that acceleration. Amazon ran an internal deep-dive in March 2026 into a trend of incidents with, as reported by the Financial Times, "high blast radius", tied in part to novel GenAI usage running ahead of established safeguards. The occasion is new. The blind spot is old.

What blast radius actually is

Blast radius is the total set of things that break, degrade, or need updating when a change ships, measured along a spectrum from the function you edited out to the repositories you have never checked out. It is a system property, not a code property, and the honest definition has to hold the whole spectrum at once.

At the narrow end sits the function: change a signature, and every caller in the file feels it. One step out is the module: the internal package that a dozen files import. One step further is the service: the API other services in your process boundary call. These three all live inside a repository, and inside a repository the graph is legible. You own the code, you own the tests, the edges are on your disk.

The spectrum does not stop at the repo wall. The widest band is the cross-repo artifact edge, where your change reaches a consumer through a construct that neither repository executes together: a Docker FROM line pinning your base image, a Terraform source resolving to your module, a Helm value feeding a downstream chart, a GitLab CI include pulling your pipeline template, a go.mod require on your published package. Same word, same question, radically different visibility. The industry mostly defines blast radius at the layer it can already see, and then stops.

That is the fragmentation you hit if you go looking for the definition today. LOOM's glossary scopes it to "how many functions, classes, and files are affected when a single code element changes". Axiom Refract defines it as the set of files that break when a given file changes, computed by BFS over a file-level import graph. Recursive pushes the other way, all the way out to business impact, features and customers and revenue. SixDegree reaches furthest, into infrastructure, data, and people. Each is correct at its layer. None of the widely-cited ones names the actual cross-repo manifest constructs as the edge. That is the gap this hub exists to fill.

How to measure it

You measure blast radius by building a directed dependency graph and traversing it backwards from the thing you changed, and every method in common use does exactly that up to the repository boundary and then stops. The differences between methods are real and worth walking honestly, because each one genuinely works where it works.

Dependency-graph BFS

The dominant mechanical method, and the one the 2026 tooling wave has converged on, is a breadth-first search over a dependency graph. Nodes are files or symbols, edges are imports or calls, and you traverse the reverse edges out from the changed node: depth 1 is the direct dependents, depth 3 to 5 is the transitive tail. LOOM, Axiom Refract, and Pharaoh all describe this mechanism precisely, and it is the right mechanism. It is deterministic, it is fast, and it answers "what imports this" without guessing.

Its boundary is the graph you built. A file-level or symbol-level import graph is scoped to one parsed codebase. It has no node for the repo across the org that pins your image, because that node was never in the graph. The BFS is only as wide as its inputs, and its inputs stop at the checkout.

Impact-based test selection

A sharper version runs the graph to pick which tests to execute: predict the affected code, run only those tests, skip the rest. When it works it is a genuine accelerator, and for a large single-repo test suite it is worth real money. It answers "which of my tests could this break" with precision.

It inherits the same wall, plus a second one. The affected tests it can select are the tests in the repository it is running in. A consumer in another repo has its own suite, on its own side of the boundary, and your pre-merge run never invokes it. Worse, static selection is demonstrably imprecise for dynamic dispatch and event-driven code even within one language: the runtime edges are exactly the ones static analysis cannot see.

Change-failure-rate, the lagging outcome

DORA's change failure rate is the most-cited blast-radius-adjacent metric, and it is a genuinely useful health number, but it measures something structurally different from the two above. DORA defines it as the ratio of deployments that require immediate intervention following a deployment, a rollback or a hotfix. It is an outcome, aggregated after the fact, across however many deploys you count.

That makes it a lagging measure, not a graph you can consult beforehand. It tells you how often your changes broke something last quarter. It does not tell you which repositories are structurally exposed to the change sitting in your pull request right now. It is a number to drive down, not a map to read before you merge. Conflating the two is a common and expensive mistake: a good CFR trend and a completely unmapped artifact layer coexist happily, right up until they do not. If you want the metric itself, we wrote a practical guide to measuring your change failure rate.

For fact density, none of this changes when you switch ecosystems. Within the open-telemetry GitHub org, 16 other repos declare a go.mod require on go.opentelemetry.io/otel, as of the org's most recent completed scan, 2026-06-28. That edge is a first-class cross-repo dependency, and no single repo's BFS, test selection, or CFR contains it.

The radius you can't see from one repo

The widest band, the cross-repo artifact edge, is invisible from any single checkout by definition, and mapping those edges across an entire estate is its own discipline, cross-repo dependency mapping, which the rest of this post depends on.

This is where the bus-factor problem and the artifact problem turn out to be the same problem. The shared module nobody remembers owning is exactly the one that walked out the door with the engineer who last touched it. The edge is declared in a manifest, so it is still there and still load-bearing, but the knowledge of why it exists left the building. A parsed graph does not care who remembers; the edge is in the file whether or not anyone can still explain it. This is the dependency bus-factor problem stated structurally.

The AI-agent version of this blindness is its own case, because an agent working from one repo's clone structurally cannot see the other side of these edges, which is why AI agents in particular miss the cross-repo radius and why the AI-agent blast radius has become its own conversation. But the agent is the occasion, not the subject. The engineer who owns the estate and holds the pager had this blind spot long before the agents arrived.

How to contain it

Containment means three different things depending on which layer you are standing on, and only one of them is about knowing the graph before the change ships. Getting the reader honestly to the third one means conceding the first two in full, because both are real and neither is what a dependency graph does.

The cloud sense: cell-based architecture and breach containment

If you type blast radius aws into a search box, you almost certainly want fault isolation, and that is a legitimate, mature discipline that has nothing to do with cross-repo dependency graphs. AWS's Well-Architected guidance is to build bulkhead, or cell-based, architectures so a failure is contained to a limited slice of the system: if a workload uses 10 cells to service 100 requests, a failure leaves 90% of requests unaffected. Adjacent to it is the security sense, the scope of what a compromised credential or breached IAM role can reach. Both are real, both are important, and Riftmap does none of it. Cell-based architecture, IAM scoping, and breach containment are a different discipline from mapping which repos consume your Terraform module, and pretending otherwise would be the exact kind of overclaim this blog exists not to make.

The change-impact sense: flags and canaries

The other honest sense of containment is exposure control after the code is deployed, and it works. Canary releases and feature flags reduce blast radius by limiting how much traffic meets a bad change. DeployHQ puts it plainly: "Reduced blast radius. A bug that ships to 5% of traffic affects 5% of users, not 100%." LaunchDarkly frames the same move as decoupling deploy from release, so code can sit dormant behind a flag and be exposed to a ring at a time. This is genuinely valuable and I would not ship anything risky without it.

It answers a different question, though. Flags and canaries control what percentage of traffic is exposed to a change. They say nothing about which repositories are structurally wired to the thing that changed. The two are complementary, not competing: a canary limits the fallout of a break you did not foresee, and a graph tells you which breaks to foresee in the first place. If you do not know a downstream repo consumes your module, no canary percentage will tell you it exists.

Structural containment: know the graph before the change ships

Structural containment is knowing the cross-repo graph before the change ships, so the artifact radius is a fact you read rather than an incident you discover. This is the layer the other two leave uncovered, and it is a parsing problem before it is anything else.

Here is what that looks like as a real number. Across the 242 GitHub repos in the cloudposse org, 147 other cloudposse repos declare a Terraform source reference to cloudposse/terraform-null-label, the org's own foundational naming-convention module, as of a scan completed 2026-07-07 and queried live 2026-07-08. That is 147 live source = edges into a single module, discoverable from no single one of those repos' checkouts. Be precise about what the number is and is not: it does not mean 147 repos would break tomorrow. It means 147 repos hold a live declared edge to that module, and whether any given consumer breaks depends on the next release and on whether that consumer is pinned. Here 138 are already on the latest tag and 9 are lagging, so the sharper containment statement is not "147 would break" but "147 consume this, and only 9 are not already on 0.25.0". terraform-null-label is unusually central even for its own org, so read 147 as this estate's top example, not a typical average. The point is not the size of the number. The point is that you cannot answer the question at all from inside any one of those repos, and the answer changes every time someone bumps a pin. We walked all 242 cloudposse repos in a separate scan writeup if you want the full picture.

This is measurable because the edges are declared. Riftmap parses them, deterministically, from what the manifests actually say rather than inferring them from names or embeddings, across an entire GitHub or GitLab organisation from one read-only token, with no per-repo YAML to maintain. The traversal is a plain breadth-first search over repo-to-repo edges in Postgres. The product's own information model already encodes the distinction this post is built on: the API endpoint that answers the question is GET /repositories/{repo_id}/impact, its docstring titles it "Transitive downstream blast radius (repo-level BFS)", and it says in as many words that it "does not trace specific files, jobs, or symbols within the source repo". The code radius is deliberately out of scope. The artifact radius is the whole job.

I want to be straight about two limits, because a sharp reader will raise both. First, a parsed graph is only as complete as what is declared. An HTTP call expressed in no manifest, a queue consumer wired by convention, a service discovered at runtime: none of that is in a source block, and a declared graph will not show it. That is a real boundary, and runtime discovery is a complementary axis, not a lesser one. SixDegree makes the reasoned case for the opposite priority, preferring discovered dependencies over declared ones when they conflict, and they are not wrong that runtime telemetry catches edges parsing cannot. The trade is honesty: a declared edge is kept honest by the build that already executes it, so it does not drift; a discovered edge needs the change already running to be seen. If the declared-versus-discovered distinction is where your interest is, we drew it out fully in declared, inferred, registered. Second, parsing declared cross-repo edges is not something only Riftmap can do. The open-source tool grafel traces Terraform and Kubernetes edges across repos as a local daemon, and it is genuinely good work. The line I would draw is scope and shape, not capability: an org-wide hosted graph across a dozen ecosystems, parsed from one token, is a different proposition from a daemon you run locally per machine. Neither claim needs the other to be false.

If your estate is bigger than you can hold in your head and you want to see the artifact radius before the next change ships rather than after it pages you, point Riftmap at your org and read your own graph before you merge.

The blast radius you can measure in CI is not the blast radius that pages you at 2am. One lives inside a repository, where your tests already run and the graph is legible. The other lives in the manifests of repos you have never opened, declared in files that are not on your disk, and it is the whole reason "it worked on my branch" and "it took down three teams" are both true at once. Measuring the first has been solved for years. Measuring the second is a parsing problem, and it is the one worth solving before you merge.

Questions engineers actually ask

What is blast radius in software engineering? Blast radius is the total set of things that break, degrade, or need updating when a change ships, measured from the function you edited out to the repositories you have never checked out. It splits into two layers: the code blast radius inside one repo, which your tests and type-checker already catch, and the artifact blast radius across repos, which travels through base images, Terraform source blocks, Helm values, and CI includes and is invisible from a single checkout.

How do you measure the blast radius of a code change? You build a dependency graph and traverse it backwards from the changed thing: depth 1 is direct dependents, deeper hops are the transitive tail. Inside one repo, a file or symbol import graph and impact-based test selection do this well. To measure the cross-repo radius you have to parse the declared manifest edges in every other repo, because the consuming edge lives in a repo that is not on your disk and no single-repo traversal contains it.

How do you contain or reduce blast radius? There are three senses. Cloud fault isolation (cell-based architecture, IAM scoping) contains failures at the infrastructure layer. Flags and canaries contain exposure by limiting what percentage of traffic meets a change. Structural containment means knowing the cross-repo dependency graph before the change ships, so the artifact radius is a fact you read rather than an incident you discover. The three are complementary, and only the third is about the dependency graph.

What's the difference between blast radius in AWS and the blast radius of a code change? "Blast radius" in an AWS context usually means fault or breach isolation: architecting cells so one failure or one compromised credential reaches a limited slice of the system. The blast radius of a code change is the set of code, services, and downstream repositories affected when that change ships. They share a word and an intuition but operate at different layers, and a tool for one does not do the other.

About Riftmap

Riftmap maps cross-repo dependencies across your entire GitLab or GitHub organisation — Terraform, Docker, CI templates, Helm, and more. One read-only token. No YAML to maintain.

What 242 Cloud Posse repos actually depend on

Daniel Westgaard — Sun, 05 Jul 2026 00:00:00 GMT

cloudposse/terraform-null-label is a Terraform module that does nothing at runtime. It generates names and tags. Its own README calls it a "Terraform module designed to generate consistent names and tags for resources," and that is the whole job. The kind of module nobody opens a PR against on a Tuesday and thinks twice about.

Open its Dependents tab on GitHub, the tab that is meant to tell you which repositories rely on a repository, and GitHub says: "We haven't found any dependents for this repository yet."

That is the single most-depended-on module in the entire Cloud Posse org, and the most obvious tool a sceptical reader would reach for reports zero. A Riftmap scan of all 242 Cloud Posse repos found that one module, terraform-null-label, is declared as a direct dependency by 147 of them, 61% of the org, nearly always on the same generated line of a file called context.tf. If you have read the earlier posts in this series, you have seen the 147 before: it is the corroborated landmark, not the news. The news is the graph around it. A drop from 147 consumers to 15 with nothing in between, two different centres, and a blast radius that fans across 61% of the org while staying one hop deep. That is the shape I want to plant before we go further.

This is the third org this series has taken apart, and it is the sharpest shape yet. The first two were a hub-and-spoke org and a loose federation. Cloud Posse is a keystone: hundreds of independent modules, one convention module holding up the majority of them, on a line most reviews never read.

The shape of the org at a glance

Across 242 repositories, Cloud Posse's public org resolves to 491 cross-repo dependencies pointing at 125 distinct artifacts. All but seven of those 125 are Terraform modules. This is an org that talks to itself almost entirely in Terraform.

It is worth saying how thin that in-org signal is against everything Cloud Posse declares. Set beside those 491 resolved in-org edges are roughly 12,900 dependency declarations that resolve somewhere else entirely: the AWS provider, the public Terraform registry, upstream Docker images. That is a single aggregate figure, so read it as an order of magnitude rather than a precise ratio, but the order of magnitude is the point. Roughly twenty-six declarations pointing out of the org for every one that stays inside it. Cross-repo-within-the-org is the rare, interesting signal here, not the common one, which is exactly why nobody has it assembled in one place.

Cloud Posse is a real business, and the description that matters is theirs, not mine. Its GitHub org bio calls it a "DevOps Accelerator for AWS Infrastructure." Its own docs describe running one test workflow "for all of our hundreds of terraform modules." Its flagship non-module project, Atmos, is a "Terraform Orchestration Tool for DevOps" that composes those modules into deployable stacks. So the org is not one big system. It is hundreds of small, independent, publicly published terraform-aws-* modules that mostly do not import each other. Which makes the one that they all import stand out.

The graph view: a star with two different centres

Drawn as a graph, Cloud Posse is a star, and it has two different centres. One node that almost everything points at, and one node that points at almost everything. They are not the same repo.

The first centre is the supplier. terraform-null-label sits at 147 inbound edges, roughly ten times the next module's count. Almost every module in the library reaches back to it. The second centre is the consumer. cloudposse/terraform-aws-components, Cloud Posse's reference-architecture "components" catalog, declares 110 outbound cross-repo dependencies, about eleven times the next-busiest repo (cloudposse/.github, at 10). One repo supplies the org. A different repo assembles it. A supplier hub and a consumer hub, and reading a single repo's clone shows you neither, because both facts only exist in the relationships between repos.

Of the 491 edges, 359 are Terraform module { source = ... } blocks, which is 73% of everything. Another 36 are GitHub Actions uses: references, 8 are Dockerfile FROM lines, 4 are reusable-workflow uses:, and exactly 1 is a go.mod require. That is the declared graph: every one of those edges is read straight from a manifest the tooling already executes.

The remaining 83 edges are not a parsed ecosystem at all, and I want to be careful not to dress them up as one. They are git_url_reference edges: the output of a heuristic regex layer that scans arbitrary text, line by line, for GitHub URLs that point back into the org. A git clone in a README, a fetch command in a shell script. Every one of those 83 sits at 0.6 or 0.7 confidence by design, because a URL in a comment is not the same kind of fact as a Terraform source block. This is the inferred layer sitting beneath the declared one, a safety net for edges no formal parser owns, and I keep it visibly separate from the declared graph rather than counting it as a sixth ecosystem. The cross-repo dependency graph that matters here is the 408 declared edges. The 83 heuristic ones are there so a real dependency written in a place no parser reads does not vanish silently.

The pattern at the centre: one module, 147 consumers

The centre of Cloud Posse is terraform-null-label, declared by 147 of the 242 repos. The number is the landmark this series keeps returning to. The fresh part is the shape of the drop-off after it, and the drop-off is a cliff. Ranked by consumer count, the top of the in-degree table reads:

terraform-null-label: 147 consumers
terraform-aws-route53-cluster-hostname: 15
terraform-aws-security-group: 13
terraform-aws-iam-role: 9
terraform-aws-s3-log-storage and terraform-aws-sns-topic: 7 each

The number two module is consumed by 15 repos. The keystone is consumed by 147. There is nothing in the middle. This is a genuinely different shape from the other two orgs in this series, and the difference is where the blast radius concentrates. Prometheus was hub-and-spoke: a few core repos, a readable ring of consumers around each, so losing any one hub takes down its own ring and no more. The kubernetes-sigs org was a federation: many sub-projects, dependencies spread thin and evenly, no single load-bearing centre to lose. Cloud Posse is neither. It is a keystone. Pull it and 61% of the org is standing on nothing at once, and there is no second load-bearing node to absorb the fall. Every one of those 147 modules would still parse, still plan, still look fine in its own repo. The dependency that decides the blast radius is the one nobody remembers is load-bearing, because it is boring and it has always been there.

Where the receipts live: `context.tf`, line 24

Of the 147 Cloud Posse repos that declare terraform-null-label, 133 declare it on the same line of the same file: context.tf, line 24. This is not a coincidence and it is not inference. It is Cloud Posse's own documented convention. Their conventions doc explains it plainly: "By convention, we install this file as context.tf which is why we call it the context.tf pattern." A context object carries the naming and tagging inputs, every cloudposse/terraform-* module exposes it as module.this, and the file that defines it is meant to be copied byte-for-byte from the canonical copy in terraform-null-label itself. The dependency is not authored per repo. It is generated, and the generator puts the module "this" block in the same place every time.

Here is the module "this" block a real consumer carries, fetched live from cloudposse/terraform-aws-route53-cluster-zone; the source line is line 24:

module "this" {
  source  = "cloudposse/label/null"
  version = "0.25.0" # requires Terraform >= 0.13.0

That cloudposse/label/null string is a Terraform registry short-address, and it resolves to the cloudposse/terraform-null-label repository through the registry's naming convention. Every one of the 133 repos that use context.tf puts that block at line 24 exactly, with no exceptions in the population. The other 14 of the 147 declare the same dependency somewhere else: main.tf in seven of them, public.tf in two, and one each in a handful of other files, at various line numbers. So the honest quantifier is not "every one of the 147." It is 133 of 147, about nine in ten, on context.tf line 24, and the remaining fourteen off the beaten path. The copy-paste convention is enforced by discipline and codegen, not by the language, which is exactly why a real scan finds a long tail that a "they all do it the same way" assumption would miss.

The version story is just as legible from the receipts. Of the 147 consumers, 139 pin a clean semantic version and 8 pin a git-tag path like tags/0.3.1 rather than a bare version string. None float on a range. 138 are on the current 0.25.0; 9 sit behind it. Those 9 are exactly the 8 git-tag pins, which can never string-match a semver release, plus one repo cleanly pinned to the previous 0.24.1. That reconciles a discrepancy an earlier post in this series flagged and left open: "9 lagging" is a recency cut and "8 on a git-tag path" is a syntax cut, and both are correct at once. They were never in conflict. They were counting two different things.

If I bump `terraform-null-label`, what breaks?

I opened a PR bumping terraform-null-label to a new tag, then asked Riftmap what it would touch across the org. I ran the impact query the way Post B's merge gate runs it: confidence floor at 0.8, up to three hops out. The answer came back at 147 affected repositories, and every one of them at depth one. Nothing at depth two. Nothing at depth three.

That flatness surprised me the first time, and then it made complete sense. The keystone does not cascade because Cloud Posse's high-fan-in modules mostly sit at a single layer rather than stacked in chains. The repos that consume terraform-null-label's direct consumers already are direct consumers themselves. The blast radius is exactly as wide as the direct-consumer count, and it stops there. Wide and flat. One file change, 61% of the org in scope, no transitive tail. I should be precise about what this call proves and what it does not: it enumerates the 147 repos whose declared dependency chain resolves back to the module. It does not prove each one would break on a version bump. It is the list of everything you now have to think about, not a verdict that all 147 are broken.

Now the part this post exists to show. Take that same one-line bump and ask what each detection method would actually return.

Grep gets you close to the headline count, and I am not going to pretend otherwise. gh search code --owner cloudposse "cloudposse/label/null" would surface most of the 147, because for this particular construct the string genuinely is the receipt. That is the honest concession, and it is different from the Go or protobuf cases where the resolved edge is nowhere in the literal text. What grep cannot do is tell you that 8 of those matches pin a git-tag path and 139 pin a semver and none float, or which of the 133-versus-14 files and line numbers each match lives on, or how cleanly each reference resolved. And it cannot tell you how deep the chain runs. Grep returns an undifferentiated list of string matches with no depth attached, so it cannot tell a blast radius that stops at its direct consumers from one that runs several hops past them. That this one is flat is a finding the graph produced, not something grep could confirm. It finds the string. It does not assemble the graph, and it does not carry the state.

A symbol graph returns nothing, and this is the cleanest possible version of that claim. I have a lot of respect for Sourcegraph; its SCIP symbol graphs are excellent at the category they are in. But that category is programming-language symbols, and a Terraform module block's source is HCL configuration data, not a symbol in any language a SCIP indexer parses. Sourcegraph's own list of indexers runs scip-go, scip-typescript, scip-clang, scip-java, rust-analyzer, scip-python, scip-ruby, scip-dotnet. There is no Terraform or HCL indexer on it, and there is no partial-credit exception the way there is for go.mod and package.json, where the import path is itself a language symbol. A symbol graph does not resolve this edge poorly. It never looks at the file. Symbol graphs and artifact graphs are different categories.

A catalog returns whatever a human registered, which for this is almost certainly nothing. I want to be fair to catalogs first, because they hold things parsing cannot see: ownership, on-call, the tier of a service, which team you page. But a Backstage relation, in Backstage's own words, "is commonly generated based on spec.dependsOn of the component or resource in question," and Port works the same way inverted, with a human writing the relation into their IaC. Nobody hand-registers 147 context.tf module sources across 147 repos and keeps them current. So a catalog either has no record of this dependency or a stale, partial one, and you cannot tell which parts are current from inside the catalog.

Riftmap returns the parsed graph, current as of the scan: 147 consumers, the 8 git-tag pins and the 139 semver pins, the 133 on context.tf line 24 and the 14 elsewhere, the flat depth-one blast radius. Not because the count is secret knowledge. The value is not that 147 is un-greppable. The value is resolution, state, transitivity, and honest confidence, assembled once into one graph the org already declared but never had in one place. Which is the whole reason GitHub's Dependents tab still reads zero for it: the graph was always sitting in the manifests, and nobody had assembled it.

What Riftmap didn't see, and why

Cloud Posse produces eight kinds of artifact, Riftmap parsed all eight, and only three of them are consumed by another repo inside the org. The production footprint is genuinely multi-ecosystem: 156 Terraform modules, 154 Terraform root configs, 69 Helm charts, 60 generic artifacts, 19 Docker images, 15 Go modules, 11 npm packages, 2 GitLab CI templates. But only Terraform modules, Docker images, and Go modules show up as cross-repo edges at all. Of the 156 Terraform modules the org produces, 118 are consumed by a sibling repo; of the 19 Docker images, 6 are; of the 15 Go modules, 1 is. Zero of the 69 Helm charts, zero of the 11 npm packages, zero of the 154 Terraform root configs, and zero of the 2 GitLab CI templates are consumed by a sibling Cloud Posse repo in this scan.

That is not a parser gap, and the why is worth being precise about, because the honest answer is more interesting than "we missed some." The Terraform root configs are terminal by design: a root module is meant to be deployed, not sourced by another module, so it is an orphan the same way a deployable stack is an orphan, on purpose. The Helm charts and npm packages most plausibly have real consumers, just not inside this org: Cloud Posse publishes charts and a CLI for the public to use, and an intra-org scan is structurally blind to consumption that happens outside the org boundary. That is the same intra-org caveat the first post in this series already carries. Separately, 43 of the 242 repos, about 18%, touch no cross-repo edge at all, either because they declare nothing the scan recognises as cross-repo or because everything they declare resolves outside the org. The scan skipped nothing and errored on nothing. What it did not draw, it did not draw for a reason it can name.

Methodology, briefly

The scan read all 242 repos with zero skipped and zero errors, in about twelve and a half minutes. No model sits anywhere in that parsing path; every edge is read from a manifest construct, not inferred from text or names or embeddings.

The one number worth dwelling on is the confidence distribution, because it is the opposite shape of the last org-scan and the difference is the interesting part. In this scan, 20.2% of edges resolve at confidence 1.0 and the dominant band is 0.9, at 61.1% of everything. That is not doubt. A confidence score on a parsed edge is not "do we think this edge is real," it is how cleanly the reference resolved to a known target. And 300 of the 359 Terraform edges resolve through the registry short-address convention, turning cloudposse/label/null into the cloudposse/terraform-null-label repo, which the resolver grades 0.9 because it took a documented naming rule rather than an exact string match. A real, deterministic, declared edge, resolved by a rule instead of an identity. The heuristic git_url_reference band is the only part sitting below the 0.8 deterministic floor, at 16.9%. Three org-scans in this series, three different confidence shapes, each one explained entirely by how that particular org names and resolves its own dependencies.

Two asks

Two asks, both small. First, if you find an edge Riftmap drew wrong or missed on a public org, tell me. A misresolved short-address or an unparsed construct is a bug I want to fix, and I credit the report. The honesty beats above exist because someone has to go check the long tail, and a second pair of eyes on a public graph is worth more than another adjective. Second, and it is the ask that actually matters: run this same scan against an org you own, not one you are reading about.

Where this sits in both series

This post is the third entry in one series and the fourth in another. As "what an org actually depends on," it sits alongside the Prometheus and kubernetes-sigs scans, three real orgs with three genuinely different shapes: hub-and-spoke, federation, keystone. As the fourth "blast radius before merge" post, it is the worked org behind the argument the other three make in the abstract: Post A's three layers, where this post's contrast of what each detection method returns comes from; Post B's merge gate, whose impact contract produced the flat 147; and Post C's declared, inferred, registered taxonomy, which is why the 83 heuristic edges sit apart from the 408 declared ones.

Scan your own org

You can run the same scan against your own org. Everything above came out of one read-only token, an org-level install, and about twelve and a half minutes, with no per-repo YAML to write and no catalog to maintain. If you want to know which repos break before you bump a shared module or a base image, including the dependency that used to live only in the head of the engineer who just left, point Riftmap at your org and look at your own keystone before you change it.

About Riftmap

Riftmap maps cross-repo dependencies across your entire GitLab or GitHub organisation — Terraform, Docker, CI templates, Helm, and more. One read-only token. No YAML to maintain.

Common questions

What does the Cloud Posse org depend on? Internally, almost entirely on itself, in Terraform. A Riftmap scan of all 242 Cloud Posse repos (2026-07-04) found 491 cross-repo dependencies pointing at 125 distinct artifacts, and 73% of those edges are Terraform module { source = ... } blocks. The single most-depended-on artifact is cloudposse/terraform-null-label, the naming-and-tagging module that 147 of the 242 repos declare. Most of what the org declares actually resolves outside itself, to the AWS provider and public registries, so cross-repo-within-the-org is the rare signal.

How many repos depend on terraform-null-label? 147 of Cloud Posse's 242 repos, which is 61% of the org, each declaring it through a Terraform module { source = "cloudposse/label/null" } block. 133 of those 147 declare it on the same generated line, context.tf line 24, following Cloud Posse's own copied-file convention. 138 are on the current 0.25.0 and 9 sit behind it. GitHub's own Dependents tracker, by contrast, reports zero dependents for the repository, because it does not parse Terraform source blocks.

What breaks if you bump a Terraform module used across an org? For terraform-null-label specifically, the deterministic blast radius is 147 repositories, and all of them are direct consumers: at a 0.8 confidence floor over three hops, nothing appears at depth two or three, so the impact is wide but flat. That count enumerates every repo whose declared dependency chain resolves back to the module; it is the set you now have to review, not a verdict that all 147 will fail to plan. grep can approximate the count because the module source string is the receipt, but it cannot tell you which references are pinned to a git tag versus a semver, which file and line each lives on, or how deep the dependency chain runs. Here it is flat, but grep cannot tell a flat radius from a deep one because its matches carry no depth.

Declared, inferred, registered: the three ways a tool knows a cross-repo dependency exists

Daniel Westgaard — Sat, 04 Jul 2026 00:00:00 GMT

Three lines were open in three tabs on my screen last week, and all three declared a dependency that crosses a repository boundary.

The first was a Helm chart. In argoproj/argo-helm, the argo-cd chart's Chart.yaml carries a dependencies: block:

dependencies:
  - name: redis-ha
    version: 4.38.0
    repository: https://dandydeveloper.github.io/charts/

The second was Terraform. In cloudposse/terraform-aws-vpc, the root main.tf has a module block whose source points at another repo entirely:

module "label" {
  source  = "cloudposse/label/null"
  version = "0.25.0"
}

The third was a Dockerfile. In cilium/cilium, images/cilium/Dockerfile builds its release stage from a base image passed in as a build argument:

FROM ${CILIUM_RUNTIME_IMAGE} AS release

Run grep across the org for any of these and you get a partial answer. It finds the string redis-ha, but not that the chart resolves against a Chart.lock you would have to read separately. It finds cloudposse/label/null, but has no idea that registry short-address maps to the cloudposse/terraform-null-label repo. It finds ${CILIUM_RUNTIME_IMAGE} and stops, because the real image name is bound somewhere else. Point a symbol graph at the same three files and it finds nothing at all. None of these is a programming-language symbol. No compiler and no SCIP indexer parses a Chart.yaml, an HCL module block, or a Dockerfile instruction as source code.

Here is the claim I want to plant before we go further. Before you merge and run a change, a cross-repo dependency can be known to a tool in three ways: declared in a manifest the machine already executes, inferred from statistical signal, or registered in a catalog a human maintains. (A fourth mode, observing the edge at runtime, needs the change already running, which is exactly what you do not have before merge. More on that below.) Those three regimes are not three qualities of the same thing. They are three different answers to the question how did the tool come to know this edge exists at all, and each one buys a different, structural failure mode.

"Parsed, not inferred" stages a two-horse race and quietly drops a third runner

The slogan I and half the industry reach for is "parsed, not inferred." It is a good slogan and it is doing less work than it sounds like. It stages a two-horse race: on one side the tool that reads what a manifest says, on the other the tool that guesses from embeddings and model output. That framing is real, but it hides the regime that quietly runs a large share of platform teams, which is neither parsed nor inferred. It is registered: an edge some human typed into a catalog, that no machine executes and no model produced.

So the honest split is three-way. Declared, inferred, registered. This is a different axis from the one I drew in an earlier post in this series, where the taxonomy was symbol / live-state / artifact. That split is about which layer of the stack an edge lives on. This one is about how a tool knows the edge is there. They compose. An artifact-layer edge can be declared, inferred, or registered, and the same Terraform module source can show up in all three tools by three different routes. The rest of this post is about that second axis, because it is where the word "parsed" is quietly carrying an argument it never actually made.

Declared: the edge the machine already executes

A declared dependency is one written into a manifest that the machine already reads and executes to do its job. Nobody adds a FROM line to document a dependency. They add it because the build will not produce an image without it. The dependency edge is a side effect of a file that has to be correct for the system to run at all, which is what makes it deterministic. terraform init resolves the module source or the plan fails. helm dependency update pulls the chart named in dependencies: or the release is incomplete. The edge is not a description of the system. It is part of the system.

What counts as declared

The declared regime is wide, and it is precise. Each ecosystem has its own construct, and the point is to name the construct rather than wave at "config files":

Helm Chart.yaml dependencies: entries (name, version, repository), which Riftmap reads as helm_dependency edges.
Terraform module { source = ... } blocks, read as terraform_module edges. Registry short-addresses and git URLs count as cross-repo; a bare ./ local path does not, nor do full registry URLs like registry.terraform.io/ or app.terraform.io/.
Dockerfile FROM lines, read as docker_base_image edges.
go.mod require directives, and the replace directives that quietly redirect them.
GitHub Actions uses: values, whether they point at owner/repo@ref or a reusable .github/workflows/x.yml@ref.
GitLab CI include: in its several forms (project:, remote:, component:).
Kustomize remote resources: and bases:, read as kustomize_resource edges.
npm package.json dependencies, including the npm: alias and git+ forms where the imported name and the actual package differ.
Ansible, where the precision matters. A role's meta/main.yml dependencies: list emits a role-to-role edge (ansible_role) regardless of how the string is dotted. A task in a playbook that calls a three-segment FQCN like polaris.infrastructure.deploy emits a collection edge (ansible_collection). Two different files, two different edge types. An FQCN in meta/main.yml still resolves as a role dependency and not a collection reference, because that file is what Ansible reads when it loads a role's dependencies.

That precision is the whole personality of the declared regime. The edge is not "there is a dependency somewhere in this YAML." It is a named construct with a known grammar and a known resolution step.

Why grep only half-sees it

Grep finds the string and misses the meaning, because in every one of these constructs the literal text is not the resolvable target. A Helm version: is usually a semver range, not a pinned version. A Terraform registry short-address like cloudposse/label/null has to be resolved through the registry's naming convention before you know which repo backs it. A Dockerfile FROM ${VAR} names a variable, not an image. A GitLab CI include: has five distinct shapes and an unqualified shorthand that silently resolves to local-or-remote depending on the string. An npm dependency can be declared under an alias, so the name in the code and the package actually installed are different strings. Grep sees text. The declared edge is text plus a resolution rule, and grep does not run the rule.

Why a symbol graph misses it

For most of these constructs, a symbol graph does not miss the edge so much as never look at it, because a symbol graph indexes programming-language symbols and none of these are symbols. Helm, Terraform, Docker, GitLab CI, GitHub Actions, Ansible, Kustomize. A compiler-accurate indexer like Sourcegraph's SCIP has nothing to say about any of them, because they are not code it compiles. This is not a knock on Sourcegraph. Symbol graphs and artifact graphs are different categories, and Sourcegraph is genuinely excellent at the category it is in.

I want to be fair about the two exceptions. For go.mod and package.json, the import path is itself a language-level symbol. Sourcegraph's own writeup on cross-repository code navigation describes how SCIP's external symbols carry cross-repository dependency information across the languages it indexes, without calling out any ecosystem by name. A Go import path and an npm package name are exactly that kind of symbol, so I read those as edges a symbol graph can resolve cross-repo when cross-repo indexing is configured. That is my inference from how Go and npm name their imports, not a claim on Sourcegraph's page about those two ecosystems. It is a real capability, and a heavier lift most installs skip. The manifest parser reads the literal require or dependencies value regardless of indexing, and it still catches the cases a symbol resolver handles less cleanly: the npm: alias, the renamed module path, the non-registry git source. Different mechanisms, overlapping coverage, and I would rather concede the overlap than pretend it away.

The scale is the part that does not fit in a code review. A full Riftmap scan of the cloudposse GitHub org (242 repos, completed 2026-07-02) found 147 repos declaring a dependency on cloudposse/terraform-null-label via a Terraform module { source = "cloudposse/label/null" } block. 138 were on the current 0.25.0. 9 were pinned behind. Nearly every one of those references sits at the same place, context.tf line 24, the line cloudposse's own module template generates. That is one declared edge, in one construct, in one org, repeated across 147 repos on a single templated line. It is exactly the kind of signal that is trivial to parse and impossible to hold in your head across 242 repositories. The full shape of that org — the cliff from 147 consumers down to 15, the flat depth-one blast radius, and what grep, a symbol graph, and a catalog each return for the same module — is its own scan writeup: what 242 Cloud Posse repos actually depend on.

The honest failure mode of the declared regime is coverage. A parser is software. It only sees the ecosystems someone wrote a parser for, and it has the blind spots any parser has. If a team declares a dependency in a format nobody has written a parser for, the edge is real and the tool does not see it. That is a genuine limit, and it is a different kind of limit from the two that follow.

Inferred: the edge guessed from statistical signal

An inferred dependency is one a tool produces from statistical signal rather than reading it from a declaration. Embedding proximity. Name similarity. Model output. Co-change history. This is the regime that reaches for a coupling nobody wrote down in any artifact at all: two files that always move together in the commit history, a service whose vocabulary sits close to another's in embedding space, a natural-language question about the codebase answered from summaries rather than a parse. When there is no manifest entry and no catalog record to read, inference is the only thing left that can even suggest the edge exists. That is a real place on the map, and declared parsing does not stand on it.

The failure mode is that inference has no ground truth. It produces a probability that an edge exists, and probabilities are wrong at a rate. This is measured, not folklore. When Richardeau et al. asked a range of LLMs to reproduce Zachary's Karate Club graph, every model got it wrong. The benchmark has 34 nodes and 78 known edges. The best model still added two edges that are not in the graph. Edge-count outputs across models ranged from 8 to 153 against a ground truth of 78 (arXiv:2409.00159). In a code-specific setting it is sharper. On a 15-question architecture-discovery suite against the Shopizer repo, an AST-derived dependency graph scored 15 out of 15. An LLM-extracted knowledge graph scored 13. A vector-only baseline scored 6 (arXiv:2601.08773). The same study documents a coverage failure distinct from being wrong: the LLM extraction pass skipped 377 files outright, so the graph it built was missing large parts of the dependency surface, not just occasionally mistaken about the parts it covered.

The confidence score is the tell. An inferred edge comes with a number that means "how likely we think this edge is real," and that number is doing load-bearing work, because without it you cannot separate the edges the tool is sure about from the ones it guessed. Turn the threshold up and you drop real edges. Turn it down and you admit false ones. There is no setting that gives you both, because the underlying quantity is a belief, not a fact. Inference is the right tool when nothing is written down anywhere. It is strictly worse than reading the file when the edge is already declared, because guessing at an edge that is sitting in plain text can only add error to something you could have simply read.

Registered: the edge a human wrote in a catalog

A registered dependency is one a human wrote into a catalog that no machine executes. Backstage represents it as spec.dependsOn in a catalog-info.yaml, which the catalog processor turns into a directional relation at ingestion. Port represents it as a relation between blueprints, single or many, which its docs frame as the software catalog as a dynamic graph database. And I want to concede the real thing first, because it is real: catalogs model relationships that parsing simply cannot see. Ownership. On-call. Which team you page. The tier of a service. There is no manifest the build executes that declares who owns a repo, and a good catalog is the right home for that.

The failure mode is drift, because a registered edge is true only as of the last human edit, and nothing executes it to force a correction. This is not a competitor's insinuation. It is Backstage's own documented behaviour: issue #20030 describes how unregistering an entity leaves related entities carrying stale relationships until a later processing pass, and a Group page will show a live warning about relationships to entities that no longer exist. Port's CTO makes the maintenance case directly, though as an interested party. As he puts it on Port's blog, "YAMLs require maintenance when code changes occur. This results in outdated information that can affect operations and decision-making…". And from the adoption side, Roadie, a Backstage-ecosystem vendor and not a rival, reports two customers reaching 88% and 90% catalog completeness over roughly four months of active effort. That last number is the one I keep coming back to. Even funded, deliberate catalog work plateaus below 100%, because the catalog is a second job that competes with shipping, and the parts nobody remembered to update are silently indistinguishable from the parts that are current. I have written more on why teams quietly abandon the catalog elsewhere.

A fourth mode: discovered at runtime, and why it is unavailable before merge

There is a fourth way to know a cross-repo edge exists, and it is neither declared, inferred, nor registered: you can observe it at runtime. Because it lives on a different axis from the other three, I want to name it and set it aside cleanly rather than fold it into inference. A service mesh, DNS, live traffic, a database connection resolved in production. That edge is discovered by watching the system run, and it is genuinely powerful, because it is the only thing that sees the undeclared HTTP calls a service makes to three others through environment variables injected at runtime, calls no manifest declares. This is the live-state layer, the subject of the first post in this series. SixDegree calls it "discovered", and their tie-break rule, prefer discovered over declared when the two conflict, is correct for the question it answers. Runtime observation is righter than any manifest about what is talking to what right now. What it cannot tell you is anything about a change that has not been merged yet, because you cannot observe the traffic of a base-image bump that does not exist in production. The thing you want the blast radius of has not run. That is why this series is about blast radius before merge, and before merge the edges you can actually know are the declared, inferred, and registered ones.

Does a parsed dependency edge need a confidence score?

Riftmap parses deterministically and still puts a confidence score on every edge, and those two facts only sound contradictory until you see what the score measures. It is not inference confidence. There is no model, so the number can never mean "we think this edge is real." It is resolution confidence: how cleanly the declared reference matched a known target in your org. The resolver's own dataclass documents it in one line. """Resolution confidence. 1.0 = exact match; lower = heuristic.""" Every value below it comes from a string or path comparison, an if, not a probability.

The external precedent for this distinction is, again, Sourcegraph. Their precise vs search-based code navigation split does the same thing one layer up. Precise navigation is compiler-accurate when a SCIP index exists. Search-based navigation is what Sourcegraph falls back to, in their own words, "when precise navigation is not available." Neither mode is doubt about whether a symbol is real. The distinction is match quality on how the reference was resolved, precise index versus heuristic search. A declared-edge resolution score is the same shape of thing, one layer down at the artifact level.

This is where I need to reconcile something honestly, because an earlier post in this series set a merge gate at min_confidence=0.8, and it would be easy to read that as "declared edges are always at least 0.8." They are not. The 0.8 floor excludes a separate regex-heuristic layer that scans files no formal parser owns, whose findings sit at 0.4 to 0.7 by design, plus a few declared edges that resolved fuzzily. The score moves for two deterministic reasons: ambiguous declaration syntax, or an imperfect string match to a known target. Neither reason is doubt about existence. The live cloudposse graph proves it: the terraform-null-label edge I pulled from the production API resolves at 0.9, not because anyone is unsure the edge exists, but because turning cloudposse/label/null into the cloudposse/terraform-null-label repo took a documented naming-convention rule rather than an exact string match. A ${var}-templated Terraform source lands at 0.5. The four ${VAR}-templated FROM lines in that cilium Dockerfile land at 0.7, each of them a real, declared base-image edge whose confidence is lower only because the image name is bound through a build argument. The number answers "how cleanly did this resolve." It never answers "do we think this is real," because nothing in the pipeline is guessing.

The three regimes differ in what keeps each edge honest

The three regimes differ in the thing that decides whether they stay true: what keeps each edge honest.

A declared edge is kept honest by the machine that executes it. Get a FROM line wrong and the build breaks. Get a module source wrong and terraform init fails. The manifest is not honest because humans are diligent about it. It is honest because it is load-bearing, and the same machine that consumes the edge re-reads it on every run. An inferred edge is kept honest by nothing. There is no build that fails when the model guesses wrong; you re-roll the dice and get a different graph. A registered edge is kept honest by human diligence alone. Nothing executes a catalog, so it rots at exactly the rate that attention wanders, which is quickly.

I have to concede a point the research made me sharpen, because a reader who knows the build-dependency-error literature will catch it otherwise. Declared is not infallible. It is true to the manifest, not true to the world. A Helm dependencies: entry nobody pruned, a Terraform module block whose source still points at code no longer wired into any resource. These are declared-but-dead edges, the same failure shape a catalog has. Declared and registered are both things somebody wrote down, and both can be stale while still parsing cleanly. The difference is not that declared never goes stale. It is that a declared edge lives in the file the machine runs, so it is cheaper to keep current than a catalog is: nobody has to remember to edit it, because the machine re-reads it every time it runs, and a wrong one tends to announce itself by breaking something. A catalog entry that goes wrong just sits there, wrong and quiet.

That is why the declared regime is the substrate I would want under an agent making a small cross-repo infra change. You cannot ask an agent to maintain a catalog, and you cannot trust it to guess. What you can do is hand it the edges the org already declared, kept current by the same machines that already depend on them being correct, including the base-image or shared-module dependency that used to live only in the head of the engineer who just left.

Where Riftmap sits

Riftmap lives in the declared regime, on purpose. It reads the edges your manifests already declare. Terraform module source, Dockerfile FROM, Helm dependencies:, GitLab CI include:, and the rest. It reads them deterministically, with no model anywhere in the parsing path, across an entire GitHub or GitLab organisation from one read-only token. No catalog YAML to maintain, because the edges are parsed straight from the files that already exist and re-read on every scan. It is not trying to be the inference tool for undeclared runtime calls, and it is not a catalog. It is the substrate: the cross-repo artifact graph the org already declared but never had assembled in one place. If you want to see what your own org declares that no single repo's clone can show you, run a scan against a read-only token and look at the graph before you bump the next base image.

About Riftmap

Riftmap maps cross-repo dependencies across your entire GitLab or GitHub organisation — Terraform, Docker, CI templates, Helm, and more. One read-only token. No YAML to maintain.

Common questions

What's the difference between declared, inferred, and registered dependencies?

A declared dependency is written into a manifest the machine already executes to do its job, like a Dockerfile FROM line or a Terraform module source, so it is deterministic and re-read on every run. An inferred dependency is guessed from statistical signal such as embeddings or LLM output, so it comes with a probability and no ground truth. A registered dependency is one a human typed into a catalog like Backstage or Port, which no machine executes, so it is accurate only as of the last edit. The three differ in what keeps the edge honest: the machine that runs it, nothing, or human diligence alone.

How do dependency-mapping tools actually detect dependencies, and are the edges parsed or inferred?

It depends on the tool, and "parsed vs inferred" hides a third option. Some tools parse the edge from a manifest declaration deterministically, some infer it from statistical signal like embeddings or model output, and some read it from a human-maintained catalog. Parsing gives you an edge that is true to the manifest and self-correcting because the machine re-reads it; inference gives you probabilistic coverage of couplings nothing declares; a catalog gives you relationships like ownership that neither can see, at the cost of drift. Observing an edge at runtime is a fourth mode, but it needs the change already running, so it cannot tell you the blast radius of something not yet merged.

Why do grep and symbol graphs miss infrastructure dependencies?

Grep finds the literal string but not the resolution rule behind it: a Terraform registry short-address, a Helm semver range, or a Dockerfile FROM ${VAR} is text plus a rule that maps it to an actual repo, and grep does not run the rule. Symbol graphs index programming-language symbols, and Helm, Terraform, Dockerfile, GitLab CI, GitHub Actions, Ansible, and Kustomize constructs are not symbols any compiler parses. For go.mod and npm the import path is a language symbol, so a symbol graph can resolve those cross-repo when cross-repo indexing is configured, which most installs skip.

Does a parsed dependency edge need a confidence score?

Not to say whether the edge exists. A parsed edge is read from a declaration, not guessed, so there is no probability that it is real. A confidence score on a parsed edge measures resolution quality instead: how cleanly the declared reference matched a known target, where 1.0 is an exact match and lower means a documented heuristic like a naming convention was needed. That is the same distinction Sourcegraph draws between precise and search-based navigation, and it is a different quantity from the existence-probability an inference tool attaches to a guessed edge.

How to add a blast-radius gate to your merge pipeline

Daniel Westgaard — Fri, 03 Jul 2026 00:00:00 GMT

A pull request to a repository that a hundred others build on should not merge with one approval from a phone. Here is a CI gate that routes the review by measured downstream exposure, in two HTTP calls and about forty lines, on GitLab CI or GitHub Actions.

Someone opens a one-line pull request. It bumps the default in a shared Terraform module, or edits the FROM line in a base image, or changes an include in a CI template. The plan is clean. The diff is three characters. CI goes green, one reviewer approves on their phone between meetings, and it merges. Then the next terraform init in six other repositories resolves the new version, and the people who own those repositories find out from their own pipelines.

The change was correct in isolation. What went wrong was the review. A repository that a hundred others build on had exactly one person look at the thing before it shipped, and that person had no way to see, from inside the pull request, who was standing downstream.

The industry's answer to this has arrived as a wave of pre-merge blast-radius gates, and they are worth taking seriously. Overmind ships a GitHub Action that submits each pull request's Terraform plan and comments the blast radius straight onto the PR. An open-source project reads live dependency relationships out of AWS Config and fails the build with a threshold gate when a change fans out too far. Amazon's answer, after its own change-failure numbers moved, was blunter: require senior sign-off on AI-assisted changes from junior and mid-level engineers. Three gates, and every one of them checks a different graph.

A blast-radius merge gate is only ever as good as the graph it queries. And for the class of change that most needs a second pair of eyes, a base image bump, a shared module rename, a CI-template edit, the graph you want is the artifact graph: which repositories declare a build-time dependency on the thing this pull request changes. That is the graph none of the gates above reads, because a FROM bump has no Terraform plan and no running resource and no code symbol, and it is the one you can query from CI today in two HTTP calls. This post is Post A made operational: the three-graph argument, turned into a job you can paste into a pipeline.

The gate is two GET requests

The whole gate is two GET requests and a threshold. You need one thing that is not in the pipeline, a Riftmap graph of your organisation, which is a one-off read-only scan I will come back to at the end. Given that, the gate resolves itself, because both platforms hand a CI job the repository's own path for free. It is $CI_PROJECT_PATH on GitLab and ${{ github.repository }} on GitHub Actions, and that is exactly what the lookup call takes. Nested GitLab subgroups are included: on a project at platform/runtime/base-images, $CI_PROJECT_PATH is that whole three-segment path, which is exactly the form the scan stores, so the lookup matches nested namespaces without any massaging.

# 1. Resolve owner/repo to its Riftmap id.
REPO_ID=$(curl -sf -H "X-API-Key: $RIFTMAP_API_KEY" \
  "https://api.riftmap.dev/api/v1/repositories/lookup?full_path=$REPO_PATH" | jq -r '.id')

# 2. Ask who declares a dependency on it.
curl -sf -H "X-API-Key: $RIFTMAP_API_KEY" \
  "https://api.riftmap.dev/api/v1/repositories/$REPO_ID/impact?max_depth=3&min_confidence=0.8"

The impact call walks the dependency graph outward from your repository and returns every repository that depends on it, each tagged with a depth and a confidence, plus a total_affected count. Depth 1 is who breaks first: the repositories whose manifests name yours directly, a source block resolving to your module, a FROM line pinned to your image, an include pointing at your template. Deeper hops are the amplification. min_confidence defaults to 0.8, which drops the heuristic matches and keeps the edges Riftmap parsed rather than guessed, and for a gate you want it there. (That number is resolution confidence, not existence probability, and the 0.8 floor is doing something more specific than it looks; a companion post works through how a tool knows an edge exists at all and what the score actually measures.)

One thing has to be honest before you wire this to anything, because it decides whether the whole idea is useful or noise. The count is the standing consumer population as of the last scan, at the level of the whole repository. It is not a diff of which consumers your specific change breaks. A repository with 147 downstream consumers returns 147 whether this pull request renames an output every one of them uses or fixes a typo in a comment. So this is a gate on exposure, not on breakage. Read the rest of this post with that framing and it stays sharp. Sell it to your team as a breakage detector, and the first person to run it on a busy shared repository will watch it fire on every pull request, including their own README fix, and quietly conclude the tool is broken. It is not measuring danger. It is measuring how many people a mistake here could reach.

The GitLab CI recipe

Here is the entire gate as a GitLab CI job that runs on every merge request. It needs one thing configured, a masked CI/CD variable called RIFTMAP_API_KEY holding a read-only Riftmap key (mint one labelled ci so you can revoke it independently of the rest).

# .gitlab-ci.yml
blast-radius:
  stage: test
  image: alpine:3.20
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  variables:
    RIFTMAP_BASE_URL: "https://api.riftmap.dev/api/v1"
    THRESHOLD: "10"                    # direct consumers that warrant the review lane
  before_script:
    - apk add --no-cache curl jq
  script:
    - |
      # GitLab hands the job this repo's path for free.
      REPO_ID=$(curl -sf -H "X-API-Key: $RIFTMAP_API_KEY" \
        "$RIFTMAP_BASE_URL/repositories/lookup?full_path=$CI_PROJECT_PATH" | jq -r '.id')

      # A repo Riftmap has not scanned yet returns nothing. Skip loudly rather than pass silently.
      if [ -z "$REPO_ID" ] || [ "$REPO_ID" = "null" ]; then
        echo "Repo not in the Riftmap graph yet; skipping blast-radius check."
        exit 0
      fi

      IMPACT=$(curl -sf -H "X-API-Key: $RIFTMAP_API_KEY" \
        "$RIFTMAP_BASE_URL/repositories/$REPO_ID/impact?max_depth=3&min_confidence=0.8")

      DIRECT=$(echo "$IMPACT" | jq '[.affected_repositories[] | select(.depth == 1)] | length')
      TOTAL=$(echo "$IMPACT"  | jq '.total_affected')

      echo "Downstream consumers: $DIRECT direct, $TOTAL transitive."
      if [ "$DIRECT" -ge "$THRESHOLD" ]; then
        echo "Over threshold ($THRESHOLD): this change touches a high-fan-in repository."
      fi

That is the complete gate. It resolves the repository, asks who depends on it, counts the direct consumers, and prints the number. It makes only GET requests, so it never trips Riftmap's rate limits, which apply to writes and not reads, and it holds no cloud credentials, because the cloud was never involved. The one guard that earns its place is the empty-REPO_ID check: a repository the scan has not reached yet, and every brand-new repository is one of those, returns nothing from the lookup, and without the guard the rest of the job would quietly compute nothing and go green while printing blank counts. That is the single worst failure mode a gate can have, looking like it ran and found no exposure when it simply never ran. Skipping loudly keeps the gate honest about the one thing it is entitled to speak on, which is repositories Riftmap has actually scanned. The job then exits 0, which is deliberate. What to do with the number is the next section, and blocking the merge is the option you should reach for last, not first.

The same gate in GitHub Actions

The GitHub Actions version is the identical two calls wearing GitHub's pull-request plumbing. curl and jq are already on the ubuntu-latest runner, so there is no install step, and the repository path arrives as ${{ github.repository }}.

# .github/workflows/blast-radius.yml
name: Blast radius
on:
  pull_request:
    branches: [main]

jobs:
  blast-radius:
    runs-on: ubuntu-latest
    env:
      RIFTMAP_BASE_URL: https://api.riftmap.dev/api/v1
      THRESHOLD: "10"
    steps:
      - name: Measure downstream exposure
        env:
          RIFTMAP_API_KEY: ${{ secrets.RIFTMAP_API_KEY }}
        run: |
          # GitHub hands the job this repo's path for free.
          REPO_ID=$(curl -sf -H "X-API-Key: $RIFTMAP_API_KEY" \
            "$RIFTMAP_BASE_URL/repositories/lookup?full_path=${{ github.repository }}" | jq -r '.id')

          # A repo Riftmap has not scanned yet returns nothing. Skip loudly rather than pass silently.
          if [ -z "$REPO_ID" ] || [ "$REPO_ID" = "null" ]; then
            echo "Repo not in the Riftmap graph yet; skipping blast-radius check."
            exit 0
          fi

          IMPACT=$(curl -sf -H "X-API-Key: $RIFTMAP_API_KEY" \
            "$RIFTMAP_BASE_URL/repositories/$REPO_ID/impact?max_depth=3&min_confidence=0.8")

          DIRECT=$(echo "$IMPACT" | jq '[.affected_repositories[] | select(.depth == 1)] | length')
          TOTAL=$(echo "$IMPACT"  | jq '.total_affected')

          echo "### Blast radius: $DIRECT direct consumers, $TOTAL transitive" >> "$GITHUB_STEP_SUMMARY"

Store the key as an Actions secret named RIFTMAP_API_KEY. Same forty lines, same two calls, same read-only key. The only real difference between the platforms shows up when you want the gate to say something on the pull request rather than in the job log, which is where they diverge, and it is worth being exact about why.

The self-updating version of CODEOWNERS

The useful version of this gate does not block the merge. It routes the review. The instinct with a number and a threshold is to fail the build, and that instinct is the one thing to unlearn here, because the far more valuable job the number can do is decide who should be looking at the change.

Think about what CODEOWNERS already does for you. It routes review by path: touch files under modules/, and the platform team is added as a reviewer automatically. This gate routes review by measured downstream exposure instead: this repository currently has N repositories building on it, so a change to it deserves an owner of that shared surface on the pull request, not just whoever opened it. The difference from a hand-written CODEOWNERS line is that the number tracks the graph. A module that grows from three consumers to forty crosses your threshold on its own, the day the fortieth repository adds the dependency, with nobody remembering to edit a rule. A module that loses its consumers drops out of the lane the same way. It is CODEOWNERS that maintains itself against what is actually downstream, rather than against what someone believed was downstream the last time they touched the file.

That reframing is also why the exposure-not-breakage limit from earlier stops mattering. Routing review by exposure never needed to know whether your change was breaking. It only needs to know how many teams are downstream, because that is what makes pulling in a senior reviewer proportionate. You are sizing a coordination cost, not predicting a failure, and the count is exactly the right instrument for sizing a coordination cost.

Underneath the routing sits a policy split I proposed in an earlier post and never actually shipped. A change with no external consumers gets the fast lane, because there is nothing downstream to coordinate and speed is free. A change under the threshold passes with the consumer list posted as a courtesy, so the author knows what they are near. A change over the threshold, or one that touches a repository tagged customer-critical, engages the review lane. Amazon reached for seniority as its proxy because seniority is trivial to encode: junior author, therefore review. Downstream exposure is the proxy Amazon actually meant. A senior engineer changing a shared base image needs the extra eyes more than a junior engineer fixing a log line in a leaf service, and only the graph can tell those two apart.

Turning the number into a review is where the platforms differ. On GitHub, the built-in token does it for free. Add permissions: { contents: read, pull-requests: write } and one step:

        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          PR=${{ github.event.pull_request.number }}
          if [ "$DIRECT" -ge "$THRESHOLD" ]; then
            gh pr edit "$PR" --add-label "blast-radius/high"
            gh pr comment "$PR" --body \
              "This change affects **$DIRECT** repositories directly ($TOTAL transitively). Engaging the shared-artifact review lane."
          fi

On GitLab the merge-request notes API needs a token with api scope, and the pipeline's own $CI_JOB_TOKEN will not post notes, so store a project access token as a masked variable (GITLAB_NOTE_TOKEN) and call the notes endpoint directly:

      curl -sf --request POST \
        --header "PRIVATE-TOKEN: $GITLAB_NOTE_TOKEN" \
        --data-urlencode "body=This change affects $DIRECT repositories directly ($TOTAL transitively)." \
        "$CI_API_V4_URL/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes"

Here is what that comment looks like on a pull request to a genuinely high-fan-in repository. When Riftmap scanned Cloud Posse, terraform-null-label came back with 147 direct consumers, 61% of the whole organisation:

Blast radius: 147 repositories build on this

This change is to terraform-null-label, which 147 repositories in the organisation declare as a direct dependency. Engaging the shared-artifact review lane.

That is the comment the forty-line recipe produces from the impact call alone. Pull the consumer view for the artifact as well, the same shape the worked example in Post A returns, and the comment can carry the version detail that tells a reviewer where the coordination actually lands: of those 147, 138 are on the latest tag and 9 are lagging across six older ones. The reviewer arrives already knowing there are nine repositories to nudge onto the new version, not 147 to panic about. That is the difference between an exposure number and a coordination plan, and it is why the number is worth surfacing where a human will read it.

Those numbers are a real scan, not a hypothetical. The whole org behind them — why the 147 stays flat at depth one, where the 133 identical context.tf lines live, and what grep and a symbol graph each return for the same module — is walked through in what 242 Cloud Posse repos actually depend on.

If you do want the gate to hard-stop a merge, that is a one-line change and an opt-in, not the default. Exit non-zero over the threshold, and mark the job as a required check in branch protection or merge-request approval settings:

      [ "$DIRECT" -ge "$THRESHOLD" ] && exit 1 || true

Start with the label and the comment. Reach for exit 1 only on the handful of repositories where a large blast radius genuinely should stop the world, and even then, expect to spend a week tuning THRESHOLD before anyone trusts a red check that came from a consumer count.

One last discipline, because the neighbours are already crossing it. The open-source AWS Config gate has an ai-gate mode, and Port's guide has an LLM reason over catalogue relations and score the risk. Both are reasonable, and a written risk narrative is a genuinely nice thing to drop into a pull request. But it is a judgement, and you should not block a merge on a judgement that can vary between two runs on the same diff. The consumer count is not a judgement. It is a graph traversal that is either right or wrong about who declares the dependency, and it is the part you can safely automate a routing decision on. Gate on the enumeration. Treat the narrative as advice.

Where this gate stops

This gate sees one layer of dependency, and three kinds of blast radius sit outside it. Being exact about all three is the difference between a tool your team keeps and one they mute.

The first is the one already covered: it enumerates, it does not diff. It answers "who is downstream," not "does this change break them." You keep the false alarms down by holding min_confidence at 0.8 and, if a particular repository is noisy, by only running the job when the files that actually declare interfaces change, through paths: on GitHub or changes: on GitLab. What you never do is describe it as catching breaking changes, because it does not, and the copy that says it does is the copy that gets the tool uninstalled.

The second is freshness. The graph is a scan artifact, not live state, and a gate makes a merge decision, so eventual consistency with your scan cadence is a sharper caveat here than the same lag would be in a dashboard. State it symmetrically and it reads as engineering judgement rather than apology. Overmind and the AWS Config gate read live state, so their answer is current to the second, and they pay for it: both need cloud credentials inside the pipeline and a real plan step before they can say anything at all. Riftmap reads a graph built by a scan, so the answer is current to your scan cadence, and that is precisely why it is two GET requests with no cloud credentials in CI and no terraform plan in the job. One buys freshness with access. The other buys cheapness with lag. For a coarse routing decision on a mature shared artifact, whose fan-in barely moves week to week, the lag is not what bites you, and you can surface it explicitly anyway. Every repository the lookup returns carries last_scanned_at and last_activity_at, so keep the whole lookup payload instead of pulling out only the id, and check the two against each other:

# capture the whole lookup response, not just .id
REPO=$(curl -sf -H "X-API-Key: $RIFTMAP_API_KEY" \
  "$RIFTMAP_BASE_URL/repositories/lookup?full_path=$REPO_PATH")
REPO_ID=$(echo "$REPO" | jq -r '.id')

STALE=$(echo "$REPO" | jq 'if .last_activity_at > .last_scanned_at then true else false end')
[ "$STALE" = "true" ] && echo "Note: this repo has changed since Riftmap last scanned it; the count may be behind."

The third is scope, and it is where the honest line with the live-state tools lives. This gate is artifact-scoped and source-scoped. Overmind's is plan-scoped and runtime-scoped. Overmind sees the resource someone created in the console that your plan is about to touch, and the GitLab Blast Radius Reviewer walks the symbol graph and prunes any change with no public symbols, so it catches an exported function's callers and never sees a FROM bump at all. This gate sees the six repositories whose FROM line resolves to the image you just rebuilt, and cannot see a runtime HTTP call that no manifest declares. A serious platform team at scale plausibly wants more than one of these running side by side, because they are blind in opposite directions, and the artifact layer is the one that has been empty until now.

The pull requests nobody looks at twice

A merge gate is a bet about which mistakes are worth stopping to look at. The blast-radius gates shipping this year all make that bet on a graph, and the graph decides which mistakes the gate can even see. Bet on the live-cloud graph and you catch the console resource and miss the cross-repo consumer. Bet on the artifact graph and you catch the change your reviewer, and your coding agent, both think is safe: the FROM line, the source ref, the shared module whose consumer list nobody has counted since the person who set it up handed in their notice. And it matters more for the agent than the human, because a person opening that pull request at least half-remembers what is downstream, whereas an agent making the same change from one repository's clone knows nothing about the other repositories at all. Wire the number to a review lane, and the pull requests with the largest blast radius stop being the ones that merge with a single approval from a phone. They become the ones the right person was pulled in to see.

None of this runs until Riftmap has a graph of your organisation to answer the two calls, and that graph is the part worth having. It is one read-only token across your GitLab group or GitHub organisation, no per-repo config and no YAML catalogue to keep current, and once it exists the blast radius of any repository is a single API call. The recipe above is just the reason the scan pays for itself. And there is deliberately no Riftmap Action or GitLab component yet: the gate is forty lines you can read, own, and change, and I would rather ship that than a black box you have to trust. If you would use a maintained drop-in instead, tell me, and I will build it.

Questions engineers actually ask

How do I add a blast radius check to my CI pipeline?

Compose two Riftmap API calls in a CI job. Look the repository up by its path ($CI_PROJECT_PATH on GitLab, ${{ github.repository }} on GitHub Actions) to get its id, then call the impact endpoint to get every repository that declares a dependency on it. Count the direct consumers and comment or route on a threshold. It runs in seconds, needs only a read-only Riftmap key, and works the same whether a person or an agent opened the pull request.

How do I fail a pull request when it affects too many repos?

Set a threshold on the direct downstream consumer count, exit the CI job non-zero when a change is over it, and mark that job as a required check in branch protection. The more useful default is not to block but to route: keep the job advisory and use the number to request review from the owners of the shared surface when exposure is high. Gate on the consumer count, which is a deterministic graph traversal, rather than on an AI-generated risk score, which is a judgement that can vary between runs.

Do I need cloud credentials to check blast radius in CI?

Not for the artifact layer. Riftmap answers from a dependency graph it built during a one-off scan of your organisation, so the pipeline needs only a read-only Riftmap API key and never touches your cloud. Live-state tools like Overmind and the AWS Config based gates do need cloud access, because they read the current state of your running infrastructure at pull-request time. The trade-off is scope: the artifact graph sees cross-repo build-time dependencies, live-state tools see runtime resources including ones created outside your IaC.

Can an AI coding agent run the same blast-radius check?

Yes, and it matters more for the agent than for a human. A person opening the pull request often half-remembers what is downstream, whereas an agent making the same cross-repo change from a single repository's clone knows nothing about the other repositories at all. The same impact call gives either one the downstream consumer list before the merge, which is context the agent structurally cannot reconstruct on its own.

Can AI check the blast radius of a PR before you merge?

Daniel Westgaard — Thu, 02 Jul 2026 00:00:00 GMT

Three products shipped the same promise this quarter: see the blast radius of your change before you merge. They mean three different dependency graphs — and each is blind to a kind of breakage the others catch. Picking a tool is really picking which graph gets consulted.

In the past few weeks I have watched three different products promise the same sentence. Overmind's homepage now leads with engineers seeing the blast radius of their changes, before they merge, delivered by simulating the live cloud environment. A GitLab hackathon project shipped an MIT-licensed Blast Radius Reviewer agent to the Duo catalog that runs pre-merge cross-project impact analysis on the Orbit knowledge graph. And Port published an official guide to calculating blast radius with AI before production deploys.

So, can AI check the blast radius of a PR before you merge? Yes, if there is a dependency graph for it to query. The interesting question is which graph, because at least three different graphs are being sold under that sentence right now, and they see different changes break.

I build one of these tools, so I have an obvious interest here. I am going to try to earn your trust the boring way, by being precise about what each graph genuinely sees, where each one structurally stops, and then walking one real pre-merge check end to end on a real public organisation, with the actual API responses.

One phrase, three graphs

"Blast radius before merge" currently describes at least three products that answer three different questions. The symbol layer asks what code calls the code you changed. The live-state layer asks what running cloud resources your plan touches. The artifact layer asks which repositories build on the thing you changed. Each layer is genuinely good at something the other two structurally cannot do, and none of them is lying to you. They are just answering different questions with the same vocabulary.

I have made a version of this argument before, scoped to Terraform: Terraform blast radius is three questions, the in-config graph, the live-cloud graph, and the cross-repo graph. A pull request is a more general object than a Terraform plan. A PR can be application code, which pulls the symbol layer into the picture, and the old in-config visualisers were never pre-merge gates in any serious sense. There is also a fourth kind of graph on the market, the modeled catalog, which I will come to at the end; it is less a layer than a maintenance regime. So for the question in this post's title, the map has three territories. Here is each one, honestly.

The symbol layer: what code calls this code

The symbol layer answers "who calls, imports, or references the code symbols this diff touches", and for application code it is the right layer to ask. The most interesting recent example is that Blast Radius Reviewer agent built on GitLab's Orbit knowledge graph. It extracts the public symbols from the diff, walks direct and transitive references outward up to three hops, weights risk by hop distance, pulls in reachable security findings and ownership, and lands a recommendation on the merge request. When Orbit is unavailable it degrades loudly to single-repo search and labels the result as partial rather than pretending it saw everything. It is well built, it is free, and it is exactly what I would want reviewing a Go or TypeScript change in a GitLab-native org. I have written before about how seriously I take Orbit as a platform, and this agent is a good example of why.

Now look at the assumption stated in its own writeup: changes that touch no public symbols are pruned early, because internal-only changes cannot have a cross-project blast radius. For application code, that is a reasonable heuristic. For infrastructure, it is exactly backwards. A Dockerfile FROM line, a Terraform source block, a Helm Chart.yaml dependency, a GitLab CI include directive: none of these is a public symbol. A diff that bumps them contains nothing for a symbol graph to traverse, so the highest-blast-radius PRs in an infrastructure estate are the ones this layer scores as impactless, by design rather than by defect.

This is not a niche gap. When I counted every cross-repo edge in two real organisations, not one was a code symbol. Symbol graphs and artifact graphs are different categories, and the difference is the whole point of this post.

The live-state layer: what running resources the plan touches

The live-state layer answers "what, in the cloud that is actually running, does this Terraform plan affect", and nothing else on this list can answer that. Overmind is the serious product here. It takes the plan JSON from your PR, queries your AWS, GCP, or Kubernetes environment in real time through read-only access, and maps the affected resources plus everything that depends on them, including resources created outside Terraform entirely, through the console or CloudFormation or a script someone ran in 2021. Those click-ops resources appear in no manifest anywhere. A parser can never find them, because there is nothing to parse. If your worry is "this plan will take down something nobody wrote down", Overmind's layer is the only one that can see it, and I have a lot of respect for it.

Its structural boundary is the same thing that makes it powerful: it reasons from a plan against live state. The repositories that consume your module have not planned anything yet. When you change a shared module, the breakage does not happen in your plan. It happens later, in the plans of a hundred downstream repos, one at a time, as each of them eventually bumps. At the moment your PR is open there is no live signal in the place the damage will actually land. Overmind's graph is plan-scoped and runtime-scoped. Riftmap's is artifact-scoped and source-scoped. A serious platform team at scale plausibly wants both, and I mean that as a description of the architecture rather than as diplomacy. The full comparison is its own post.

The artifact layer: which repos build on what you changed

The artifact layer answers "which repositories declare a build-time dependency on the thing this PR changes", and in today's crop of pre-merge tools it is the question nobody else is answering. Nothing in the current wave walks Terraform source blocks, Dockerfile FROM lines, Helm chart dependencies, or CI include directives across the repositories that were never checked out. So rather than argue it abstractly, here is one real pre-merge check, end to end.

The organisation is Cloud Posse, which maintains one of the largest public Terraform module estates there is. Riftmap scanned the org on 2026-07-04 with one read-only token: 242 repositories in about twelve and a half minutes, zero errors, no per-repo configuration.

The PR we will pretend to open is against [terraform-null-label](https://github.com/cloudposse/terraform-null-label), their naming and tagging convention module. Say it is a release-prep PR for a new tag that renames an output.

Start with the two layers above, because the result is instructive. The diff touches HCL output and locals blocks, so there are no public symbols to extract; a symbol-layer reviewer prunes this change as having no cross-project impact. And the module declares no resource, data, or module blocks at all, only locals, variable, and output blocks. It provisions nothing, so terraform plan shows nothing to add, change, or destroy, and there is no live infrastructure for a plan-simulation layer to map. Both layers report, correctly by their own definitions, that this PR touches nothing.

Now ask the artifact graph:

curl -s "https://api.riftmap.dev/api/v1/repositories/{repo_id}/impact?max_depth=10" \
  -H "Authorization: Bearer $RIFTMAP_TOKEN"

{
  "source_repository": {
    "name": "terraform-null-label",
    "full_path": "cloudposse/terraform-null-label"
  },
  "affected_repositories": [
    { "full_path": "cloudposse/terraform-aws-acm-request-certificate", "depth": 1, "confidence": 1.0 },
    { "full_path": "cloudposse/terraform-aws-alb",                     "depth": 1, "confidence": 1.0 },
    { "full_path": "cloudposse/terraform-aws-alb-ingress",             "depth": 1, "confidence": 1.0 }
  ],
  "total_affected": 147,
  "max_depth_reached": 1
}

That response is real and only trimmed. 147 repositories, 61% of the org's 242 repos, declare terraform-null-label as a direct Terraform-module dependency (deduplicated, confidence ≥ 0.8, and intra-org only, a caveat I will come back to). The module that both other layers scored as impactless is the single highest-blast-radius artifact in the estate. Every one of those 147 edges sits at depth 1. This is not a deep chain amplifying a small number; it is 147 repositories importing one module directly, a module that contains no infrastructure at all, only the convention everything else is named by.

The consumers view is where the pre-merge decision actually gets made, because it carries versions:

{
  "artifact": { "artifact_type": "terraform_module", "name": "cloudposse/terraform-null-label", "consumer_count": 147 },
  "latest_version": "0.25.0",
  "consumers_on_latest": 138,
  "consumers_lagging": 9,
  "state_breakdown": { "pinned": 139, "floating": 0, "branch": 8, "absent": 0 },
  "consumers": [
    { "repository": { "full_path": "cloudposse/terraform-aws-elastic-beanstalk-application" },
      "version_constraint": "0.25.0",     "version_constraint_state": "pinned", "source_file": "context.tf", "source_line": 24 },
    { "repository": { "full_path": "cloudposse/terraform-aws-cloudwatch-flow-logs" },
      "version_constraint": "tags/0.3.1", "version_constraint_state": "branch", "source_file": "kinesis.tf",  "source_line": 2 },
    { "repository": { "full_path": "cloudposse/terraform-aws-multi-az-subnets" },
      "version_constraint": "0.24.1",     "version_constraint_state": "pinned", "source_file": "public.tf",   "source_line": 10 }
  ]
}

Notice the source_file and source_line fields. Each edge points at the exact line of the exact manifest where the dependency is declared. Nothing here is guessed. The resolver collapses three declaration forms onto the same module: Terraform-registry version pins like 0.25.0, git-tag refs like tags/0.3.1, and one raw git URL with no version at all (Cloud Posse's geodesic image, which references the module that way and sits just outside these 147 as a lower-confidence edge).

Two honest wrinkles, because precision is the product here. First, zero of the 147 consumers float a version range. Every single one hard-pins, so publishing a new tag breaks nobody at the moment of release. What the number tells you is something more useful: who has to coordinate the upgrade, and the version distribution tells you how well that coordination has gone historically. 138 consumers sit on the latest release and nine are scattered across six older tags, some dating back to the tags/0.3.x era. Not one repo floats, yet the org is still fragmented across seven distinct versions. That drift is what version constraints look like in real estates generally, and it is the evidence that "everyone pins" and "everyone is current" are very different sentences.

Second, when a consumer does bump, null-label's outputs feed resource names and tags, so the consumer's own plan can light up with renames, and at that moment, one consumer at a time, the live-state layer sees it. The artifact layer answers the question that comes before any of those plans exist: who has to open that PR at all.

There is a fashionable objection to this layer, which is that parsed manifests capture declared dependencies rather than real ones. At the artifact layer the objection dissolves, because the declaration is the mechanism. The build executes the FROM line. terraform init resolves the source block. The pipeline includes the include. There is no separate runtime truth that the manifest is a stale snapshot of; the manifest is the instruction the machines follow. Undeclared runtime calls between services are a real blind spot, and they belong to a different layer of dependency entirely, one that runtime observation is the right tool for. Which repos build on your module is not a runtime question. It is written down, deterministically, at a file and line number, in repos you have never cloned. It just is not written down in the repo the PR is in, which is why neither the agent that opened the PR nor the reviewer reading it can see it, and why inferring it with embeddings or an LLM's confidence score is the wrong tool for a merge gate.

The caveat I promised: all of these counts are intra-org. Cloud Posse's modules are used enormously across the public Terraform ecosystem, and none of that external usage appears in this scan. Within their own 242 repositories, the numbers above are exact. In the world, the true blast radius is far larger and nobody's graph sees all of it.

The full scan behind this one worked example — the cliff from 147 consumers straight down to 15, the two different hubs one repo supplying the org and another assembling it, and what grep, a symbol graph, and a catalog each return for the same module — is its own post: what 242 Cloud Posse repos actually depend on.

Where the catalogs sit

Port's blast-radius guide is real and worth taking seriously, and it works on the fourth kind of graph I flagged earlier: a modeled one. You describe your services and their relations as catalog entities, and an AI agent reasons over those relations to produce a risk score and a deployment analysis. The output is a judgement, and the graph it judges from is as accurate as the last person who updated the catalog. I have written about modeled graphs versus parsed graphs and about why hand-maintained catalogs drift toward fiction, so I will keep it to one sentence here: a modeled graph answers with the accuracy of its YAML, and an enumeration beats a judgement anywhere an enumeration is available.

The blast radius the AI reports is the blast radius of the graph

The answer to this post's title was never really in doubt. An agent can query any graph you hand it, and every product I have named will genuinely put something called a blast radius on your PR. What you are choosing when you pick one is not whether AI checks your change. It is which graph gets consulted, and therefore which category of breakage stays invisible. Symbol graphs cannot see the FROM line. Live-state graphs cannot see the repos that have not planned yet. Artifact graphs cannot see the click-ops instance someone made in the console. The teams that get this right will not be the ones that bought the best AI. They will be the ones that knew which question their estate actually needed answered, and made sure a graph existed that could answer it before the merge button did.

If your estate's risk lives where Cloud Posse's does, in the modules, images, charts, and templates that a hundred repos quietly build on, that graph is the artifact graph, and checking it from CI or an agent is one HTTP call.

This post split the graphs by which layer an edge lives on; a companion piece works the orthogonal axis, how a tool comes to know an edge exists at all, whether it is declared in a manifest, inferred from statistical signal, or registered in a catalog.

Common questions

Can AI check the blast radius of a PR before you merge?

Yes, if there is a dependency graph for it to query at PR time. The AI resolves what the PR changes, requests the set of affected consumers from the graph, and reports the result before merge. Without a graph, an AI reviewer only sees the repository the PR is in, so cross-repo blast radius stays invisible until something breaks downstream. The practical question is which graph it queries: symbol graphs see code references, live-state graphs see running cloud resources, and artifact graphs see which repositories build on the changed artifact.

What tools show blast radius on a pull request before merge?

Three kinds, by layer. Symbol-layer tools like Sourcegraph and GitLab Orbit (including the open-source Blast Radius Reviewer agent) trace which code references the symbols in a diff. Live-state tools like Overmind simulate a Terraform plan against real-time AWS, GCP, or Kubernetes state and comment the affected resources on the PR. Artifact-layer tools like Riftmap enumerate the repositories whose manifests (Terraform source blocks, Dockerfile FROM lines, Helm dependencies, CI includes) consume what the PR changes. They answer different questions, and infrastructure-heavy estates usually need the third.

Does Claude Code or Cursor know the blast radius of a change?

Not on their own. Coding agents see the repository they have cloned or indexed, so a change to a shared module, base image, or CI template looks safe because the consumers live in repos the agent never opened. Given a queryable dependency graph, though, an agent can check blast radius at planning time with one API call and get the affected repositories back before it opens the PR. The agent is not the limitation; the missing graph is. More on that in which AI coding assistants can see blast radius before they change code, where Claude Code, Cursor, and Copilot are each measured against this exact question.

Is blast radius analysis deterministic or AI-generated?

It depends on the layer, and honest tools are clear about which parts are which. Graph traversal is deterministic: "147 repositories declare this module at these file and line numbers" is an enumeration, and it is either right or wrong. Risk narratives, severity scores, and deployment recommendations are judgements, usually LLM-generated, layered on top of whichever graph the tool has. A reasonable rule for merge gates: gate on the enumeration, treat the narrative as advice.

You can index every repo in Cursor. It still can't tell you what breaks.

Daniel Westgaard — Wed, 01 Jul 2026 00:00:00 GMT

How to tune Cursor's codebase index for a large monorepo or a multi-repo workspace — and the one question no amount of tuning makes it answer.

Open a monorepo of any real size in Cursor and the first thing you meet is the indexing bar, and the first thing you learn is that it can take a while. A repository in the tens of thousands of files can sit there for a long time if you point Cursor at the root and walk away.

So you do the sensible thing. You read the docs, you write a .cursorignore, you open the package you actually work in instead of the whole tree, and the bar that took an age now takes a minute. @Codebase gets faster and sharper. This is real work, it is worth doing, and most of this post is how to do it well.

Then, one afternoon, you are about to change something shared. A base image half the org builds on. A module three Terraform stacks call. A contract package a dozen services import. And you ask the fast, well-tuned index the one question that actually matters before you press go. What breaks. And the answer comes back confident, and quick, and wrong in a way you cannot see.

Here is the claim this post runs on. You can tune Cursor's index to cover a fifty-repo workspace and make @Codebase genuinely fast and useful, and it still will not tell you which repositories break when you change a shared module, because the index answers similarity and a declared dependency is not a similarity relationship. Everything up to that ceiling is worth doing, and I will spend most of the post doing it. The ceiling itself is real, and no amount of tuning moves it, because it was never a tuning problem.

There is a version of this post all over the internet right now, and most of it is good. The best one I have read walks multi-repo workspaces and per-service .cursorignore files carefully and calls the result a microservices graph explorer. I want to be fair to that framing, because the tuning it describes is correct and I am about to repeat a fair amount of it. But "the index spans all my services" and "the index maps how my services depend on each other" are two different claims, and the distance between them is the whole second half of this post. I have made the structural version of that argument before, and shown how to wire the missing graph into Claude Code and Cursor. This one starts somewhere more practical. It starts with your index actually being slow.

What Cursor's index actually is

Cursor's index is a semantic search index, and knowing that precisely is what makes the rest of this post make sense. When you open a workspace, Cursor splits your code into chunks along syntactic boundaries, runs each chunk through a custom embedding model to get a vector, and stores those vectors in a remote vector database built on Turbopuffer, keyed by an obfuscated path and line range. Your source is not kept server-side. Only the embeddings and masked metadata leave your machine, and the chunks are decrypted on the client when the agent needs them. A Merkle tree tracks which files changed so re-indexing only touches what moved, and the index syncs roughly every five minutes.

When you search, your query becomes a vector too, and Cursor returns the chunks whose vectors sit nearest yours. That is what @Codebase is underneath. Nearest-neighbour search over embeddings. The official description is exact about it: it returns the most semantically similar code, even when the matching chunk does not contain the words you searched for. Cursor's own evaluation puts semantic search at around 12.5% more accurate than grep alone on large codebases, with the gain growing as the codebase grows, and that is a real result I have no interest in talking down.

In 2026 this got more capable, and it is worth being current about, because the workflow changed. You mostly do not type @Codebase any more. Cursor's Agent picks the search strategy itself, combining a fast custom grep it calls Instant Grep with semantic search, and it can spawn an Explore subagent that runs many searches in parallel without bloating the main context. Cursor's own line is that you do not choose the tool, you describe what you need and the Agent decides. This is a genuine improvement. But notice what did not change underneath the sophistication. Instant Grep matches strings. Semantic search matches meaning. Both are ways of finding text that resembles other text, and neither resolves a reference in one repository to the artifact another repository builds. The agent got much better at choosing which kind of resemblance to look for. It did not gain a new kind of edge to look over.

Tuning the index for a large or multi-repo codebase

The single lever that matters most on a large codebase is how much you ask Cursor to index, because both indexing cost and query noise scale with file count. Cursor's own numbers are blunt about the cost: a large repository indexed naively can take hours to reach its first query, and on the largest repos the ninety-ninth-percentile time-to-first-query is over four hours before their teammate-index-sharing trick kicks in, with semantic search unavailable until the index is at least 80% built. One monorepo tutorial clocks an 8,800-file repo at seven to twelve hours from the root, cut to minutes with the right exclusions. Everything below is a way of pointing the index at the code that is load-bearing for your task and keeping everything else out of it. Do them in roughly this order.

Scope the index: open the package, not the root

The highest-leverage move on a monorepo is to not open the monorepo. Opening a package directory as the workspace root makes Cursor treat that directory as the whole codebase and index only within it, and on a large tree that is the difference between a minute and several hours.

# Indexes everything under the root, slowly
cursor /path/to/monorepo

# Indexes one package, fast
cursor /path/to/monorepo/packages/api

A shell alias per package you live in (alias ca='cursor /path/to/monorepo/packages/api') makes this frictionless. The cost is that references outside the package are no longer in the index, which is fine right up until your task actually crosses a package boundary, and then it is precisely the problem the second half of this post is about.

The two ignore files, and which one you actually want

Cursor has two ignore files and they do different jobs, and mixing them up is the most common configuration mistake I see. .cursorignore is a complete block: a file listed there is not indexed, not read, and not available even when you @-mention it, as though it did not exist. .cursorindexingignore is narrower: it keeps a file out of the index and out of search results, but the file stays readable, so you can still pull it in with @Files when you genuinely need it.

The practical rule the field has settled on is short. Reach for .cursorindexingignore first, because it is the reversible choice, and promote a path to .cursorignore only when the AI should never see it, like a secret.

# .cursorindexingignore
# Kept out of the index, still reachable with @Files.
tests/fixtures/
e2e/recordings/
packages/legacy/

# .cursorignore
# Invisible to indexing AND to all AI features.
.env*
secrets/

There is one detail in Cursor's default indexing exclusions worth knowing, because it is quietly on-topic. Cursor already skips lockfiles by default, package-lock.json, yarn.lock, go.sum, and the rest. Those are the files that record the exact resolved version of every transitive dependency, which is to say the single most precise dependency information in your repository is the first thing the index throws away. It throws it away for sensible reasons, lockfiles are enormous and read as noise to a similarity search. Hold onto that, though, because it is a small preview of the larger point. The index is tuned to find code that reads like your question, and dependency records do not read like anything.

Multiple repositories: the multi-root workspace

For genuinely separate repositories, rather than packages in one tree, Cursor supports multi-root workspaces. A .code-workspace file lists several folder roots, Cursor indexes all of them, and Agent can reach across the set. A workable pattern for a large estate is to group repositories into a few workspace files by domain, payments with identity with the API gateway in one, catalogue with search with recommendations in another, and switch between them rather than opening everything at once. One caveat to know going in: features that assume a single git root, like worktrees, are disabled in a multi-root workspace.

Done well, this is genuinely useful. Open web-app, orders-service, and the shared contract repo together, and "how does the orders service validate a token" becomes one question instead of four context switches. This is the setup the multi-repo guides call a microservices graph explorer, and I understand why they reach for it. When every service sits in one index, @Codebase stops being a single-service lookup and starts answering questions that range across the whole set.

But the word doing too much work in "microservices graph explorer" is graph. The index now spans your services. It does not map them. It can surface the code in orders-service that mentions the contract, and the code in the contract repo that defines it, because both are text and both might resemble your query. What it cannot do is tell you that orders-service declares a dependency on that contract, and that billing-service, which you did not open, declares one too. Spanning a set of repositories and mapping the edges between them are different operations, and the index only performs the first one.

Project rules and hierarchical ignore

Project rules and hierarchical ignore are two smaller levers worth setting. Rules live in .cursor/rules/*.mdc now, one or more files that describe your architecture and conventions and load into context by relevance. If you are still carrying a root .cursorrules file, note that it is legacy and ignored in Agent mode, so migrating it is overdue. Rules are where you tell the agent how the monorepo fits together and which boundaries not to cross, and they do help. Notice, though, that they help by you writing the structure down, which makes them a hand-maintained description with the same decay problem every written map has: the description is only as current as the last engineer to update it, and it drifts from the code at exactly the speed the code changes.

Hierarchical Cursor Ignore, a setting rather than a file, lets Cursor walk up parent directories collecting .cursorignore files, so you can keep a global exclusion set at the root of a large monorepo and let each package layer its own on top. It is the right tool for keeping a big tree's index configuration from repeating itself.

The freshness you're actually working with

Cursor's index is as current as your checkout, and no more, and it is worth being honest with yourself about what that means. The index reflects the files on your disk. It does not pull your colleagues' commits, so a function a teammate added to the identity service this morning is not in your index until you pull and Cursor re-indexes the file. And even for your own work the index trails the actual files by a sync interval. The consequence is a clean line: the index is reliable for the stable shape of a system, and unreliable for the change that landed an hour ago in a repository you did not open. Both of those are outside it. Keep that boundary in mind, because it compounds with the one the next section is about.

The question a tuned index still can't answer

A perfectly tuned Cursor index still cannot tell you which repositories break when you change a shared module, because it answers similarity and a cross-repo dependency is a declared edge, not a similarity relationship. Do all of it. Scope the index to the package, split the workspace by domain, get the file count into the low thousands, write the rules, keep it fresh. You now have a fast, lean, accurate semantic index across every repository you care about, and @Codebase is as good as it gets. Now ask it the question you opened this whole workflow to answer. You are about to bump a base image, retire a shared module, or change a contract. Which repositories break.

Here is what happens, concretely, and you can check me on it because the org is public. Take the Prometheus organisation: as of Riftmap's May 2026 scan, fifty-six repositories, and when you parse the dependency edges between them, a hundred and eighty-eight cross-repository edges. A handful of repositories carry most of it, prometheus/common with twenty-five dependents, client_model with twenty-four, procfs with twenty-three, client_golang with twenty-two. (Those counts drift a little between scans, which is exactly why they are dated here; the live showcase always renders the current number.) Clone all fifty-six, open them in one immaculately tuned Cursor multi-root workspace, wait for the index to finish, and ask @Codebase: what depends on client_golang.

You will get chunks. Files that mention client_golang, code that resembles your query, the definition itself. What you will not get is the list of twenty-two repositories that declare a require on it, because that list is not a similarity relationship. It is twenty-two go.mod files, in twenty-two repositories, each with a line naming client_golang and a version. A go.mod require line and the client_golang source it points at share almost no tokens, nothing an embedding would place near the other. The edge is not latent in the text, waiting to be retrieved. It was declared once, in a manifest, and it is either parsed from that manifest or it is not found.

And it is finer than a repository count, which is the part that should give you pause before a change. The same scan finds prometheus/common required twice from prometheus/prometheus alone, two separate manifests in one repository, each naming common with its own version, and the graph tracks them as two references rather than folding them into a single repo-to-repo edge.

"We bumped the dependency" and "we bumped every reference to the dependency" are different statements, and Go monorepos are exactly where that difference hides. A parser surfaces each of those references as its own edge, because it read each manifest and knows how many there are. A similarity index has no concept of "the second go.mod that requires this". It has chunks, ranked by resemblance, and resemblance was never going to count references in files it treats as prose.

This is not a tuning failure, and that distinction matters. There is no .cursorignore you could write, no workspace split, no rule, that turns a nearest-neighbour search into a dependency resolver. The index is answering the question it was built to answer, which is "what code resembles this", and it answers it well. The question a breaking change asks is "what declares a dependency on this", and that is a different question with a different data structure behind it. You cannot tune your way from one to the other, because they were never the same machine.

The graph that answers it is parsed, not tuned

The edges the index can't retrieve are not missing, they are declared in the manifests you already have, in constructs built for exactly this. The contract in a go.mod require or a package.json dependency. The module in a Terraform source block. The image in a Dockerfile FROM. The chart in a Chart.yaml dependency. The template in a GitLab CI include:project or a reusable Actions uses:. I spent a whole series walking those one ecosystem at a time. They are deterministic. Parsed, not inferred. The dependency graph across your organisation already exists, declared and unassembled, in files a similarity index reads as text and a parser reads as edges. This is the difference between inferred context and a dependency graph, and tuning the index is orthogonal to it: a better index is a better answer to a different question.

Riftmap is that graph. It parses those manifests across your entire GitHub or GitLab organisation from one read-only token, resolves each reference to the repository that owns the artifact, and returns the answer the index can't, every repository that depends on the thing you are about to change, with the version each one declared. It is the Prometheus graph above, for your own org. If you want that graph in front of the agent rather than in a browser tab, wiring it into Cursor and Claude Code is its own post, because the graph is useful to the engineer holding the pager first and the agent second. Either way it is the same move. Stop asking a tool built for resemblance to answer a question about dependency, and hand over a graph that was parsed for exactly that.

Tune Cursor's index until it is perfect and you have made it excellent at finding the code that resembles your question. The repositories that break when you change a shared module were never going to resemble your question. They were a set of FROM lines and require blocks and source references, declared once across repositories you may not have even opened, waiting to be read. The index reads them as text. You need something that reads them as edges.

Questions teams ask

The same questions come up whenever I help someone tune this, so here they are, answered straight.

How do I speed up Cursor indexing on a large monorepo? Index less. A repository in the tens of thousands of files can take hours to index from the root, so the highest-leverage move is to open the package you work in as the workspace root rather than the whole tree. Add a .cursorignore for build output, dependencies, and generated files, aim for a few thousand indexed files rather than tens of thousands, and use .cursorindexingignore for large directories you still want to @-mention occasionally. Most slow-index complaints come down to indexing node_modules and vendored code nobody needed in the index in the first place.

Should I use .cursorignore or .cursorindexingignore? Use .cursorindexingignore unless the AI should never see the file at all. .cursorindexingignore keeps a file out of the index and out of search results but leaves it readable, so you can still pull it in with @Files, which makes it the reversible, lower-risk choice for large or noisy directories. Reserve .cursorignore for things that must be fully invisible, like secrets or files you never want referenced, because it blocks reading and @-mentioning as well as indexing.

Does Cursor's @Codebase understand dependencies between repositories? Not in the sense a breaking change needs. @Codebase is nearest-neighbour search over an embedding index, so it returns the code most similar to your query, which is a different set from the repositories that declare a dependency on what you are changing. A go.mod require line, or a Dockerfile FROM, and the repository it points at are not similar text, so no similarity search reliably connects them. Indexing more repositories widens what @Codebase can resemble against, but a cross-repo dependency edge has to be parsed from a manifest, not retrieved by similarity.

Can Cursor index multiple repositories at once? Yes. A multi-root workspace, defined in a .code-workspace file, can hold several repository roots, and Cursor indexes all of them and lets Agent search across the set. That makes @Codebase span your repositories, which is genuinely useful for understanding a system. It does not make the index map how those repositories depend on each other, which is a separate thing that comes from parsing manifests rather than from a wider index.

Claude Code reads your clone. Cursor reads similarity. Neither sees the graph.

Daniel Westgaard — Tue, 30 Jun 2026 00:00:00 GMT

Both agents can be handed more than one repository. Here is how to wire cross-repo blast radius into each, and the exact point where Claude Code's clone and Cursor's index each stop.

You have Claude Code open in one repository and Cursor in another. The task in front of you is small, and the kind agents are good at. Bump a base image. Tighten a variable on a Terraform module. Delete a CI job that you are fairly sure three other projects still call. Before you let the agent run, you want the one thing it cannot tell you. Who else breaks.

Both tools have a multi-repo story now, so it feels like a question they should be able to answer. Claude Code has /add-dir and native MCP. Cursor indexes an entire workspace and answers questions about it. You could be forgiven for assuming that somewhere in there is a feature that knows your orders-service consumes the contract you are about to change. There is not, and the reason is different for each tool. Knowing exactly where each one stops is the difference between wiring up something that genuinely helps and trusting something that quietly does not.

So here is the claim this post runs on. Claude Code and Cursor can both be handed more than one repository, and neither can tell you which repositories a base-image or Terraform change will break, because Claude Code only sees the repositories you checked out, and Cursor's index answers similarity, not dependency. The edge that breaks the other repo was declared in a manifest, and a manifest is neither a file the agent cloned nor a chunk that embeds near your query.

I have covered the Copilot version of this question before, and made the case for why this blindness is structural rather than a gap a smarter model closes. This is the Claude Code and Cursor version, and it gets concrete about the wiring.

What each agent can actually see today

What Claude Code and Cursor can see across repositories is different for each, and it moves fast enough that this section carries a date. As of June 2026, here is the precise shape of it.

Claude Code sees the directory you started it in, recursing up the tree to load any CLAUDE.md it finds along the way. You extend that reach with the --add-dir flag, the /add-dir command, or permissions.additionalDirectories in .claude/settings.json. It reads and greps those trees, and it can edit them. What it does not do is hold a dependency graph of them. Add MCP servers and it gains tools that can. So Claude Code's cross-repo reach is exactly the set of directories you granted, navigated by reading and search, plus whatever tools you wired in.

Cursor's reach is its index. It chunks your code, embeds each chunk with a custom model, and stores the vectors in a remote vector database, and @Codebase answers by finding the chunks whose embeddings sit nearest your query. Multi-root workspaces are supported, so several repositories can be indexed at once and Agent can reach all of them. The index covers the repositories you opened, it trails your local checkout by a sync interval, and it answers by similarity.

Notice what both give you. A way to put more repositories in front of the agent. Notice what neither gives you. A way to turn "the agent can see these repositories" into "the agent knows how these repositories depend on each other." That second thing is the whole post, and the rest of it is, first, why each tool stops short of it, and then how to hand each tool the part it is missing.

Claude Code: widen the window, write the map, add the tool

Claude Code gives you three ways to reach across repositories, and they map cleanly onto the three families every agent's users reach for, in roughly this order. Each one solves a real problem. The first two stop at the same wall, and the third is where the fix actually goes.

Widen the window with /add-dir

The first instinct is access, and Claude Code makes it cheap. --add-dir at launch, /add-dir mid-session, or permissions.additionalDirectories in .claude/settings.json to make a set of sibling directories part of the project so everyone working in that area gets them.

# At launch
claude --add-dir ../orders-service --add-dir ../platform-charts

# Or permanently, in .claude/settings.json
{
  "permissions": {
    "additionalDirectories": ["../orders-service", "../platform-charts"]
  }
}

Each granted directory becomes readable and editable, and as of a recent version Claude Code can even load the CLAUDE.md from an added directory if you set CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1. At a handful of tightly coupled repositories, with someone keeping the set current, this is the right first move and it costs an afternoon. I want to be fair to it before drawing the line.

The line is that access is not selection. You chose which directories to add, and you chose them from memory. Nothing in /add-dir tells you that a third repository consumes the same contract and is not in the set at all. And the failure that bites hardest is quieter still. You can only add a directory that exists on your disk, so the repository you forgot to clone is not a directory you can add. Widening the window shows the agent more rooms. It does not hand it the floor plan, and I made the longer version of that argument in Repo access was never the hard part.

Write the map in CLAUDE.md

The second instinct is to write the structure down. This is the CLAUDE.md and AGENTS.md layer, files loaded at session start and held for the whole session, layered enterprise, user, and project deep, that describe how the system fits together. More than sixty thousand repositories now carry one. The most documented version is Mabl's, an 850-line coordination graph their agents query at planning time, and it works.

It also decays, and the engineers writing these files know it. The sharpest line I have read on the pattern comes from someone who layered the files org, team, and repo deep and concluded: "I learned not to list repos here. Lists go stale. Instead, tell Claude where to look." That is the trap in one sentence. A hand-written map has to be kept current by humans at the same throughput the agents are changing the repositories, and an agent navigating by a stale map does not feel stale. It feels fast, right up until the change lands. A map that decays is the developer-portal catalog problem wearing new clothes, and it loses to the same thing: a graph parsed from the source, which cannot drift from the source because it is read from it.

Add the graph as an MCP tool

The third instinct is the right one. Stop describing the structure and hand the agent a tool that holds it. MCP is native to Claude Code, configured with claude mcp add or a committable .mcp.json at the project root, and this is where the fix belongs.

The catch is what is usually on the other end of that tool call. Most of what you can plug in here is a symbol index or a semantic one. It follows imports and call edges, or it embeds your code and retrieves by similarity. Both stop at the language boundary, the same wall I walked in the flagship: a symbol graph answers "who calls this function" and never sees a FROM line. The tool Claude Code actually needs at this layer is one that resolves a Dockerfile FROM to the repository that builds the image, and a Terraform source to the repository that owns the module. That tool is an artifact graph, and wiring it in is the back half of this post.

Cursor: the index is the context model, and it answers the wrong question

Cursor's cross-repo story is its index, and the index is built to answer a different question than the one a breaking change asks. This is the part worth slowing down on, because Cursor is genuinely good and the distinction is easy to miss.

Here is how it works. Cursor splits your code into chunks, runs each chunk through an embedding model to get a vector, and stores those vectors in a database. When you ask @Codebase something, your question becomes a vector too, and Cursor returns the chunks whose vectors sit nearest yours. The official description is exact about this: it returns the most semantically similar code chunks, even when they do not contain the keywords you used. Across a multi-root workspace it does that over every repository you opened.

I want to be generous here, because it deserves it. Semantic search is a real improvement over grep. Cursor's own research puts it at around 12.5% more accurate on large codebases, and the gain grows with size. Open web-app, orders-service, and the shared contract repo in one workspace, and "how does the orders service validate a token" becomes one question instead of four context switches. For understanding a system, exploring it, finding where a concept lives, it is excellent, and nothing below is a knock on that.

The line is that semantic search returns the code most similar to your query, and a declared dependency is not a similarity relationship. A Dockerfile line that reads FROM platform/base-go:1.21 and the repository that builds platform/base-go share almost no tokens, no structure, nothing an embedding would place near the other. The edge between them is not latent in the text, waiting to be retrieved. It was declared once, in a manifest, and it is either parsed from that manifest or it is not found.

Ask @Codebase "what depends on this base image" and you get the files that mention base images, which is a different set from the repositories that inherit this one. This is the difference between inferred context and a dependency graph, and it is sharpest exactly where Cursor is most loved.

Two more limits sit underneath that one, and they bite even if you set the similarity question aside. The index covers only the repositories you opened in the workspace, and someone chose that .code-workspace folder list, from memory, which is the catalog trap again in a different file. And the index trails your checkout by a sync interval, so by Cursor's own guidance it is reliable for stable architecture and unreliable for recent change. The repository you did not open and the push from this morning are both outside it. Cursor indexes what looks related. The thing you need before a base-image bump is what is declared dependent, and those are different graphs built by different machinery.

The wall both share, and the graph that clears it

Widen the window, write the map, or index the workspace, and you reach the same wall from three directions. /add-dir gives access without selection. CLAUDE.md gives structure that decays. The index gives similarity, never the declared edge. None of them resolves a source block to the repository that owns the module, because that was never the job any of them was built to do.

	How it reaches across repos	What that answers well	What it can't resolve
Claude Code	Reads the directories you grant it with `/add-dir`	Anything inside a repository you checked out	Which repositories a change affects, and any repo you didn't clone
Cursor	Semantic search over an embedding index of the open workspace	"Where does this live", "how does this work"	A declared dependency, which is not a similarity relationship

But the edges that matter are already written down. The contract package in a package.json dependency or a go.mod require. The module in a Terraform source block. The image in a Dockerfile FROM. The chart in a Chart.yaml dependency. The template in a GitLab CI include:project or a reusable Actions uses:. I spent a whole series walking those edges one ecosystem at a time. They are deterministic. Parsed, not inferred. The graph that should be answering the agent's question already exists in your organisation's manifests, unassembled. The rest of this post is assembling it once and wiring it into Claude Code and Cursor.

Wiring the graph into Claude Code and Cursor

A cross-repo dependency graph helps either agent in three ways, and they are worth doing in order, because each one is more setup and more enforcement than the last. The graph here is Riftmap, which parses these edges across your whole GitHub or GitLab organisation from one read-only token and serves the result over an HTTP API. You can adopt the same architecture with any parsed graph, including one you build yourself.

Tier one: let the agent call the API

The simplest version works today and installs nothing. Tell the agent the graph is an HTTP call, and let it make the call with the shell tool it already has. The recommended pattern is three endpoints. Resolve the working tree to a node, hydrate that node's context in one round-trip, and ask for the transitive cascade when the change actually warrants it.

# Resolve the working tree's clone URL to a Riftmap repo
REPO_ID=$(curl -s \
  "https://api.riftmap.dev/api/v1/repositories/lookup?url=https://github.com/myorg/platform-charts" \
  -H "X-API-Key: $RIFTMAP_API_KEY" | jq -r '.id')

# One round-trip: the repo, its dependencies, its dependents, its artifacts
curl -s "https://api.riftmap.dev/api/v1/repositories/$REPO_ID/context" \
  -H "X-API-Key: $RIFTMAP_API_KEY"

# When the change is breaking, ask for the transitive blast radius
curl -s "https://api.riftmap.dev/api/v1/repositories/$REPO_ID/impact?max_depth=3" \
  -H "X-API-Key: $RIFTMAP_API_KEY"

To make the agent reach for this without being reminded each time, put the instruction where it already reads. A line in CLAUDE.md for Claude Code, a rule in .cursor/rules/ for Cursor, along the lines of: before planning any change to a shared artifact (a base image, a Terraform module, a Helm chart, a CI template), call the Riftmap API to list the dependents and fold them into the plan.

This is not theoretical. I have a recorded Claude Code session doing exactly this. The prompt asks it to delete a helm:deploy job, because Helm deploys are moving into an umbrella chart, and to flag who would break. The agent calls the API on its own, surfaces 51 consumers across the organisation, and sorts them by whether they pin a release tag, and so have a grace period, or float on main, and so break on the next pipeline run. It can make that distinction because every dependency edge the API returns carries the version_constraint the consumer declared. It also flags, unprompted, a caveat about the granularity of one edge, which is the kind of self-correction you want from an agent about to make a breaking change. That is the entire point. The structural account is in front of the agent before the first edit, not discovered in CI twenty minutes later.

Tier two: make it a first-class tool with MCP

Calling curl from a prompt works, but the agent has to be told the shape of the call each time, and the call lives in your instructions rather than in the tool list where it belongs. Both Claude Code and Cursor are MCP clients, so the more native option is to expose the graph as MCP tools.

Riftmap does not ship its own MCP server yet, and the reason is worth stating plainly, because it is the honest one: the endpoints are the load-bearing piece, packaging them is mechanical, and the build is being held until real users ask for it rather than designed for a workflow nobody has yet. If you want it, the roadmap page takes an issue, and concrete demand is what unblocks it.

Until it lands, you bridge in about five minutes, because Riftmap publishes a static OpenAPI schema and there are mature generators that turn any OpenAPI spec into an MCP server. Point one at the schema, give it the API base and your key, and the three endpoints become tools the agent sees in its tool list. For Claude Code, in a committable .mcp.json at the project root:

{
  "mcpServers": {
    "riftmap": {
      "command": "npx",
      "args": ["-y", "@ivotoby/openapi-mcp-server"],
      "env": {
        "OPENAPI_SPEC_PATH": "https://app.riftmap.dev/openapi.json",
        "API_BASE_URL": "https://api.riftmap.dev/api/v1",
        "API_HEADERS": "X-API-Key:${RIFTMAP_API_KEY}"
      }
    }
  }
}

Cursor reads the same mcpServers format, so the identical block drops into .cursor/mcp.json, with one change: Cursor's variable syntax for the key is ${env:RIFTMAP_API_KEY} rather than ${RIFTMAP_API_KEY}. One detail in that config is worth knowing rather than copying blind. The schema is served from app.riftmap.dev and the API answers on api.riftmap.dev, which is why the base URL is set explicitly instead of being inferred from the spec's own host.

With either client, "who depends on platform-charts" is now a tool call the agent makes itself, in Plan Mode or mid-task, with no HTTP in the prompt. When Riftmap's own server ships it will be a thinner version of the same thing, pipx install riftmap-mcp against the same endpoints, and switching to it is a config line.

Tier three: make it a gate, not a hint

A tool the agent may call is still a tool the agent may skip. For the highest-stakes changes you want the graph between the change and main, not merely available to the planner. There are two honest places to put it.

In the loop, Claude Code runs hooks, skills, and subagents. A skill the agent invokes during planning, or a check on the commit boundary, can make the dependents query a step that has to happen before a change to a shared artifact proceeds. This keeps the graph in the agent's path rather than its discretion, though it depends on the agent's cooperation to fire.

At review, the cleaner gate is CI, because it does not depend on the agent cooperating at all. On any pull request that touches a shared component, the pipeline calls /impact, posts the consumer list as a comment, and the human reviewing the agent's change is checking it against the same structural account the agent planned with, not against memory. This is the architecture I think the whole category lands on, and it is the one Mabl built by hand before running agents across a hundred repositories on top of it.

What makes either gate trustworthy rather than confidently wrong is the freshness contract. Every repository the API returns carries last_scanned_at and last_activity_at, and the single rule is that if the repository has been pushed to since Riftmap last scanned it, the graph is treated as stale. For an interactive agent that means warn and proceed with the caveat. For a CI gate it means trigger a rescan and re-poll before the merge. A gate that knows when it is out of date is the opposite of the stale CLAUDE.md that feels fast right up until it is wrong.

The graph you hand the agent, not the one it tries to infer

Give Claude Code every repository you have checked out, and give Cursor an index of all of them, and you have given each agent a faster way to read what is already in front of it. You have not given either one the list of repositories that break when it bumps the base image. That list was never a file Claude Code could clone or a chunk Cursor could embed. It was a set of FROM lines and source blocks sitting in repositories the agent never opened, declared once and never assembled. The agent cannot infer it, because it was never there to infer. It has to be parsed and handed over.

Riftmap is that graph, built from one read-only token across your GitHub or GitLab organisation. It parses the manifests that already declare these edges across twelve ecosystems and resolves each reference to the repository that owns the artifact, then serves the result two ways. An interactive blast-radius view for the engineer who owns the estate and holds the pager, and an HTTP API, three endpoints with an OpenAPI schema and a freshness field on every response, that Claude Code and Cursor can call during planning, or that you can put in front of a merge. Auto-discovered, never catalogued. Parsed, not inferred. The MCP server is coming when enough people ask. Until then it is one config block away.

Questions teams ask

The same questions come up whenever I help someone wire this in, so here they are, answered straight.

How do I give Claude Code cross-repo dependency awareness? Claude Code sees the repositories you grant it with /add-dir and reads them, but it does not build a dependency graph across them. To give it cross-repo blast radius, expose a parsed dependency graph as a tool it calls during planning. Either let it call the Riftmap HTTP API from its shell, resolving the repo with lookup and then asking for context or impact, or wrap the OpenAPI schema as an MCP server in .mcp.json. Then it can ask which repositories a change affects before it edits.

Does Cursor's @Codebase understand cross-repo dependencies? Not in the sense a breaking change needs. @Codebase is semantic search over an embedding index, so it returns the code most similar to your query, which is a different set from the repositories that declare a dependency on what you are changing. A Dockerfile FROM line and the repository that builds that base image are not similar text, so no embedding search reliably connects them. Cross-repo dependency edges have to be parsed from manifests, not retrieved by similarity.

Can I add a Riftmap MCP server to Claude Code or Cursor? Not a first-party one yet. It is on the roadmap, deferred until there is real demand. Today you bridge in a few minutes: Riftmap publishes a static OpenAPI schema at app.riftmap.dev/openapi.json, and a generic OpenAPI-to-MCP server turns it into MCP tools you register in .mcp.json for Claude Code or .cursor/mcp.json for Cursor. Or skip MCP entirely and have the agent call the three HTTP endpoints directly.

Why doesn't /add-dir tell Claude Code which repositories a change affects? Because /add-dir grants access, not selection. It makes the directories you name readable and editable, but you chose those directories from memory, and it cannot add a repository that is not checked out on your disk. Knowing which repositories to add is the cross-repo dependency question itself, and that answer comes from a parsed graph, not from a wider window.

The repo your agent didn't clone is the one it breaks

Daniel Westgaard — Mon, 29 Jun 2026 00:00:00 GMT

Coding agents got cross-repo access this year. They still cannot see the blast radius of a base-image bump — because that edge was never a function call, and it lives in a repo they never opened.

Last spring someone posted a small VS Code extension to Hacker News. The pitch was one sentence from their own week. They had added a single field to a shared struct, and found out in CI, twenty minutes later, that 417 files depended on it. So they built a tool that shows you that tree the moment you save, files colour-coded by how far downstream they sit. It is a good tool. Underneath it is a Rust CLI and tree-sitter, parsing your code into a graph of which file references which.

Read that story again and notice what kind of dependency it actually is. A field on a struct. Files that reference the struct. Functions that call those functions. It is a symbol graph, it lives inside one repository, and tree-sitter can see all of it. This is the version of blast radius the industry has largely tooled. Sourcegraph indexes it. CodeLayers draws it on save. GitLab's new Knowledge Graph answers it over MCP. The most-quoted blast-radius anecdote on the internet is a within-repo, symbol-level story, answered by within-repo, symbol-level tools.

Now hand the same engineer their next task, and hand it to an agent. Bump the base image three services are built on. Tighten a variable on a Terraform module that six repositories source. Rename a value key in a Helm chart that nine deployments inherit. The thing that breaks is real, and it is downstream, and it is not 417 files in this repository. It is eleven services in eleven other repositories, owned by teams who never read the changelog. And the edge that connects the change to the breakage was never a function call. tree-sitter will never find it. It was never in the code. It only ever existed in a manifest, in a repository the agent did not clone.

So here is the claim this whole post is built on. An AI coding agent can see the repository it cloned. The edges that break when a shared base image, Terraform module, or Helm chart changes live in other repositories, declared as a Dockerfile FROM line or a Terraform source block, which means they sit outside the agent's context by construction, not by oversight. You cannot prompt your way past it. You have to give the agent the graph.

The agents' own users have already asked for this

The clearest evidence that this is the live problem is that the people running these agents are filing the feature request themselves, in the agents' own issue trackers, in their own words. In February someone opened a request on the Claude Code repository for multi-repository sessions. The interesting part was not the ask. It was the reasoning. The author wanted the agent to discover additional repositories as it works, "via dependency analysis, import tracing, or configuration references", because, in their words, "I don't always know which repos are affected when I start the task." Their example stack was a shared API-contracts library, a Node backend, a React frontend, and a Kubernetes infrastructure repository.

It is not one request. There is a second one that wants the agent to see the API handlers in backend/, the types they share with frontend/, and the Terraform definitions in infra/, and to trace a payment flow end to end across all of them. There is a third asking for a --workspace flag so a single session can coordinate a change to an API in one repository and its client in another. And over on the GitHub side there is the Copilot request I have written about before, the web-app and orders-service pair where Copilot cannot detect that the frontend is calling an endpoint the backend just renamed, because the contract lives in a repository outside its scope.

Four requests, three agents, one shape. None of these people are asking for a better model. They are asking for the thing the model cannot hold in its head: a map of how the repositories depend on each other. Claude Code is not broken here, and neither is Copilot. They are consumers waiting for a graph that nobody has handed them yet. The rest of this post is about why the workarounds they reach for in the meantime all stop in the same place, and what the graph would have to parse to actually answer the question.

The workarounds, and where each one stops

Spend an hour in the support forums for any of the big coding agents and you will see the same three families of workaround, reached for in roughly this order. Each one solves a real problem. Each one stops at the same wall.

Widen the window

The first instinct is access. Open more repositories so the agent can read them. Claude Code ships /add-dir, and the multi-repo feature requests above are mostly asking for the remote and team version of it. VS Code has multi-root workspaces, a .code-workspace file listing several repository folders that open together. Copilot has Spaces, the one genuinely multi-repo surface GitHub ships, where you assemble a curated set of repositories and chat against it. These are the right first move, and at a handful of repositories they are often enough.

But access is not structure. The agent can now read orders-service while it edits web-app. Nothing tells it that it should, or that a third repository consumes the same contract and is not in scope at all. Widening the window shows the agent more rooms. It does not hand it the floor plan. I made the longer version of this argument in Repo access was never the hard part, and it is the limit underneath this entire category.

Write the map by hand

The second instinct is to write the structure down. This is the CLAUDE.md and AGENTS.md era, files that more than sixty thousand repositories now carry, READMEs for agents that describe how the system fits together. Some teams go further and build a dedicated repository to hold it, an agents meta-repository that serves as the agent's orientation and working memory. The most documented version is Mabl's, an 850-line repo coordination graph their agents query at planning time, which they credit with cutting context drift from roughly forty per cent of agent failures to under five. It works.

It also decays, and the people writing these files know it. The most useful line I have read on the pattern comes from an engineer who layered the files org, team, and repo deep and concluded: "I learned not to list repos here. Lists go stale. Instead, tell Claude where to look." That is the trap in one sentence. A hand-written map has to be kept current by humans at the same throughput the agents are changing the repositories, and the agent navigating by a stale map does not feel stale. It feels fast, right up until the change lands. A map that decays is the developer-portal catalog problem wearing new clothes, and it loses to the same thing: a graph parsed from the source, which cannot drift from the source because it is read from it.

Hand the agent a hosted index

The third instinct is the most sophisticated, and the closest to right. Stop writing the map by hand and serve a real index over a tool call. Augment exposes its context engine to other agents over MCP. There are custom MCP servers with trace_dependency and load_symbol tools that follow the call chain across repository boundaries. CodeLayers does it from tree-sitter. GitLab Orbit does it at GitLab scale, a property graph of code and the whole software lifecycle, queryable over MCP. These are real graphs, and an agent that calls one is genuinely better off than one navigating by a markdown file.

But look at what every one of them indexes. Functions. Classes. Imports. Call edges. They are symbol graphs, and a symbol graph answers "who calls this function" beautifully. It does not answer "what breaks if I change this base image," because the answer to that question is not made of function calls. I want to be fair to Orbit in particular, because it is the most serious graph anyone has shipped in this space and a very large, very well-funded proof that the category is real. I read everything they shipped before saying a word about it. And it still does not parse a single FROM line.

That is the wall all three families hit. Widen the window and you have access without structure. Write the map and you have structure that rots. Serve a symbol index and you have a real graph that stops at the language boundary. None of them parse the layer where a platform team's worst change actually lives.

The edge that was never a function call

Blast radius is two questions wearing one phrase, and almost every tool in this space answers the wrong one for infrastructure. Ask "what breaks if I change this" at the symbol layer and you get a graph of functions and their callers. Ask it at the infrastructure layer and you get a completely different graph, with completely different nodes and edges, built by a completely different parser.

The nodes of that second graph are the things your repositories are actually made of and share between each other. A base image. A Terraform module. A Helm chart. A reusable CI template. The edges are the references that bind those things across repositories: a Dockerfile FROM line pinning the image, a Terraform source block pointing at the module repo, a terraform_remote_state lookup, a Helm dependencies entry or a value reference, a GitLab CI include:project, a reusable Actions uses:. These are not function calls and they are not in the code for a symbol graph to find. They are declared in manifests, deterministically, and they point at repositories the agent never opened.

Side by side, the two graphs look like this.

	Symbol graph	Artifact graph
Nodes	functions, classes, files	base images, Terraform modules, Helm charts, CI templates
Edges	calls and imports between symbols	`FROM` lines, `source` blocks, `include:project`, chart `dependencies`
Where the edge lives	in the code, in the repo you cloned	in a manifest, in a repo you didn't clone
Answers	who calls this function	what breaks if I change this base image

A symbol graph and an artifact graph are different categories, built by different parsers, and blast radius on an infrastructure change needs the second one.

This is why the agent's blindness is structural rather than a gap a smarter model closes. When an agent edits a Terraform module's output variable, the breakage is in the six repositories that source that module, and the only record that those six repositories exist is six source blocks sitting in six manifests across the org. The agent cloned one repository. It has one of the seven facts it needs. No amount of reasoning recovers the other six, because they were never text it could read. They are edges in a graph it was never given.

And the fix has a specific shape, the same one Mabl reached and the same one the feature requests are circling. Parse the manifests that already declare these edges. Resolve each reference to the repository that owns the artifact. Build the cross-repo graph once, keep it current by re-reading the source, and let the agent query it during planning. Parsed, not inferred. The graph that should be answering the agent's question already exists in your org's manifests, unassembled.

What this looks like on a real org

The transitive reach of a shared artifact is almost always larger than anyone eyeballs, and it is invisible from the place people go to check. I ran the open-telemetry GitHub organisation through Riftmap to put a number on it. 105 repositories. A change to opentelemetry-collector reaches twenty-one of them, across three levels of the dependency graph, every edge a go.mod require resolved to the repository that owns the module. An engineer editing the collector sees the collector. They do not see the twenty-one. GitHub's own dependency graph will not show it to them either, because it works per repository and does not traverse the org transitively.

Two details from that scan are worth holding onto, because they say something about what counting gets you versus what parsing gets you. The most-referenced repository in the entire org is opentelemetry-specification, cited fifty-one times. Change it and you break no one's build, because those fifty-one references are documentation links, not dependencies. The collector is referenced far less and ripples through twenty-one repositories. Counting mentions and resolving dependencies are different operations, and only one of them tells you what will actually break.

Now hold that example up against the infrastructure layer, because it is the gentle version of the problem. A go.mod require at least lives in a file inside the repository the agent cloned. The dependency is in scope even if its transitive reach is not. Move to the base image built by a separate platform repository, or the Terraform module sourced from a third, and the dependency is not in the agent's repository at all. It is in another repo entirely, reached by a reference the agent's tools do not resolve. If the package layer is already bigger than anyone tracks, the artifact layer is the part no one can see at all. That is the gap, and it is the one Riftmap was built for.

Why this gets worse as agents get better

The faster and more confident agents get, the wider this gap opens, which is the uncomfortable part. A human making a base-image bump at least pauses, half-remembers that the payments team is downstream, and sends a Slack message. An agent makes the change cleanly, passes the same local tests the repository has always been reviewed against, and opens the pull request in ninety seconds. Each change looks correct in isolation because each change is correct in isolation. The defect is at the seam between repositories, and the seam is exactly what neither the agent nor its local tests can see.

This is why the aggregate numbers move in the wrong direction as AI adoption climbs, and I have walked that data, Cortex and DORA and Amazon's own high-blast-radius memo, in its own post rather than repeat it here. The short version is that local correctness went up and system stability went down, and the two are not in tension. They are the same fact seen from inside one repository and from across the org.

The dependency that walked out the door

There is a more human version of this, and in every conversation I have had about Riftmap it is the one that lands hardest. The base image that nine services inherit from, or the shared module six repositories source, is very often a dependency nobody wrote down, set up years ago by the senior engineer who has since moved teams or left. The graph lived in their head. When they walked out the door, the org did not lose the dependency. It lost the only copy of the map.

An agent inherits that amnesia and runs at speed on top of it. It will confidently change the artifact the departed engineer quietly wired into half the estate, because nothing in the repository it cloned records that the wiring exists. This is the highest-stakes edge precisely because it is the least documented one, and it is the strongest reason the map cannot be a thing humans maintain by hand. The dependency that broke production is the one nobody remembered. A parser does not forget, and it does not resign.

The graph you don't have to build

Give an agent every repository in your organisation and you have given it access. You have not given it the map. The record of what breaks when it bumps a base image was never in any of those repositories' code, and no symbol graph, however good, will reconstruct an edge that was only ever a source block in a manifest. Those are different gifts, and only one of them tells the agent what it is about to break.

Riftmap is the version of that map you do not have to build by hand. One read-only token across your GitHub or GitLab organisation. It parses the manifests that already declare these edges, Terraform source blocks, Dockerfile FROM lines, Helm chart dependencies, CI includes, go.mod requires, across twelve ecosystems, resolves each reference to the repository that owns it, and serves the result two ways. An interactive blast-radius view for the engineer who owns the estate and holds the pager, and an HTTP API the agent calls during planning, to ask which repositories a change affects before it opens the pull request. Auto-discovered, never catalogued. Parsed, not inferred.

Questions teams ask

The same handful of questions comes up every time I walk an engineer through this, so here they are, answered straight.

Can an AI coding agent see which other repos a change will affect? Not on its own. An agent's context is the repository it has cloned, and the edges that break when a shared base image, Terraform module, or Helm chart changes live in other repositories, declared in manifests the agent never reads. It can see the change. It cannot see the consumers, unless it is given a cross-repo dependency graph to query.

Why doesn't Claude Code or Cursor know about my Terraform or Helm dependencies? Because those dependencies are not function calls. A Dockerfile FROM line, a Terraform source block, or a Helm value reference is a manifest declaration that points at another repository, and code-aware tooling indexes symbols and imports, not artifact references across repos. The dependency only exists in a file the agent did not clone, so it sits outside the agent's context by construction.

How do I give a coding agent cross-repo blast radius? Parse the manifests across your org that already declare the dependencies, resolve each reference to the repository that owns the artifact, and expose the resulting graph as a tool the agent calls during planning. Riftmap does this from one read-only token and serves it over an HTTP API, so the agent can ask which repositories a change affects before it opens a pull request.

Isn't this just a token-saving optimisation for agents? No. Saving tokens is a side effect, and a declining one as context windows grow. The point is that the artifact-layer dependency graph is information the agent structurally cannot reconstruct from the single repository it cloned, no matter how large its context window gets. It is missing context, not expensive context.

How to Find Every Consumer of Your Kustomize Base

Daniel Westgaard — Sat, 27 Jun 2026 00:00:00 GMT

You have a two-line change staged for platform-base. It is the overlay every team in the org builds on. Maybe you are tightening a securityContext so the whole estate runs as non-root. Maybe you are changing a commonLabels value that Kustomize propagates into selector fields, and a Deployment selector is immutable once it exists, so for everyone downstream this is a delete and recreate rather than a rolling update. Maybe you are dropping a Kubernetes API version that a recent release finally removed. You make the edit, and you reach for a tag.

Then the question lands, the way it always does right before you cut a release. Who builds on this?

You look at the base repository for an answer. There is a kustomization.yaml, a base/ directory of manifests, and a README that three people have edited and nobody has read. None of it names a single overlay that points at this base. Nothing inside the base knows who depends on it. That information lives somewhere else, in repositories you are not currently looking at, and the base has no way to point you towards them.

This is the same structural fact behind the whole Find Every Consumer series: the dependency lives in the relationship between repositories, and the artifact you are changing cannot see its own dependents. We have worked through that shape for Terraform modules, Docker base images, Helm charts, and six other ecosystems. Kustomize is the last of them.

Here is the conflation worth naming. Kustomize gets filed in everyone's head as a local templating thing. You write overlays, you run kustomize build, you get manifests. And for a single repository that is exactly what it is. But the moment a base goes remote, the moment one overlay's resources: list points at another repository's directory, Kustomize stops being a local tool and becomes a cross-repo dependency mechanism with a version. Teams adopt remote bases for precisely that reason, to share a hardened, opinionated base across the org without copying it. And then they get no consumer map, because nothing in the toolchain was built to give them one. So let us answer it properly. If you change a shared Kustomize base, what breaks, and how do you find every overlay that builds on it before you find out the hard way?

Where your base actually gets consumed

Start with the shape of the problem, because Kustomize reuse spreads a base's dependents across more places, and more spellings, than people expect.

The pattern that matters is the remote base. One repository holds a base, a kustomization.yaml and the manifests it assembles, and overlays in other repositories pull it in by URL through the resources: list:

# my-app/overlays/production/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - https://github.com/platform/configs//bases/webapp?ref=v1.2.0
namespace: production
images:
  - name: webapp
    newName: registry.example.com/team/webapp
    newTag: v2.1.0

That resources: entry is a cross-repo dependency. The overlay lives in the application team's repository. The base lives in the platform team's repository. The ?ref=v1.2.0 is a version pin on that dependency, sitting inside a URL string. And this is not an exotic usage. The common shape in practice is composition across teams, an overlay assembling bases that several different teams each own:

resources:
  # Platform team's standard webapp base
  - https://github.com/platform/configs//bases/webapp?ref=v1.0.0
  # Security team's network policies
  - https://github.com/security/policies//network-policies?ref=v2.1.0
  # Observability team's standard service monitor
  - https://github.com/monitoring/configs//prometheus-servicemonitor?ref=v1.5.0

This composition approach is documented as real-world practice, and it is exactly the cross-repo coupling that goes unmapped. When I actually counted every cross-repo edge across two real orgs, this kind of infrastructure coupling was the entire story — not one edge was a code symbol. Every one of those three bases lives in a repository other than the one doing the assembling. Each consuming overlay names the base it depends on in a URL, not in a clean, typed dependency block. And the components: list behaves the same way, as does the older bases: field that is deprecated but very much still live in real repositories.

It is worth being precise about how this differs from the Helm post, because the two are the pair that covers Kubernetes config reuse. Helm shares config through templated, versioned charts pulled from a registry, and that post covered the consumer side of it in full, the Chart.yaml dependencies, the ArgoCD Application and Flux HelmRelease manifests, the OCI and HTTP registry forms. Kustomize shares config through overlays that patch a base. The chart is a package; the base is a directory in a repo. The one place the two worlds touch is the inline helmCharts: field, where a Kustomization renders a Helm chart directly, and that is the seam back to the Helm post. Everything else here is the other half of the problem: the overlay model, where a remote base is the unit of reuse and a URL is the dependency edge.

This is the same structural shape we covered for Terraform modules pulled by git:: source. A directory in one repository, referenced by URL from another, pinned by a ref. Kustomize just has more spellings for the URL, and that is where it gets hard.

The version lives inside the URL, and the URL is a mess

Look again at that remote base reference. The version you care about, the thing that decides whether a given overlay is in range of your next release, is not in a version: field. It is the ?ref= query parameter inside the resource string. To know who is pinned to v1.0.0 and who is riding main, you have to parse the URL.

And the URL is not one format. It is a family of formats, and the family is, by the maintainers' own description, not well-specified.

The official Kustomize docs describe the modern form as an HTTPS or SSH git clone URL, with the in-repo directory appended after a //, and query parameters for ref, version, timeout, and submodules. So all of these are valid, and all of them mean a remote base:

resources:
  # scheme-prefixed HTTPS
  - https://github.com/org/repo//overlays/prod?ref=v1.2.0
  # explicit git:: prefix
  - git::https://gitlab.example.com/infra/base//manifests?ref=v3
  # SSH scheme
  - ssh://git@gitlab.example.com/infra/legacy-base.git//manifests?ref=main
  # scp-like SSH, no scheme at all
  - git@gitlab.com:org/platform/k8s-cluster-addons.git//kustomize/base?ref=v1.0.0
  # scheme-less host, the canonical form in Kustomize's own examples
  - github.com/org/repo//overlays?ref=v1.0.0

The scheme-less form at the bottom is not a shortcut someone invented. It is the canonical form in Kustomize's own remote-build examples. No leading https://, no git@, just a host and a path and a //. A grep written to find URLs, anything anchored on https?://, sails straight past it.

If you think this is me picking the worst case, here is the maintainers' own account of it. There is an open issue cataloguing the URL forms Kustomize currently accepts, and the list includes github.com/org/repo, gh:github.com/org/repo, https://github.com/org/repo, git::https://github.com/org/repo, and github.com:org/repo, with the author noting "and probably a lot more." It then points out that most of those shortcuts only work for github.com, so the scheme-less form for a different host may or may not resolve, and concludes that the parsing logic "greatly needs an overhaul." There is a separate legacy go-getter format, still supported for backwards compatibility but no longer recommended, which means it is also still in real repositories.

There is one more wrinkle the same issue surfaces, and it matters for anyone trying to detect these. Kustomize tries to load a resource as a file first and as a remote base second, and the thing that disambiguates is the //. A path with a // delimiting a subdirectory is treated as a remote base; a plain path like ../base is local and is read directly off disk. So the // is load-bearing. Any detector has to use it to tell a cross-repo dependency (gitlab.example.com/infra/base//overlays) apart from a local path that happens to live a directory up (../base), and from a relative path that happens to contain a double slash for unrelated reasons. Get that wrong in either direction and you either miss real edges or invent ones that do not exist.

This is the part of the Kustomize story that is genuinely close to uncontested. Plenty of tools can render an overlay. The reverse question, which overlays across the org point at this base and at which ref, requires parsing a URL format that the project itself calls underspecified, and almost nothing does it.

The image you deploy is not the image you wrote

Remote bases are the headline, but there is a second cross-repo edge in every overlay, and it has a trap in it.

Kustomize overlays rewrite images through the images: transformer. The subtlety, the one that quietly resolves the wrong thing if you are not careful, is that the image actually deployed is the newName, not the name being matched:

images:
  - name: addon                  # placeholder; a name-matching scan wrongly stops here
    newName: registry.example.com/platform/docker-base-images/python   # the image that deploys
    newTag: "3.12"               # so the real edge is: docker-base-images : python @ 3.12

Read that the way a naive scan would, keying off the name: field, and you conclude the overlay depends on an image called addon. It does not. addon is just the placeholder being matched in the base; the image that lands in the running pod is registry.example.com/platform/docker-base-images/python. The real dependency, the artifact whose consumers you would want to track, is the newName. The original name is metadata, useful to keep but not the edge. A consumer map that resolves the matched name instead of the effective name points at the wrong node, or at no node at all when the placeholder is a bare string with no registry in it.

Version comes from newTag, or from a digest when the overlay pins by content:

images:
  - name: registry.example.com/platform/docker-base-images/go
    digest: sha256:1111aaaa...

A digest is the most precise pin there is. It is also where the simple, obvious parsing approach falls over, because the version is not the part after the last colon. Split registry.example.com/org/app@sha256:1111... on : and you mangle the digest. The whole sha256:... string is the version, and digest wins over newTag when both are present, which is a rule Kustomize enforces and Renovate documents precisely because the combination is ambiguous.

And the images do not only live in overlays. Raw Kubernetes manifests carry them too, in containers, in initContainers, and, since Kubernetes 1.25, in ephemeralContainers, the debug containers people attach to a running pod. That last list is the one most tools forget. A maintenance pod that pulls a private image into an ephemeral container is consuming that image just as surely as a Deployment is, and if your scan walks only containers you will miss it.

So a single overlay can declare a remote-base edge to another team's repository and an image edge to your registry, and a single manifest can declare image edges across three different container lists. None of it looks the same, and all of it is cross-repo.

What the Kubernetes and Kustomize tooling tells you, and where it stops

The tooling around Kustomize is good, and it answers real questions. It answers the other ones.

The Kustomize CLI. kustomize build and kubectl kustomize render an overlay to its final manifests, resolving the remote bases, applying the patches, rewriting the images. This is genuinely useful and it is the right tool for seeing what an overlay produces. It is also forward and per-overlay. You point it at an overlay and it tells you what that overlay becomes. There is no reverse mode, no kustomize who-builds-on-this. It cannot take a base and hand you the overlays across the org that consume it, because it only ever looks down from one overlay, never up from one base.

ArgoCD and Flux. They deploy Kustomize overlays, and if your org has gone all-in on GitOps then in principle every consuming overlay is declared somewhere as an Application or a Kustomization CRD. The Helm post went deep on why "in principle" does a lot of work in that sentence, and the same applies here, so I will keep it short: the manifests are spread across a central gitops repo, per-team repos, and per-environment repos, and "show me every Application whose overlay references base X" is not a built-in view in either tool. There is a sharper version of the problem that is specific to remote bases. When an ArgoCD Application points at one repo whose overlay pulls a private base from a second repo, the deploy tooling frequently cannot make that jump, because its credentials are scoped to the first repo. This is a recurring, documented pain point. The cross-repo edge is real enough to break a deploy, and still invisible to the thing doing the deploying.

Renovate. It is the closest any of these come to caring about consumers, and it deserves a fair hearing, because its Kustomize support is real. The kustomize manager parses kustomization.yaml files, extracts remote resources, image tags, components, and helm charts, resolves the dependency's source repository, checks for newer SemVer tags, and opens a pull request to bump the version. If you want your remote-base refs and image tags kept current, it does that job.

But, as with every ecosystem in this series, Renovate has to know who consumes what in order to open those PRs, and it does not expose that knowledge as something you can query. You cannot ask it "which overlays reference my base, and at which ref." It reacts after a new version is published, repo by repo, and only in repos where it is configured. There are two failure modes specific to Kustomize on top of that. Its remote-target URL parsing is brittle: it does not treat the version= parameter as a ref, and multiple query parameters break it, so the very URL forms the previous section catalogued are partly outside what it handles. And for raw Kubernetes manifests, the picture is starker. Renovate's Kubernetes manager is off by default and matches no files at all until you configure file patterns by hand, for a reason the docs state plainly: there is no commonly accepted naming convention for Kubernetes YAML files, and they do not want to check every *.yaml file just in case. That is not an oversight. It is the same hard problem we are about to get to, and Renovate's honest answer to it is to make it your job, per repo. Which is exactly the configuration burden the rest of this post argues you should not have to carry.

The general-purpose graphs. They sit at a different layer and have a clean category line, the same one drawn across this series. Sourcegraph's symbol graph is excellent at programming-language symbols and blind to kustomization.yaml, because a remote base is not a symbol. Port models the catalog you describe in Blueprints rather than parsing the bases your repos already declare, so your base-to-overlay edges are only as complete as what someone remembered to model. Backstage and the developer-portal category solve a real problem, but the catalog is only as accurate as the last person to edit it, which is why teams quietly stop editing it. None of these is wrong. They are answering a different question.

Every tool above is forward, or reactive, or modelled by hand. Render this overlay. Bump this repo when a tag moves. Show me the catalog I wrote down. Not one of them answers the question with your finger on the tag: across all of my repositories, which overlays build on this base, at which ref, and what breaks if I change it.

Why this is harder than it looks

You might reasonably think this is a grep problem. Search every repository for the base's repo name, collect the hits, done. It is not, and the reasons are specific to how Kustomize references things.

Most remote bases are not URLs

The previous section made the case from the maintainers' own issue tracker, so I will not relitigate it, only draw the consequence. A grep anchored on https:// misses the scheme-less canonical form. A grep for the bare host string risks colliding with comments, with image registries that share the host, and with documentation. And the // that distinguishes a remote base from a local path is the kind of thing a regex can match but cannot reason about, because telling gitlab.example.com/infra/base//overlays (remote, cross-repo) apart from ../base (local, ignore) and from a path that contains // incidentally requires understanding that the first has a real dotted host in front of the // and the others do not. This is parsing, not searching. The honest version of the detector gates on a dotted host segment before the //, so relative paths stay local and only genuine remote references become edges.

The deployed image hides behind a rename

The newName trap from earlier is a grep problem in miniature. The string you would search for, the effective image, does not appear next to the name: field that a naive scan latches onto. It appears in the newName: line below it, and the matched name above is a placeholder you specifically do not want to resolve. A tool that reads the wrong field produces an edge to a node that does not exist, which is worse than no edge, because it looks like an answer.

You cannot just allow-list every YAML file

This is the one that has no clean shortcut, and it is the same wall Renovate hit when it left its Kubernetes manager off by default.

A formal parser earns the right to own a file, so that a cheaper text-grep pass does not also scan it and emit a second, lower-confidence version of the same edge. For most ecosystems that ownership is by filename. A kustomization.yaml has a fixed name, so a parser can claim it, and the heuristic scanner can cede every file with that name. Good. But raw Kubernetes manifests have no naming convention. They are *.yaml, the single most common file extension in an infrastructure repository, shared with CI config, Helm values, GitHub Actions workflows, and a hundred other things. You cannot allow-list *.yaml to a Kubernetes parser without disabling text-based YAML scanning across the entire organisation. So the Kubernetes case cannot be solved by filename. It has to be solved by content: a parser may claim a YAML file only when the content actually is a Kubernetes manifest, an owned pod-spec kind carrying an image. And it has to be deliberately narrow, because a manifest that carries no image, a ConfigMap, a Service, a CRD, should still fall through to the heuristic scanner, in case it carries an incidental in-org URL worth catching. This is a real, fiddly, important distinction, and it is the difference between a graph you can trust and one that double-counts.

Templated manifests do not fully parse

Some manifests under a templates/ directory are Go-templated YAML that a strict YAML parser rejects outright, because {{ .Values.image }} is not valid YAML. The best you can do is a regex fallback that recovers the literal image: references and accepts a lower confidence for them. The honest boundary is the same one every ecosystem in this series eventually hits: a pure {{ .Values.image }} reference cannot be resolved from source, because the real image is supplied at install time, not committed in the file. A tool that claims to resolve it is guessing. The right move is to recover the literal references, score them honestly, and be straight about the templated ones.

What the full answer requires

Put all of that together and the requirements for actually answering "who consumes this base" fall out:

Scan every repository in the organisation, with no opt-in and no per-repo config. The consuming overlays live in repositories other than the one you are changing, so anything that needs each team to register, annotate, or configure a file pattern will be incomplete the day someone forgets.
Parse every remote-base spelling and pull the ref out of the URL. Scheme-prefixed, git::, ssh://, scp-like SSH, and the scheme-less canonical form, across resources:, components:, and the deprecated bases:, with the ?ref= or ?version= captured as the version.
Resolve image transformers against the effective newName, not the matched name, and read the whole sha256:... as the version when a base pins by digest.
Walk containers, initContainers, and ephemeralContainers in raw manifests, so a debug container consuming a private image is counted, not missed.
Resolve a remote base to the in-org repository that produces it, including the scp-like SSH form, with a guard so a public base that happens to share a name with one of yours is not pulled into your graph.
Record the constraint state of every consumer, whether they pinned you to a ref, rode a branch, or pinned by digest, so you know which overlays move when you tag and which stay put.
Tell these two kinds of edge apart without double-counting them, which means owning kustomization.yaml by filename and Kubernetes manifests by content, and staying current by re-scanning rather than trusting a one-time trawl.

How Riftmap does this

This is the gap Riftmap was built to close, so here is honestly what it does and does not do for Kustomize and Kubernetes.

Riftmap scans a GitLab or GitHub organisation and parses every repository deterministically. There is no language model in the parse path; the edges come from parsing the actual files, and each edge carries a rule-based confidence score. On the Kustomize side it reads remote bases from resources:, components:, and bases: as a kustomize_resource edge at confidence 0.9, recognising the scheme-prefixed, git+, ssh://, scp-like SSH, and scheme-less host forms, and gating on a dotted host segment so local paths stay local. It reads the images: transformer as a kustomize_image edge at 0.85, resolving the effective newName and keeping the matched name as metadata. On the raw-manifest side it reads containers, initContainers, and ephemeralContainers as k8s_container_image edges at 0.85, recording a digest pin as its full sha256:... string. The inline helmCharts: field resolves as a helm_chart_reference, which is the one place this hands back to the Helm world. These dependency-type strings are stable, and the confidence scores are deliberately uneven, because some of these edges are more certain than others and the tool says so rather than flattening everything to one confident-looking line.

The headline for the resolver is the scp-like SSH form, the one with no scheme that a URL parser chokes on. Given git@gitlab.com:polaris-works/platform/k8s-cluster-addons.git//kustomize/base?ref=v1.0.0 in an overlay's resources:, Riftmap rewrites the git@host:path form to host/path, resolves it to the in-org k8s-cluster-addons repository, and records v1.0.0 as the version. The scheme-less in-org form pointing at the same base resolves to the same repository, and the two declarations dedupe to a single graph edge, so the impact view shows one dependency, not two, while the declaration view still shows both rows.

The double-counting problem from earlier gets solved with the content-versus-filename split, made concrete. Riftmap owns kustomization.yaml by filename and raw manifests by content, so a base is counted once, as a kustomize_resource, never also as an incidental git_url_reference. The filename half is easy. The content half is the careful one: the Kubernetes parser claims a *.yaml file only when it carries an owned pod-spec kind and an image, so a maintenance pod is claimed and ceded, while an image-less ConfigMap beside it still falls through to the heuristic scanner for any org URL it happens to carry. Same double-emit class that bit the ArgoCD parser, solved the same way.

The numbers come from the polaris-works test organisation, a 55-repo synthetic org built to stress exactly these cases, on a full re-scan that completed across all 55 repositories with nothing skipped. The Kustomize and Kubernetes fixtures added three graph edges, taking the org from 180 to 183. What makes the three the point is what they collapse from:

Declared in the fixtures	Becomes in the graph
4 image references (2 `kustomize_image` transformers + 2 `k8s_container_image`, across container and ephemeral)	2 edges, both into the single `docker-base-images` artifact (`python`, `go`, `node` are tags of it)
5 remote-base references (2 in-org, 3 external)	1 edge to the in-org base; the 3 external bases stay unresolved
9 references in source	3 edges, 0 new artifacts (180 → 183)

Those three edges are warehouse-api building on k8s-cluster-addons through the scp-like SSH base, and k8s-cluster-addons consuming docker-base-images through both a Kustomize image transformer and a raw Pod container. The collapse is the dedup story made literal: nine references in source become three edges in the graph. And the two cedes held through all of it. Org-wide git_url_reference stayed at 7 and docker_base_image stayed at 19, which is the proof nothing got double-emitted. The artifact count did not move from 87, because Kustomize and Kubernetes consume; they do not produce. The one consumer-count that changed was docker-base-images, from 19 to 20, as k8s-cluster-addons was added once, not twice.

What Riftmap does not claim

The honest limits are part of the product, so here they are plainly.

It does not resolve templated image references. A literal image: line in a Go-templated manifest is recovered at lower confidence, but a pure {{ .Values.image }} is unknowable until install time, and the tool does not pretend otherwise.

A digest pin currently shows its constraint state as branch rather than pinned. The resolution is correct, the edge points at the right artifact, but the state label, the thing that buckets a consumer as pinned or floating, falls through to the wrong bucket for sha256:.... It is cosmetic, it is on the list to fix, and it is the kind of thing worth being upfront about. If you want the full treatment of constraint state, why pinned, floating, and branch are the facts that actually decide your blast radius, I wrote about it across real estates here.

It reads the manifest as committed, not the output of kustomize build. So a generator that synthesises resources at build time is not expanded, by design, because expanding it would mean executing the build rather than parsing the source. The matched name behind a newName is stored as metadata but is not yet surfaced on the public dependencies API. And it recognises your bases and images by your org and registry, so a public base or a public image you merely consume shows up as an external dependency, which is the correct answer, not a repository in your graph.

None of those gaps is hidden behind a confident interface. The point of a blast-radius tool is to be trusted on a Friday afternoon, and you do not earn that by overclaiming.

Twelve ecosystems, one graph

Step back, because this is the last ecosystem in the series and the shape of the whole thing is finally visible.

A base's consumers are the overlays that build on it. An image's consumers are every file that points at it. And here is the part that only lands once you have done all ten: those are edges into the same graph, and the graph does not care which kind of file the consumer lives in. The docker-base-images artifact in that scan is consumed by Dockerfile FROM lines, the subject of the very first post in this series. It is consumed by Kubernetes Deployment containers. It is consumed by Kustomize image transformers. Three different consumer surfaces, three different file formats, one node, counted once. The Dockerfile, the Deployment, and the overlay are not three separate problems. They are three ways of pointing at the same artifact, and a graph that parses the edges sees them as exactly that.

That is why the series worked one ecosystem at a time but was only ever building one thing. Each post took an artifact most teams cannot get a consumer list for, a Terraform module, a Helm chart, a Go module, an npm package, an Ansible role, a Kustomize base, and showed that the consumer list is unanswerable for the same reason every time: the dependency was never in the file you were changing. It was in the relationship between repositories, and the artifact you were about to break could not see its own dependents. The fix is not a better grep or a catalog someone has to maintain. It is to parse those relationships across the whole organisation and resolve them into a graph. Parsed, not inferred.

Your platform-base change is still sitting there, untagged. Now you can see every overlay that builds on it, at which ref, which ones move when you tag and which stay pinned, and which teams you were about to surprise. Tag it on purpose.

This is the latest post in the Find Every Consumer series, which works through the same question across Docker base images, Terraform modules, GitHub Actions workflows, Helm charts, Go modules, GitLab CI templates, npm packages, Python packages, and Ansible roles, one ecosystem at a time. It completes the run across the twelve ecosystems Riftmap parses today, and the graph keeps growing as new ones are added. For the technical version of how each ecosystem fights back, see auto-discovering dependencies across ten ecosystems, and for what this looks like on a real Kubernetes org, see what 208 kubernetes-sigs repos actually depend on.

Riftmap maps cross-repository dependencies across a GitLab or GitHub organisation and answers the change-impact question directly: if I change this, what else breaks? It parses the relationships between your repositories rather than asking you to model them, with no per-repo config. Map your org, or book a walkthrough and we will map it with you.

I counted every cross-repo edge in two real orgs. Not one was a code symbol.

Daniel Westgaard — Thu, 25 Jun 2026 00:00:00 GMT

I scanned two public GitHub organisations and counted every cross-repository edge between them. The share that is infrastructure rather than code runs from a third to almost all. The share that is a code symbol is zero.

Spend a couple of days reading the launches that landed this spring and you start to notice what they have in common. GitLab shipped Orbit. Sourcegraph rebuilt its homepage around an AI code-review demo. Both are good, and both are graphs of your code. Both sell you on the same kind of question. Who calls this function. What inherits from this interface. What does changing this method signature touch. Every query in every demo is a code query.

There is a question underneath all of it that none of those launches answers. Symbol graphs are excellent. I will say that more than once in this post and mean it every time. But how much of what actually holds a real organisation together are they even looking at? Nobody has put a number on it. So I scanned two real organisations and counted.

Two graphs, and only one of them gets measured

The argument about these graphs has been had. I have had it twice, at length. There is the symbol graph: the functions, classes and imports inside your code, the thing SCIP indexes and Sourcegraph serves at the top of its category. And there is the artifact graph: the base images, Terraform modules, Helm charts and reusable CI templates your repositories share, bound together by edges that were never code. A Dockerfile FROM line. A Terraform source block. A GitLab CI include. Different nodes, different edges, a different parser entirely. I have worked that distinction through in full for Sourcegraph and for GitLab Orbit, and I would rather link those than repeat them.

What none of us did, in any of those posts, was measure the split. The whole debate is about which graph matters. It has been conducted without the one number that would settle the shape of it. In a real organisation, how much of the cross-repo coupling lives in the artifact graph a symbol tool cannot see? That number is not on the open web. I went and got it.

One clarification before the data, because the words collide. "Artifact dependency graph" also means something specific in supply-chain security, where it records what went into building a single binary. That is a different graph pointed in the opposite direction. This post is about the cross-repo sense: what consumes your shared artifacts across the org.

What I scanned, and how I counted

Two public GitHub organisations, chosen to sit at opposite ends on purpose. Prometheus, the monitoring stack, is about as code-centric as an org gets. Go-native, 58 repositories, the kind of place where you would expect the coupling to live in go.mod and nowhere else. Cloud Posse is the opposite by design. Its entire reason to exist is publishing reusable terraform-aws- modules, so if any organisation's coupling lives in infrastructure, it is that one. I am not hiding that choice. The point of the pair is to bracket the range, and you cannot bracket a range without picking the ends.

Both were scanned on the same day, 2026-06-25, on the same build of Riftmap (v1.6.6, commit 273794e). Prometheus came back with 58 repositories scanned, Cloud Posse with 242.

Here is the rule every number in this post is counted by, stated once so you can hold me to it.

Counts are directly-declared, in-organisation, cross-repository dependency edges from a single fresh full scan of each GitHub org, where both the consuming repo and the producing repo are inside the org and are not the same repo; references in test/ and examples/ trees are excluded. The canonical headline unit is one distinct consumer-repo to producer edge; raw manifest references are reported alongside. The "no symbol-graph representation" claim is scoped to the infrastructure-artifact bucket only (Terraform sources, Docker FROMs, CI uses and includes, Kubernetes images): those edges contain no code symbols or import statements. The language-package bucket (Go, npm, Python) is manifest-declared and partially representable by a symbol indexer via import resolution.

In plain terms. An edge only counts if it stays inside the org and crosses a repository boundary. A dependency that leaves for the public registry does not count. I count what is declared, not the transitive closure underneath it. And the strong claim, the one about edges a symbol graph cannot represent, applies to the infrastructure layer, not to the package edges a symbol index can partly resolve through imports. I will come back to that last point and give the symbol graph its due.

One more convention. Every figure here is the product's all-confidence count, the same number app.riftmap.dev shows and anyone can re-run, with a stricter 0.8-confidence floor reported alongside wherever it changes the picture.

I will tell you how I know the count is honest, because the way I found out is the best evidence I have. The first scan undercounted Cloud Posse badly. It parsed 1,361 Terraform Registry references like source = "cloudposse/label/null" and resolved exactly none of them to a repository inside the org, because the resolver was treating the registry namespace as somewhere external. The scan had found a gap in my own tool. I fixed the resolver, re-scanned, and Cloud Posse's resolved edges went from 199 to 490 while terraform-null-label's consumers went from 9 to 147. Prometheus came back identical, edge for edge. A change that moves the Terraform-native org two and a half times over and does not touch a single edge in the Go-native one is the cleanest evidence I can give you that the count measures what it claims to.

Where the edges actually live

Prometheus: a third of the coupling is already invisible

Start with the org that should be friendliest to the symbol-graph view, and the one I have scanned before. 214 cross-repo edges, from 271 references. The breakdown reads exactly like a Go shop. 132 go.mod requires, 40 GitHub Actions uses, 38 Dockerfile FROM lines, 3 Kubernetes image references, 1 npm dependency.

Add up the edges a symbol graph cannot represent, the Actions and the Docker images and the Kubernetes references, and you get 38% of the total. Call it a third, in the most code-centric org I could find. At the stricter confidence floor it is 32%, which is the number I would defend hardest. Either way, a third of what holds Prometheus together is infrastructure no symbol indexer sees.

And the other two-thirds? Those are go.mod requires. Not function calls. Manifest lines a build tool resolves later against a module registry. I will come back to what a symbol graph does with those. For now the only figure that matters is the one at the bottom of the table. Of 214 cross-repo edges, the number that are code symbols is zero.

Cloud Posse: almost all of it is infrastructure

Now the other end. 490 edges, from 1,320 references. Here I have to be careful with the confidence split, because it is the one place a sharp reader can push, so let me push first. Of the 408 edges resolved at high confidence, 407 are infrastructure artifacts and exactly one is a language package. That is 99.75%. The product's headline number is 490 rather than 408, and the difference is 82 lower-confidence heuristic edges that mix real infrastructure couplings with a handful of Go import paths and some noise. I hold those out of the claim. That is why the share is anchored to the 408 I can stand behind, not the 490.

The composition of the part I can stand behind. 359 Terraform module sources, 36 Actions, 8 Docker base images, 4 reusable workflows, and that single go.mod require. Cloud Posse is an extreme, and it is an extreme by construction. That is the reason it is here. It shows you where an organisation built entirely out of shared infrastructure actually sits, and it sits at almost exactly 100%. The symbol count, again, is zero.

Put the two ends together. The infrastructure share of cross-repo coupling runs from 38% in the most code-centric org I could pick to 99.75% in the most infrastructure-centric one. The number that does not move is the symbol count. In both organisations it is zero.

One module, 147 repositories

Composition is the shape of the thing. Fan-in is where it bites. So here is the single most-consumed artifact in either org, and it retires a guess I made in writing once.

In the glossary entry for the artifact graph I wrote, as a hypothetical, that a shared Terraform module might be sourced by forty repositories. The measured figure for Cloud Posse's terraform-null-label is 147. Every one of those 147 repositories pulls it through the same line, module "this" { source = "cloudposse/label/null" }, sitting in a context.tf. Behind it the next most-shared modules are route53-cluster-hostname at 15, security-group at 13, iam-role at 9.

Sit with the 147 for a moment. That is one module, and changing it re-plans 147 repositories across the org. The edge that connects it to each of them is a single string in a manifest. There is no function call. There is no import statement. There is nothing in any symbol table. A symbol graph could index every line of Go in Cloud Posse and represent precisely none of that 147-repository blast radius, because the blast radius was never written in code.

A note on the number, so it is unimpeachable. 156 repositories reference the module in raw declarations. 147 of those resolve to distinct in-org consumers once self-references and test trees are stripped out. 147 is the figure I stand behind.

What a symbol graph does see

I have said symbol graphs are excellent twice now, and I want to make the concession real, because the claim I am making is narrower than "symbol tools are blind" and the difference is the whole point.

A symbol graph is not blind to all of this. For the language-package edges, Prometheus's 132 go.mod requires, SCIP carries the relationship. Its external-symbol mechanism resolves an import in one repository to the package that defines it in another, with version metadata attached. Ask Sourcegraph whether node_exporter depends on client_golang and it can tell you, and it would be right. I am not going to pretend otherwise to make my number look bigger.

What a symbol graph cannot do is two separate things. The first is the headline. It cannot represent the infrastructure edges at all. A Dockerfile FROM, a Terraform source, a GitLab CI include, an Actions uses. None of them contains a symbol or an import for an indexer to resolve, so none of them appears in a symbol index. That is the infrastructure bucket, the one that ran from a third to nearly all, and it is structural. It is not a coverage gap someone closes next quarter. The second is subtler, and it applies even to the package edges a symbol graph can see. An index will tell you node_exporter imports client_golang. It will not tell you which version constraint each of the 23 consumers is pinned to, which of them float to your next release, or which reference is hiding in a second go.mod three directories down. That resolution is the work. It is the thing the artifact graph does and the symbol index does not.

So here is the precise version of the claim, the one I will defend against anyone at Sourcegraph or GitLab. Not one cross-repo edge in either organisation is a symbol. And the infrastructure share of those edges, the part no symbol index reaches at all, runs from a third to nearly all.

The graph that was carrying the weight

A symbol graph can read every line of code in your organisation and still not see the base-image bump about to take a dozen services down, or the one-line source reference binding 147 repositories to a single module. Those edges were never code. They were declarations, sitting in manifests, waiting for a build tool to resolve them long after the symbol indexer had finished its pass. The graph that maps them is a different graph. And in the two organisations I measured, it was carrying somewhere between a third and very nearly all of the weight.

None of which makes that graph exotic. Past a certain repository count it is as load-bearing as the symbol graph, and a serious setup needs both. The requirements are not subtle either. It has to be parsed from source, so it stays current as the repositories change instead of going stale the moment someone forgets to update a catalog. It has to be queryable, so the engineer reaching for it mid-incident and the agent reaching for it at planning time get the same answer. And it has to read across whatever platforms you actually run on, because the edge that bites is the one running from a GitHub service onto a base image published from GitLab. That is the primitive. It is not a product. It is the thing the industry has spent this year slowly working out that it needs, one launch at a time.

Where I build that primitive, it is called Riftmap. One read-only token, a GitLab or GitHub organisation parsed across twelve ecosystems, and the artifact graph comes back as something you can use. A visual blast radius in the UI, the same graph over an API for the agents that need it at planning time. Parsed, not inferred. Auto-discovered, never catalogued. The numbers in this post came out of it, and you can point it at your own org and get yours.

A few questions, answered directly

What fraction of cross-repo dependencies are infrastructure rather than code?

In two real public organisations measured in June 2026, the infrastructure-artifact share of in-org cross-repository edges ranged from 38% in a Go-native stack (Prometheus) to 99.75% in a Terraform-native one (Cloud Posse). It varies with what the organisation builds, but in both cases zero of the cross-repo edges were code symbols. The infrastructure edges are Terraform source blocks, Dockerfile FROM lines, CI includes and reusable workflows, none of which a symbol graph represents.

How many repositories typically depend on a single shared Terraform module?

In the Cloud Posse organisation, one module (terraform-null-label) is sourced by 147 repositories, each through a single-line source reference in a Terraform manifest. High-fan-out shared artifacts like this are the widest-blast-radius and least-visible edges in a polyrepo: changing one of them re-plans every consumer, and the edge to each consumer is a declaration in a manifest rather than anything in code.

Can a symbol graph such as SCIP, Sourcegraph or GitLab Orbit index infrastructure dependency edges?

No. Infrastructure edges like a Dockerfile FROM, a Terraform source or an Actions uses contain no code symbols and no import statements, so a symbol indexer represents none of them. A symbol graph can resolve language-package dependencies such as a Go import or an npm package through import resolution, but the infrastructure layer requires a different parser entirely.

What version constraints actually look like across real Terraform estates

Daniel Westgaard — Wed, 24 Jun 2026 00:00:00 GMT

I had a mental model of how Terraform module versions get pinned. Roughly the one the documentation implies. You put a version on a module block, maybe a ~> if you want a little room above the floor, and that is the version the repo is on. I believed it well enough that I never bothered to check it.

So I checked it. I parsed the source and version of every module block across a handful of real, organisation-scale Terraform estates and looked at the actual distribution of how versions are written. Two things I was confident about going in turned out to be wrong, and both were more useful wrong than they would have been right, which is the only reason this is worth writing up.

The first wrong thing: I expected versioning style to be a per-repo, sometimes per-module, decision. A mix inside any given organisation. It is not. The second: I expected one widely used ecosystem to be a ~> world that a naive exact-match would mostly miss. It turned out to be overwhelmingly exact pins. I will take them in order. The through-line underneath both is the same. How a module version is pinned is an organisation-level convention rather than a per-module choice, and the shape of the constraint, not the number inside it, is what decides whether you can safely automate a change across the estate.

I went looking for how versions are pinned, and measured it

Method first, because the numbers are the only thing that makes this more than an opinion.

I parsed module source and version across four public corpora, each scanned as a whole organisation rather than cherry-picked repo by repo:

cloudposse, a large and widely used module ecosystem.
terraform-aws-modules, the curated AWS collection.
terraform-google-modules, the curated GCP collection.
A mirrored Azure Verified Modules example corpus. AVM lives inside the very large Azure GitHub organisation and is not cleanly scopeable on its own, so I stood up a throwaway organisation mirroring the real AVM example repositories and scanned that.

Then I ran each constraint string through real Terraform and OpenTofu matching semantics rather than synthetic test cases, so the distribution reflects how these constraints actually resolve, not how I imagine they resolve.

One methodological point matters enough to state up front, because it is part of the argument and not a caveat to bury. I report every figure per corpus and never pool them. A blended "X% of modules pin exact" number across four estates does not describe the world. It describes whichever corpus contributed the most rows. If you take one thing from the method, take that.

Versioning style is an organisation-level convention, not a per-module choice

This is the structural headline, and it is the thing I got most wrong.

Within a single estate, versioning style is close to homogeneous. Not a spread. A house style. cloudposse pins exact: 89% of its module declarations are a bare version = "x.y.z" with no operator, and not a single ~> appears anywhere in the estate. The remainder is almost all git-sourced modules pinned by tag, which is a different problem and a later section. The curated terraform-aws-modules and terraform-google-modules collections are the mirror image, 94% and 95% ~> respectively, with exact pins down in the low single digits. The AVM example corpus lands on the exact-pin side too, overwhelmingly bare pins, around 82%.

That 82% comes with a caveat I want to state in the same breath, because leaving it out would make the number dishonest. The AVM examples are authored by the AVM team and pinned by CI. They over-represent exact pins compared with how real enterprise consumers of those modules actually write their constraints, which leans far more toward ~>. The example corpus tells you the house style of the people writing the modules, not the house style of the people consuming them. Hold onto that when you read the figure.

Four corpora, four single-style camps. The reason this is more useful than I expected is operational. If versioning style were a per-module decision, auditing an estate would mean inspecting every repo, because the last repo would tell you nothing about the next one. Because it is an organisation-level convention, the opposite holds. Learn one repo's convention and you can usually predict the rest of the estate. The unit of analysis is the organisation, not the module. That changes how you scope a migration before you have written a single line of it.

What the constraint shape tells you about blast radius

Once you stop asking "which version is this repo on" and start asking "is this safe to change," the constraint shape stops being a formatting detail and becomes the whole question. The shapes do not carry the same amount of information, and the difference between them is exactly the part that decides whether an automated rewrite lands where you meant it to.

An exact pin tells you what runs. version = "0.3.5" is unambiguous. The repo is on 0.3.5, you know precisely what a change touches, and you can reason about it.

A bounded ~> tells you the band. ~> 0.4.0 allows 0.4.x and stops before 0.5.0. Both arities behave the same way in spirit: ~> 1.2.3 pins the patch floor and holds the minor, ~> 1.2 holds the major and allows any minor above. You do not know the exact version, but you know the ceiling, and a ceiling is most of what you need to reason about safety.

An unbounded >= tells you a floor and nothing else. >= 0.3.0 with no upper bound permits 0.3.0, and it permits 2.4.1, and it permits whatever shipped this morning. This is the dangerous shape. Not because it is common, but because it looks like a version and is actually an open-ended permission.

The rest of the taxonomy fills in around those three. A compound comma-AND like >= 0.3.0, < 0.5.0 is a hand-built band, a floor and a ceiling assembled by someone who wanted ~> behaviour with different edges. A bare version with no operator defaults to exact equality. A != exclusion carves a hole out of an otherwise-open range. Prereleases like 1.0.0-beta1 exist and behave like their own small edge case. None of those are the problem. The problem is the unbounded >=, and here is why it is worse than it looks.

Suppose a tool wants to decide whether a given module block matches >= 0.3.0 so it can rewrite it. The honest answer is that it cannot know which version is actually running. The repo could be on 0.3.0. It could be on 2.4.1. The constraint does not say. So what does a tool do when it has to produce a yes-or-no match against a constraint that genuinely has no single answer? One common shortcut is to floor-normalise: collapse >= 0.3.0 down to a 0.3.0 pin so the comparison succeeds. And the moment it does that, it has quietly decided the repo is sitting on the floor of a range the author deliberately left open.

In an automated rewrite, that is a change landing on a module nobody pointed it at. The author wrote >= 0.3.0 precisely to keep their options open above the floor. The tool read that openness as a pin and edited accordingly. The danger here is not frequency. You could go a long way before this bites. The danger is silence. It produces a confident match and a clean diff, and nothing in the output tells you the match was a guess.

The honest line is to treat the shapes by how much they actually constrain. A bounded ~> carries an implicit ceiling, so normalising it to a concrete version stays inside a band the author already accepted. That is defensible. An unbounded >= carries no ceiling at all, so any concrete reduction is a guess wearing the costume of a match. Until a tool can do real constraint-against-constraint intersection, the conservative behaviour is for a bounded ~> to normalise and an unbounded >= to be an explicit no-match. A miss you can see beats a match you cannot trust.

The modules your version query cannot see

There is one more shape, and it is the one a version audit is structurally blind to.

A module sourced over git carries its version in the source ref, not in a version attribute:

module "example" {
  source = "git::https://example.com/modules/network.git?ref=0.16.0"
}

There is no version line here. The version is the ?ref= on the end of source. Anything that audits an estate by reading the version attribute looks at this block, finds no version, and returns null. It does not flag it. It skips it. Silently, in the same way the floor-normalisation problem is silent, and for a related reason: the tool answered a question the data did not actually contain.

There are two ref shapes, and they are not equally bad. ?ref=0.16.0 is a tag, and a tag is semver-recoverable. You can parse the version back out of the URL if you know to look there. ?ref=main is a branch, and a branch is not recoverable at all. There is no version in main. There is only whatever main pointed at the last time this was applied, which can be something different tomorrow.

This is not hypothetical, and it is not rare. In the cloudposse scan, the same estate that is 89% clean exact pins, almost one in ten module declarations are git-sourced with the version sitting in a ?ref=tags/0.x.0 rather than a version attribute. Those refs are recoverable if you know to parse source. A version audit never looks there, so it returns null for every one of them. The tidiest-looking corpus in the sample keeps nearly a tenth of its module edges out of reach of the obvious query.

Sit with that for a second. A branch ref is the least-pinned dependency in the entire estate. It is more open than >= 0.3.0, because at least >= 0.3.0 names a floor. And it is exactly the dependency your audit cannot see if it only looks at version. The most dangerous edges hide in the place most tooling does not think to look.

Why this is a discovery problem

I want to be fair to the tools that do the other half of this, because they are genuinely good at it.

The actual rewrite, the part where you move a shared module from 0.3.x to 0.4.0 across dozens of repos, is a solved and deterministic problem. OpenRewrite's HCL recipes do exactly this, and they do it well. Point a recipe at code that matches its filter and it produces a clean, reviewable diff with every matching module block flipped and nothing else touched. I have a lot of respect for that work. It is careful, it is deterministic, and it is the easy half.

It is the easy half because it assumes the hard half is already done. A rewrite recipe is only as good as the set of repos you point it at and the accuracy of the version it thinks each one is on. And that, as the last few sections argued, is where it gets quietly hard. Which repos consume the module. Under which constraint shape. And which ones a naive version query cannot even see because the version is hiding in a git:: ref. That is not an apply problem. It is a discovery problem, and it sits upstream of every rewrite tool, every codemod, and every careful sed across the org.

People do solve discovery today, mostly with grep and scripts, and at small scale that is completely fine. A grep -r 'source =' . across a dozen repos will get you most of the way. It starts to break on exactly the subtleties this post is about. It treats >= 0.3.0 and 0.3.0 as different strings without understanding that one is a pin and the other is an open range. It returns nothing for a git::...?ref=main module because there is no version to grep for. It works right up until the estate is big enough, or heterogeneous enough, that the edge cases stop being edge cases. (Symbol-graph tools like Sourcegraph are excellent at what they do and entirely orthogonal to this. A module source edge is not a code symbol. Different category.)

This is the problem Riftmap exists to solve. It parses the dependency edges your repos already declare, the Terraform source and version, the Dockerfile FROM, the CI include, the Helm references, across your whole GitHub or GitLab organisation, and builds the graph underneath them. Parsed, not inferred. So when you ask "if I change this module, what consumes it, and under which constraint shape," the answer is read off declared manifests rather than guessed from names or text. It is the same discovery question whether you are deprecating an internal module or chasing a CVE through your base images: the blast radius is the product. The rewrite is what you run once you can see it.

A version constraint feels like a fact about what is running. It is not. It is a record of what the author was willing to allow. An exact pin happens to make those two things identical, which is probably why it is so easy to forget they were ever different. The unbounded ranges and the branch refs are where they come apart, and treating the permission as a fact is precisely how an automated change ends up somewhere nobody asked it to go.

You changed the shared CI template. Half the org got it instantly. The other half will never see it.

Daniel Westgaard — Tue, 23 Jun 2026 00:00:00 GMT

Every guide on shared CI tells you how to write a reusable template. Almost none tell you how to change one you already have. The hard part was never the YAML. It is that a single edit ships to two disjoint sets of repos, on two different clocks, and your CI platform shows you neither set.

Someone on your platform team made a small, careful change to the shared pipeline.

Call the project platform/ci. It started as one file and grew into a little library: a build template, a deploy template, a security-scanning include, some shared rules. Most of the org consumes it. Nobody knows exactly how much of the org, because nothing in the product counts for you. The change itself was trivial and correct. A job called test was doing two things, so they split it and renamed the original to unit-test, the way you would tidy any file you owned. They ran it against their own repo, the pipeline went green, they merged.

Eight minutes later, the first Slack message. Then four more. Services that nobody on the platform team had ever opened were failing at the pipeline-creation step, before a single job ran, because their .gitlab-ci.yml does extends: .test and there is no longer a job called test to extend from. GitLab's own template guide spells the mechanic out plainly: rename a job that downstream pipelines depend on and the consumer's config immediately fails to lint, because the job it references no longer exists. The on-call engineer traced it back, the platform team added test as a thin alias for unit-test, shipped again, and the bleeding stopped. Forty minutes, start to finish. Everyone moved on.

For five months, nothing.

Then a payments service that had not been actively developed in over a year picked up an unrelated dependency bump, which meant someone finally moved its pinned ref: v1.4.0 forward to pull the fix. It inherited the eighteen months of template changes it had slept through, including the test rename, including a few others, all at once. It broke in staging on a Tuesday, and the engineer who got the page had no reason to connect it to a change the platform team had made and forgotten about two quarters earlier. The blame landed on the dependency bump, because that was the visible change. The actual cause had been sitting in platform/ci since spring.

The part I keep coming back to is that the same one-line edit broke two completely different sets of repositories, at two different times, for two opposite reasons. One set broke instantly because it was tracking the template's branch. The other broke months later because it was not. And on the morning of the merge, the platform team could see neither set. They found out who the first group was from the Slack messages. They will never find out who the second group is, because the second group breaks alone, later, attributed to something else.

A shared CI change is two deployments wearing one merge

We talk about changing a shared CI template as one action. It is two, and they have almost nothing in common except the commit that triggers them.

The first is a deployment to every consumer that tracks a moving reference. For these repos, your merge is not a proposal they get to evaluate. It is a push straight to their next pipeline run. No rollout, no canary, no opt-in. If the change is breaking, they break at merge time, in their own projects, at whatever moment they next happen to run CI. The blast radius is the whole tracking population and it detonates the instant you click merge.

The second is a deployment to every consumer pinned to a fixed reference, and it is the strange one, because it has not happened yet and might not happen for a year. These repos are frozen on the version they pinned. Your change is real, it is merged, it is live for everyone else, and it is completely invisible to them. They will receive it at some unknowable future point, whenever someone bumps the pin, usually for an unrelated reason, usually long after anyone remembers what changed. When they receive it, they get the entire accumulated diff in one jump, decoupled from any context that would help them debug it.

So one change produces an instant, loud failure in one group and a deferred, silent, context-free failure in another. Worst of all, you do not know which of your consumers are in which group. The pin or its absence is the single most important fact about how a consumer will react to your change, and it is a fact you do not hold. This is the conflation the whole problem sits on. "Changing the template" sounds like one job with one audience. It is two deployments to two audiences on two clocks, and the only thing standing between you and a clean change is a census you were never given.

The half that breaks while you watch

The instant half is the one people have at least felt, because it shows up in the chat channel the same afternoon. The mechanics differ by platform, and the mechanics matter, because they decide how much of your org is in the instant bucket by default.

GitLab: the unpinned include detonates at merge

In GitLab CI, the ref: on a project include is optional. When you leave it out, the include resolves to the HEAD of the template project's default branch, at pipeline creation time. That is documented behaviour in the CI/CD YAML reference, not an accident, and in practice most includes in most orgs are written without a ref because that is the shortest thing that works:

# In some-service/.gitlab-ci.yml
include:
  - project: 'platform/ci'
    file: '/templates/build.yml'
# no ref: tracks platform/ci's default branch HEAD

Every repo that wrote it this way is riding your main. A merge to platform/ci is not a release to them. It is an instant, org-wide deployment of CI configuration to every consumer that did not pin. GitLab says as much in its own docs: including another project's configuration is, from a security standpoint, like pulling a third-party dependency, and no pipeline or notification fires when that other project's files change. The dependency is real and it is silent. The default configuration is the dangerous one.

This is not a theoretical risk that only bites small teams. GitLab has lived it at the scale of the largest CI template library in existence, and the GitLab CI template edition of the Find Every Consumer series walks through the receipts: a default-branch rename that broke templates with hardcoded refs, and a GitLab engineer candidly describing blast-radius monitoring that amounts to waiting for customers to complain. If the maintainers of GitLab's own templates operate partially blind here, the platform/ci repo in your org is not an outlier.

GitHub: a moving ref ships on the next run

GitHub Actions makes the same trap available with slightly different ergonomics. A reusable workflow or composite action is called by uses:, and unlike a GitLab include, uses: always requires a reference. So every caller pins to something. The catch is that "something" is very often a branch:

jobs:
  build:
    uses: my-org/ci/.github/workflows/build.yml@main   # moving: next run picks up your change
    # vs @v1            -> a tag, only as frozen as the maintainer's discipline
    # vs @9a8b7c6...    -> a full SHA, the only genuinely immutable pin

@main behaves exactly like the unpinned GitLab include. The caller picks up your change on its next run, with no opt-in. A tag like @v1 looks safer, and is the advice everyone gives, but a git tag is mutable. It is only frozen if the maintainers never re-point it, which is why GitHub's own supply-chain hardening guidance recommends pinning third-party actions to a full-length commit SHA rather than a tag. The implication for you, the template maintainer, is the same as on GitLab: some unknown fraction of your callers are tracking a moving target and will take your next change immediately, and you cannot tell which from the inside.

The transitive case sharpens it on both platforms. Template repos include other template repos. A reusable workflow uses: a composite action that uses: another. If you change a base template that a wrapper template includes, the repos that break are the ones that included the wrapper, which may never have heard of the base. They depend on you through a layer they did not write and cannot see. Finding the direct callers is a string search. Finding the transitive ones is a graph traversal, which is the whole reason the per-ecosystem editions of this series exist: the reusable GitHub Actions workflow edition covers the call-graph mechanics in full, and they do not reduce to grep.

The half you never hear from

The pinned consumers are the half nobody plans for, because they make no noise. They are green in CI, building against the version they froze, contributing nothing to your sense of who depends on you. Every signal you have about your consumer base comes from the consumers who are active and tracking. The pinned, dormant ones are statistically invisible right up until the moment they wake up and break.

And when they break, they break in the worst possible way for debugging. They receive your change divorced from its context. The engineer on that payments service did not get "the test job was renamed three months ago," with a changelog and a migration note attached. They got a pipeline that suddenly would not start, bundled with a dependency bump and whatever else had accumulated on platform/ci since they last pinned. The cause was a quarter old and wearing someone else's clothes.

This is the precise failure mode the internal library deprecation post is built around, and it is worth being explicit that CI is the same problem in a harsher form. There, a service that pinned an old version of a shared package and went quiet never saw the deprecation warning, because the warning lived in a version it was not pulling. The quiet, pinned consumer is the one that breaks, in both cases, because quiet is exactly what "we pinned it and stopped thinking about it" looks like from the outside. The difference, and the reason CI is worse, is what you have to reach them with.

CI is the one shared dependency with no signal layer

Here is the part that makes a CI template change genuinely harder than a library deprecation, rather than just an instance of it.

When you deprecate a shared library, the playbook hands you real signalling machinery. It is conditional and often silent, and the deprecation post takes that machinery apart in detail, but it exists. You can add a @deprecated annotation that an active consumer's editor will flag. You can raise a DeprecationWarning that a test suite can surface. You can cut a semver major so the removal lands on a boundary tooling is built to respect. npm will even print npm WARN deprecated on install. None of it reaches a pinned, dormant consumer reliably, which is the deprecation post's whole argument, but for the consumers who are paying attention, there is a channel.

A shared CI template has none of this. There is no @deprecated for a job name. There is no warning you can attach to an extends target that fires when a downstream pipeline relies on it. There is no semver boundary, because most include:project and @main consumers are not pinning versions at all, and the loosely typed surface a template actually exposes, the job names, the variables, the extends targets, has no declared interface to mark up in the first place. GitLab's newer spec:inputs gives components something like a typed contract, which is real progress, but it covers a sliver of the installed base. The fleet of include:project templates that nearly every self-managed estate runs on communicates entirely through job names and variables that no compiler checks.

Strip it down and the signalling options for a CI template change are exactly two. The instant consumers find out when their pipeline turns red, which is to say after the change has already broken them, which is not a signal so much as a casualty report. The pinned consumers find out never, until they bump. The one human channel left is an announcement in a chat channel, and the deprecation post already covers why that reaches everyone except the people you most need it to reach: the team that pinned your template eighteen months ago and reorganised twice is, by definition, the team not reading your announcement.

So for a library, signalling is the easy half of the job and the census is the hard half. For a shared CI template, the signalling half very nearly does not exist. There is no annotation, no warning, no version boundary, no typed interface, nothing between your merge and someone else's red pipeline. Which leaves the census not as the harder half of the work. It leaves the census as essentially all of it.

Neither platform shows you the roster

Once it is clear that the signal will not assemble the consumer list for you, you go to build it by hand, and every route gets you partway to the same wall. I want to be fair to each, because some of them are genuinely useful for part of the problem.

Code search is the obvious first move and it works for a one-off. Search your group for the template path and you get matches. What you do not get is the ref, the distinction between a real include: and a comment that mentions the path, or the second hop where a wrapper template hides the forty repos behind it. On GitLab, the good version of code search is the Premium advanced search, which on self-managed you have to stand up and operate yourself. On GitHub, search will not surface reusable-workflow callers across private repos as a clean roster either. Matches are a starting point. They are not a system, and they are certainly not a list with refs and owners attached.

The platforms' native dependency views are scoped to the wrong place. GitHub has a Dependents tab built for almost exactly this question, and it only computes dependents for public repositories. Your shared CI lives in a private org, which is the one case it does not cover. GitLab deserves real credit here, because it has started to answer the question: the GitLab 19.0 CI/CD Catalog components analytics view shows usage counts and, on Ultimate, which projects used a component recently and on which version. But look closely at what that covers. It covers include:component, resources published to the Catalog, on a thirty-day usage window derived from pipelines that actually ran, with the per-project drill-down gated to Ultimate. The include:project template fleets that nearly every enterprise estate actually runs on, including the platform/ci repo in the scene above, are out of scope. The gap is closing for components on the newest tier. For everyone else it is wide open.

Then you write the script, and several teams have, which is the strongest possible evidence that the question matters. Enumerate every project, fetch every CI config, parse the YAML, extract the includes and uses: calls, resolve the refs, handle the five different GitLab include forms and the remote includes a literal search misses, reconstruct the nested chains, page through the API, respect the rate limits, run it on a schedule, store the result. That is a real system with a real backlog, and the corner cases are now yours to maintain. The full enumeration mechanics, per platform, are exactly what the GitLab CI template and GitHub Actions workflow editions of this series document, so I will not re-derive them here. The point for this post is one level up: whichever route you take, you are trying to reconstruct, by hand, a list the platform could have kept and did not.

The list is a graph query, not a search

Strip the problem back to what you actually need before you touch a shared template, and it is small and specific. Every repository whose CI configuration references this template, directly or transitively. The reference each one declares, and crucially whether it is a moving ref or a pinned one, because that single fact sorts every consumer into the instant bucket or the silent bucket. The team that owns each repo, so you know who to route a migration to. And the order, so you change the base template before the wrappers that include it.

That is a query against a graph of dependency edges, and the only honest way to build the graph is to parse it. Read the include: entries in every .gitlab-ci.yml, resolving project, remote and component forms back to the repos they point at and ignoring local and GitLab-shipped template: includes, which are noise in a consumer map. Read the uses: in every .github/workflows/*.yml, following reusable workflows and composite actions. Read the template files that template repos themselves carry, so the nested chain from a base template to its end consumers is in the graph and not just the wrapper that includes it directly. Record the ref each consumer declares, or its absence, as a first-class fact. Parsed, not inferred. Not counted from thirty days of pipeline runs, not read off a wiki page someone last edited before the reorg, not pieced together from a chat thread. Read from the CI config that already declares the edge, because that file is the source of truth and it is also exactly where any migration is going to land.

The pin-or-no-pin column is the one that turns this from a list into a plan. With it, "who breaks at merge and who has time" stops being a guess. You can see the repos riding an unpinned include or a @main and know they take the change instantly, so they are the ones to fix or warn first. You can see the repos frozen on an old tag and know they are stranded, carrying a debt that comes due whenever they next bump, so they are the ones to migrate deliberately before they wake up and break alone. Two buckets, two plans, derived from a column the platform never gave you.

Why the template calcifies

There is a second cost to not being able to see the roster, and it is quieter than the incident, which is why it is worse over time.

When you cannot enumerate who consumes a shared template, the rational thing to do is to never restructure it. Think about what a clean refactor of platform/ci would ask of you. To rename that job properly, to collapse two templates into one, to drop a variable nobody should be using any more, you have to be willing to say "this will not break anyone," and if you are wrong, it breaks at merge time, org-wide, in other people's projects, with your name on the commit. "I am fairly sure nothing extends from this" is not a sentence you want to be holding when forty pipelines fail to start. So the safe move, the locally rational move, is to never make the structural change. Add a new job beside the old one instead of renaming it. Bolt a new variable on rather than reworking the interface. Leave the dead path in, just in case.

This is how shared CI templates turn into append-only sprawl. Not because nobody wants to clean them up. Because removal and restructuring are unprovable-safe, and the cost of being wrong is paid in production at an inconvenient hour by someone else. The template accretes jobs, flags, and compatibility shims, each one cheap to add and impossible to remove, until it is a file nobody fully understands and everybody is slightly afraid of. The same dynamic that leaves undead modules in a codebase leaves undead jobs in your pipeline library, for the same reason: you cannot prove the removal is safe, so you never attempt it.

A trustworthy consumer census changes the calculus entirely. When "who consumes this template, at which ref, owned by whom" is one query, restructuring stops being a gamble and becomes a scheduled piece of work. You see the four repos that extend the job you want to rename, you route the change, you watch the number go to zero, and then you rename it for real. The census is not only the thing you reach for the morning a pipeline falls over. It is the thing that lets a shared template get smaller instead of only ever larger.

Two rosters, one merge button

So, stripped down. Changing a shared CI template is two deployments wearing one merge, and the renamed job showed which audience each one reaches.

One deployment is instant and loud. It ships to every consumer tracking your branch, an unpinned GitLab include or a GitHub @main, the moment you merge, and you hear about it the same afternoon when their pipelines turn red. The other is deferred and silent. It waits, fully merged and completely invisible, on every consumer pinned to a tag, until some unrelated bump pulls them forward into the accumulated change and breaks them alone, months later, blamed on something else. The signalling machinery that would warn either group barely exists for CI: no annotation, no warning, no version boundary, no typed interface, nothing between your edit and someone else's failed pipeline.

Which means the roster is the whole game. Not the harder half of the job, the way it is for a library. The entire job. And the roster for both buckets, the instant one and the silent one, with the pin or its absence beside every consumer, was sitting in the CI config across your org the whole time. The template that fifty projects include without a ref is the highest-leverage, least-observed dependency you own. Parse who depends on it before you press merge, because the platform will not, and the alternative is finding out from the people you should have told.

This is the query Riftmap is built to answer. Point it at your GitHub or GitLab organisation with one read-only token and it parses the CI edges across every repo: include:project, include:remote and include:component on GitLab, reusable-workflow and composite-action uses: on GitHub, plus the multi-project triggers and cross-project needs: a string search misses, while deliberately skipping the local and platform-shipped includes that are noise. It parses the template repos' own files too, so the transitive chain from a base template to its end consumers is in the graph. Each edge carries the ref the consumer declares, or its absence, plus the file and line where it lives. Before you merge that job rename, you open the graph, click the template, and read the consumer list, sorted into the ones riding your branch and the ones frozen on a tag. You know who breaks now, who breaks later, and who to tell, instead of finding out who you should have told. And if you want that check to run itself, the blast-radius gate recipe wires the same consumer count into a CI job on every merge request.

Riftmap maps cross-repo dependencies across your entire GitLab or GitHub organisation: Terraform, Docker, CI templates and components, Helm, npm, Go, Python, and more. One read-only token. No YAML to maintain. The free tier is here.

Appendix: the argument in short

Claim. Changing a shared CI template is treated as a single task and is actually two deployments. One ships instantly to consumers tracking a moving ref (an unpinned GitLab include:project, a GitHub @main) and breaks them at merge time. The other waits, silent and invisible, on consumers pinned to a tag, and breaks them alone whenever they next bump the pin, decoupled from any context. CI is worse than a library deprecation because it has essentially no signalling layer: no @deprecated, no DeprecationWarning, no semver boundary, no typed interface for job names and variables. That leaves the consumer census as not the hard half of the job but the whole of it, and the census can only be built by parsing the include: and uses: edges every repo's CI config already declares, with the ref or its absence recorded against each consumer.

Consumer census (CI edition). The set of repositories whose CI configuration references a given shared template, directly or transitively, with the reference each one declares (and specifically whether it is moving or pinned) and the team that owns it, derived by parsing .gitlab-ci.yml and .github/workflows/*.yml across an organisation rather than from usage telemetry, a wiki, or an announcement.

FAQ.

If I change a shared CI template, which pipelines break? Two separate groups, on two timelines. Consumers tracking a moving ref (an unpinned GitLab include:project, which resolves to the template project's default-branch HEAD, or a GitHub uses: ...@main) take the change on their next pipeline run and break immediately. Consumers pinned to a tag or SHA do not see the change until someone bumps the pin, then receive the whole accumulated diff at once. Neither GitLab nor GitHub gives the maintainer the list of which consumers are in which group.
How do I safely change a shared CI template used across many repos? Build the consumer census first. Parse the include: and uses: edges across every repo, record the ref each consumer declares (or its absence), and sort consumers into the moving-ref group that breaks at merge and the pinned group that is stranded. Change base templates before the wrappers that include them. The signal will not do this for you, because a CI template has no deprecation-warning mechanism.
Why does a GitLab CI include without a ref get template changes instantly? Because an omitted ref: on a project include resolves to the HEAD of the template project's default branch at pipeline creation time, which is documented behaviour. A merge to that branch is therefore an immediate, org-wide deployment to every consumer that did not pin, with no notification fired.
Can GitHub's Dependents view or GitLab's Catalog analytics tell me who consumes my CI template? Partially, and not for the common case. GitHub's dependency graph computes dependents for public repositories only, so a private org's shared workflow is not covered. GitLab's CI/CD Catalog components analytics covers published Catalog components on a thirty-day usage window, with per-project detail on Ultimate, but not the include:project template fleets most self-managed estates actually run on.

Related reading.

How to find every consumer of your GitLab CI template — the full GitLab-side enumeration mechanics this post sits on top of: the five include forms, nested chains, triggers and cross-project needs.
How to find every consumer of your reusable GitHub Actions workflow — the same enumeration, for reusable workflows and composite actions.
You deprecated the internal library. The repos still using it never saw the warning — the sibling post. Same census-versus-signal split, but for libraries, which at least have a signalling layer; CI is the limit case where that layer is gone.
A CVE just hit your base image. Your scanner won't tell you which repos to fix — the reactive twin: the same cross-repo-versus-single-artifact gap, forced by an external shock instead of a planned edit.
Your senior engineer just left. Your bus factor was measuring the wrong thing — what happens when the person who held the consumer map in their head walks out.
GitLab Orbit maps your whole SDLC. It still can't tell you what an infrastructure change will break — why a CI include edge is an artifact edge a symbol graph cannot see.
The catalog maintenance trap — why the hand-maintained "consumers of this template" wiki page is wrong by the time you read it.
What is cross-repo dependency mapping? — the glossary definition of the parsed graph this post keeps pointing at.

How to Find Every Consumer of Your Ansible Role

Daniel Westgaard — Sun, 21 Jun 2026 00:00:00 GMT

You have got a one-line fix for the hardening role. A sysctl value that should have been set from the start, the kind of change nobody notices until an auditor does. You open the role's repository, make the edit, and reach for a tag.

Then the question lands, the way it always does right before you cut a release. Who gets this?

You look at the repository in front of you for an answer. There is a tasks/ directory, a defaults/main.yml, a meta/main.yml, and a README that three people have edited and nobody has read. None of it names a single playbook that uses the role. Nothing inside the role knows who depends on it. That information lives somewhere else, in repositories you are not currently looking at, and the role has no way to point you towards them.

This is not your team being sloppy. It is structural, and Ansible chose it on purpose.

Here is the proof. Back in 2016, Jeff Geerling, who maintains more widely used Ansible roles than almost anyone alive, filed a request for a lock file. Something like package-lock.json or poetry.lock, a file that records exactly which version of each role and collection actually resolved, so a run is reproducible and you can see what you are really shipping. The request sat. When the old issue tracker was archived years later, it was carried over and then quietly abandoned. A decade on, Ansible still has no native lock file.

Sit with what that means. Every other ecosystem in this series at least commits to telling you which version is installed. npm has package-lock.json. Go has go.sum. Python has its various lock formats. Ansible looked at that primitive and decided not to build it. And if the ecosystem will not commit to telling you what version of a role actually ran, it is certainly not going to tell you who consumes that role across your organisation. The reverse question, the one you are asking right now with your finger over the tag, was never in scope.

So let us answer it properly. If you change a shared Ansible role, what breaks? And how do you find every consumer before you find out the hard way?

Where your role actually gets used

Start with the shape of the problem, because Ansible reuse spreads a role's dependents across more places than people expect.

The canonical layout, the one the official best practice points you towards, is one repository for your playbooks and a separate repository per role. The playbook repository pulls the roles it needs through a requirements.yml:

# platform-playbooks/roles/requirements.yml
roles:
  - name: hardening
    src: https://gitlab.example.com/platform/ansible-role-hardening.git
    scm: git
    version: v2.3.0

  - name: geerlingguy.nginx
    version: "3.1.4"

collections:
  - name: polaris.infrastructure
    source: https://automationhub.example.com/api/galaxy/
    version: ">=1.4.0,<2.0.0"

  - name: community.crypto

That is one site where your role's consumers live. There are several more, and they do not look alike.

A play can pull a role in directly at the play level:

- hosts: webservers
  roles:
    - hardening
    - role: geerlingguy.nginx

A task can pull one in dynamically or statically, anywhere in the tasks section:

tasks:
  - ansible.builtin.import_role:
      name: hardening

  - ansible.builtin.include_role:
      name: hardening

And a role can pull in another role as a dependency, declared in its own meta/main.yml, which then runs before it, recursively:

# ansible-role-webserver/meta/main.yml
dependencies:
  - role: hardening

Read that last one again, because it is the one that bites. If webserver depends on hardening in its metadata, then every playbook that uses webserver is also a consumer of hardening, and not one of those playbooks mentions hardening anywhere. The dependency is real, it runs in production, and it is invisible to anyone searching the playbook repositories for the word "hardening".

So the consumers of your role are scattered across requirements.yml files, play-level roles: keys, import_role and include_role tasks, and the meta/main.yml of other roles. Every one of those lives in a repository other than the one you are about to tag. None of them is listed anywhere central. This is the same structural fact behind the whole Find Every Consumer series: the dependency lives in the relationship between repositories, and the artifact you are changing cannot see its own dependents. It is the exact shape we covered for Terraform modules pulled by git source, only Ansible has more entry points and weaker typing.

The version you cannot see

Now layer the lock file problem back on top, because it turns a hard problem into a worse one.

Look again at the requirements.yml above. The hardening role is pinned to v2.3.0. The polaris.infrastructure collection is pinned to a range, >=1.4.0,<2.0.0. The community.crypto collection has no version at all. Each of these is a different relationship to the thing you are about to release, and you have probably got all three patterns live across your estate right now.

When a version is absent, ansible-galaxy install takes the latest it can find. When it is a range, you get the newest release inside the range at install time. When it is a branch or main, you get whatever that branch points at the moment the pipeline runs. And here is the part with no safety net: nothing writes down what actually resolved. There is no lock file to read afterwards. With npm you can at least open package-lock.json and see the truth, which is why "the change you ship without shipping it" was the core of the npm post. In Ansible you cannot, because the file that would hold that truth was never built.

So tagging v2.4.0 of your role is not shipping a change to a known list of consumers at a known version. It is a fan-out to an unknown set of repositories, an unknown number of which are pinned, ranged, or floating, resolving on a schedule you do not control, with no record of what each one actually ran. You are pushing a change into a system that has deliberately chosen not to remember its own state.

The first thing a real answer has to do, then, is the thing the ecosystem refuses to. It has to tell you, for every consumer, whether they pinned you, ranged you, or left it floating. "Who is unpinned" is not a nice-to-have. In an ecosystem with no lock file, it is the single most important fact about your blast radius, because the unpinned consumers are the ones that will move the moment you tag, without anyone deciding to.

What Ansible's own tooling tells you, and where it stops

The Ansible toolchain is genuinely good, and it answers real questions. It just answers the other ones.

ansible-galaxy collection list and ansible-galaxy role list tell you what is installed in the environment you are standing in. That is forward, local, and per-environment. There is no ansible why. The CLI will happily tell you that a collection is present; it has no concept of which of your repositories declared it, let alone which tasks use it.

ansible-inventory --graph --vars and --host will reconstruct what a given host ends up with, variables and all. Again, forward, and per-host. It answers "what does this host get", never "who across my repositories consumes this".

ansible-lint and Molecule are excellent, and you should be running both. ansible-lint in particular will flag short module names, deprecated syntax, and a long list of anti-patterns. But linting is per-project quality enforcement and Molecule is per-role testing. Neither builds a cross-repository map of who depends on what. They make each repository better in isolation; they do not connect them.

It is worth noting how often engineers reach past all of this and build the reverse lookup themselves. There is a published tool, ansible-discover, whose entire purpose is to list the dependants of a role so you can trigger the right CI jobs when it changes. There is ansible-variables, which exists to trace where a host's variables actually come from. Both are small, both are local-path, both work only across the repositories you have already checked out together. They are proof that the question matters enough for people to keep writing the same tool, and they define the gap precisely: the moment the answer spans repositories that are not on one disk at one time, these stop.

Then there is the registry layer, and this is where people most often expect the answer to live, because it feels like it should. Ansible Galaxy, Automation Hub, and a private Automation Hub do distribution, curation, governance, and supply-chain control, and they do it well. What they record is publication and downloads. A download count is not a dependency edge. Knowing that polaris.infrastructure was pulled four hundred times this month tells you nothing about which of your repositories declared it, which tasks call into it, or what breaks if you change it. This is the same trap as the Go module proxy: the proxy logs fetches, and a fetch is not a use.

Automation Controller, AWX, and the wider Automation Platform sit one layer up and know about Projects, where each Project is a git repository the controller syncs and whose requirements.yml it installs at sync time. Automation Analytics will report on job runs, host counts, and ROI. All useful, all runtime. The controller knows which Projects exist and installs their requirements; it does not parse and present a cross-Project graph of which Projects depend on which role. It answers "what ran" and "what runs", not "what is declared, everywhere, right now". It is the same distinction we drew for GitLab's pipeline analytics, where usage events told you about executions and never about the static set of repositories that include a thing.

And the update bots, which are the closest any of these come to caring about consumers? They treat Ansible as a second-class citizen. Renovate does have an ansible-galaxy manager that will bump role and collection versions per consumer, which means it implicitly knows about the repositories it is switched on for. But its data source for collections ignores a custom source: and falls back to public Galaxy, so for an internal collection served from your own Automation Hub, the exact case where blast radius is your problem, Renovate is effectively looking at the wrong registry. Dependabot does not support Ansible Galaxy at all. The feature request has been open since 2021 with a steady trickle of thumbs-up and no support. Even the ecosystem built to watch your dependencies for you does not watch these.

Every tool above answers a forward question or a distribution question. What is installed here. What does this host get. What did Galaxy serve. What ran last night. Not one of them answers the only question that matters when your finger is on the tag: across all of my repositories, who consumes this role, at what version pin, and what breaks if I change it.

Why this is harder than it looks

You might reasonably think this is a grep problem. Search every repository for the role name, collect the hits, done. It is not, and the reasons are specific to how Ansible resolves things at runtime rather than at parse time.

A role's real interface is variables it never declares

This is the hardest thing in Ansible, and it is worth slowing down for, because it is the one that has no clean answer anywhere.

A role's true contract is not its name. It is the set of variables it reads. And in Ansible, those variables are supplied by the consumer, not declared by the role. Your hardening role reads hardening_sysctl_overrides. It does not, and cannot, list that as a typed input the way a function signature would. The value is set somewhere out in the consumer's world: in a group_vars/webservers.yml, in a host_vars file, in a vars: block on a play, in an --extra-vars flag in a pipeline, in a set_fact. Ansible resolves which one wins through a precedence order with more than twenty levels, and role defaults sit very near the bottom of it, which is the source of a thousand confused afternoons.

Now rename that variable. Ship hardening v2.4.0 where hardening_sysctl_overrides becomes hardening_sysctl_config. Nothing errors at parse time. There is no compile step to fail. The old variable simply stops being read, the new one falls back to its default, and a hardening setting silently reverts on every host whose consumer set the value under the old name. There is no grep target, because the breaking change is the absence of a string near a role reference that does not textually mention the role at all. The consumer set a variable; it never said which role the variable was for.

This is the inverted contract at the heart of Ansible reuse. The role depends on inputs it does not declare. The playbook declares inputs without saying which role they feed. The dependency edge has no home in either file. It is the reason this is genuinely harder than any of the manifest-based ecosystems in this series, and, as we will get to, it is also the honest boundary of what any tool that reads source can claim.

The same module call has two spellings

A collection ships modules, and the real blast radius of a collection is every task that calls one of its modules. Ansible lets you write that call two ways. Fully qualified, polaris.infrastructure.configure_firewall, or as a bare configure_firewall with a play-level collections: keyword setting up a search path.

The catch is that the short form is on the way out. The official documentation describes the collections: keyword as a temporary mechanism from the 2.9 transition and tells you to rewrite content that uses it and prefer the fully qualified name. ansible-lint actively flags it. So modern, well-written playbooks tend to use the fully qualified name directly in every task and carry no collections: block at all. Which means a grep for the short name misses the modern callers, a grep for the fully qualified name misses the legacy ones, and the bare short name collides with built-ins and with identically named modules in other collections. The usage edge for a collection is real, it is increasingly written in fully qualified form in task bodies, and it is precisely where naive search is weakest.

Static and dynamic inclusion do not grep the same

roles: and import_role are static. Ansible processes them at parse time, so the role name is right there in the file. include_role is dynamic, evaluated at runtime, and it can take a computed name:

- ansible.builtin.include_role:
    name: "{{ role_for_this_environment }}"

There is no string hardening to find here. The consumer relationship is a variable that resolves during the run. This is unresolvable from source by anyone, including us, and any tool that claims otherwise is guessing. The honest move is to find the literal cases and be straight about the computed ones.

Dependencies hide behind other dependencies

Back to meta/main.yml. Role dependencies are recursive and run before the role that declares them. If webserver depends on hardening, and app-tier depends on webserver, then a playbook using app-tier is a transitive consumer of hardening two hops away, naming neither intermediate. Finding direct consumers is a string search. Finding transitive ones is a graph traversal, and you cannot fake a graph traversal with grep, which is the same wall we hit with nested GitLab CI includes.

The declaration is not in one place

Even the manifest is not one file. A requirements.yml can pull in other requirements files with an include: directive. Collections get declared in requirements.yml, in a collection's own galaxy.yml dependencies, in role metadata, and in execution-environment definitions that bundle a requirements file into a container image. ansible.cfg can redirect where roles and collections resolve from with roles_path and collections_path. The string that represents your role appears in a different shape in each of these, and a tool that reads only the root requirements.yml of each repository will quietly undercount.

What the full answer requires

Put all of that together and the requirements for actually answering "who consumes this role" fall out:

Scan every repository in the organisation, with no opt-in and no per-repo config. The consumers live in repositories other than the one you are changing, so anything that needs each team to register or annotate will be incomplete the day someone forgets.
Parse every declaration site, not just the obvious one. requirements.yml roles and collections, galaxy.yml dependencies, and meta/main.yml role-to-role dependencies, at minimum.
Capture usage edges, not only install edges. Who declared the role in a manifest is one thing. Who actually invokes it through roles:, import_role, and include_role, and who calls into a collection through fully qualified module names in task bodies, is the thing that breaks.
Reconstruct transitive role-dependency chains, so a consumer two hops away through meta dependencies is counted, not missed.
Resolve names to the in-org repository that produces the artifact, including git-URL sources, with a guard against a public role or collection that happens to share a name with one of yours.
Record the declared version constraint, or its absence. Since there is no lock file, the queryable fact you can offer is who pinned you, who ranged you, and who left it floating.
Stay current by re-scanning, not by trusting run telemetry. What ran last week is not what is declared today.
Make it one query, because a real answer you have to assemble by hand across forty repositories is not an answer you will actually run before a release.

How Riftmap does this

This is the gap Riftmap was built to close, so here is honestly what it does and does not do for Ansible.

Riftmap scans a GitLab or GitHub organisation and parses every repository deterministically. There is no language model in the parse path; the dependency edges come from parsing the actual files, and each edge carries a rule-based confidence score. That last point matters for Ansible specifically, because some of these edges are genuinely more certain than others, and the tool says so rather than flattening everything to a confident-looking line.

On the consumer side, it reads roles from requirements.yml, from meta/main.yml dependencies, and from play-level roles:, import_role, and include_role, including the modern ansible.builtin.include_role form and includes nested inside block, rescue, and always. It reads collections from requirements.yml, from galaxy.yml dependencies, from the play-level collections: keyword, and, crucially, from fully qualified module calls in task bodies, which is the usage edge that the fading collections: keyword is being replaced by. Manifest declarations resolve at full confidence; a play-level roles: entry or an include_role name is scored a little lower, because it might point at a role bundled in the same repository rather than a shared one; a fully qualified module call is scored lower still and filtered against a denylist of public namespaces so the graph is about your collections, not ansible.builtin.

On the producer side, it detects which repository publishes a role, from its meta/main.yml galaxy metadata, and which publishes a collection, from its galaxy.yml. An edge forms when a consumer declaration resolves to a producer in the same organisation. A role or collection pulled by git URL resolves to the in-org repository that produces it, which sounds obvious and was, until recently, exactly where things slipped: a collection declared by a bare git source: with no name used to be parsed and then dropped on the floor, because the resolver had no git fallback for collections. It became a permanent external edge even when the producing repository was sitting right there in the org. That is fixed now, and it is a good illustration of how well infrastructure hides its own edges, that a tool built specifically to find them still had a blind spot for the case where the dependency was declared by URL.

Because the whole thing is a graph, the transitive case is handled. The impact traversal walks meta dependency chains, so when you ask what breaks if you change hardening, you get the playbooks two hops away through webserver and app-tier, which is the answer grep structurally cannot give you. Riftmap uses no graph database to do this, just PostgreSQL and a breadth-first walk in application code, which is a deliberate choice covered elsewhere, but the relevant point here is that the traversal exists.

And the version-state question, the one the missing lock file makes load-bearing, is answered directly. Every consumer of a role or collection carries its constraint state: pinned to an exact version, floating on a range, riding a branch, or absent entirely, and it flags the ones already trailing the latest release. You can filter those consumers down to the unpinned ones and read off, in one number, how many repositories will move the instant you tag, with nobody deciding to. That is the "who is unpinned" answer the opening of this post said you needed, and it is a filter, not a research project.

The same view works for a role or a collection. Here it is for an internal collection, polaris.infrastructure, because a collection is where you can see both kinds of edge in one place: most of these consumers declared it in a requirements.yml, and one of them is in the list only because a playbook calls one of its modules by fully qualified name.

There is even a small, on-theme detail in how the detection works. The cheap pre-filter that decides whether a YAML file is worth parsing as a playbook used to key off the presence of roles: or collections: or include tokens, which meant a thoroughly modern playbook that used nothing but fully qualified module calls, no collections: block at all, would have been skipped before it was ever examined. The best-written playbook was the one that hid best. The detection now keys off hosts:, the actual marker of a play, so the modern repositories that do everything right are exactly the ones that no longer slip through.

What Riftmap does not claim

The honest limits are part of the product, so here they are plainly.

It does not trace variables, and that is on purpose. "Who consumes this variable" means modelling more than twenty precedence levels with per-repository runtime semantics, and the result would be a false-positive machine that quietly undermined every edge you actually trust. This is the inverted contract from earlier, and it is the boundary of what reading source can honestly tell you. Riftmap maps the artifact graph and is straight about the fact that the variable contract sits outside it, because the alternative is pretending to an answer nobody can derive from source without lying about it.

It does not resolve computed include_role names, because name: "{{ something }}" is unknowable until the run. It does not parse import_playbook references, which are intra-repository file paths rather than cross-repository dependencies. It does not, today, read execution-environment definitions or follow requirements.yml include: chains, both of which are on the roadmap rather than in the product. And it recognises your collections by your namespaces, so a public collection you merely consume shows up as an external dependency by design, not as a repository in your graph.

None of those gaps is hidden behind a confident interface. The point of a blast-radius tool is to be trusted on a Friday afternoon, and you do not earn that by overclaiming.

Distribution and blast radius are different questions

Step back, and the shape of it is clear. The very things that make Ansible feel light are the things that make its blast radius invisible. No lock file, so no record of what ran. No compile step, so no parse-time failure when a contract breaks. Variables resolved at runtime from wherever the consumer happened to set them. A role pulled from a repository nobody pinned. Ansible will cheerfully run a playbook it has never seen, against a host it has never met, resolving a role nobody locked and reading a variable nobody declared, and it will do it well. That flexibility is the entire point of the tool.

It is also why "what breaks if I change this role" has no answer in the box. The box was designed not to keep that answer.

Galaxy and Automation Hub tell you where a role came from and how often it was pulled. That is distribution, and it is a real and useful thing to know. It is a different question from what breaks when you change it. Distribution is about the artifact. Blast radius is about the relationships between repositories, which is the one place the artifact cannot see and the registry was never asked to look. You find every consumer by reading those relationships across the whole organisation and resolving them into a graph. Parsed, not inferred.

Your hardening fix is still sitting there, untagged. Now you can see who gets it, who pinned you and who did not, and which playbooks two hops away you were about to surprise. Tag it on purpose.

This post is part of the Find Every Consumer series, which works through the same question across Terraform modules, Docker base images, GitHub Actions, Helm charts, Go modules, GitLab CI templates, npm packages, and Python packages, one ecosystem at a time.

Overmind shows you the blast radius in your running cloud. It can't show you the repos that were building on what you changed.

Daniel Westgaard — Fri, 19 Jun 2026 00:00:00 GMT

Overmind reads your live AWS, GCP and Kubernetes state to tell you whether a Terraform apply is safe. Riftmap parses source to tell you which other repositories consume what you are changing. Both call it "blast radius". They are not the same radius.

The line that anchors Overmind's homepage is a good one. The Terraform plan shows what is in the plan, it says, but "the real impact lives in the running infrastructure". It is the kind of sentence I wish more infrastructure tools were honest enough to write. A terraform plan shows you the diff. It does not show you what that diff does once it lands in an account full of resources that depend on each other in ways the plan never spells out. Overmind built a real product on closing exactly that gap, and I have spent the last few days in their docs, their CLI, and their own writing about it, because when a tool reaches for the words your product is built on, the responsible thing is to understand it properly before you say anything about it.

Here is where I landed. "Terraform blast radius" is not one question. It is at least three, and they are answered by three different kinds of tool that are easy to mistake for one another. Overmind answers one of them, and answers it well. It is not the one a platform team in a 50-to-300-repo polyrepo org runs into most often, and it is not the one Riftmap is built for. The two tools barely overlap once the three questions are clear. So this post is mostly about drawing that line precisely, and being fair to Overmind while I do it. It is the same exercise I ran recently with GitLab Orbit, on a different axis.

What Overmind actually does

I want to be generous here, because Overmind earns it, and because what it is good at and what Riftmap is for sit on different axes.

Overmind plugs into the Terraform workflow at plan time. You run overmind terraform plan locally, or you wire overmind changes submit-plan into CI so it fires on every pull request. From there it does the thing most tools with "blast radius" in the name do not: it reaches into your running cloud. Using read-only access to your AWS, GCP or Kubernetes, it queries the live account through the provider APIs, builds a dependency map from the resources that actually exist, and works out which of them your plan could disturb. The depth is real, with over 120 AWS resource types and all of Kubernetes supported. Crucially, that map includes resources Terraform does not manage at all. Something created by hand in the console, or by CloudFormation, or by another tool entirely, still shows up, because the map comes from the cloud and not from your state file. On top of it Overmind posts a machine-generated list of risks straight into the PR, and overmind terraform apply lets it snapshot before and after a deploy so you can confirm nothing reacted in a way you did not expect. There is also an LLM-driven investigator, overmind explore, for poking at infrastructure interactively. And to its credit, the credentials never leave your environment; the CLI talks to the cloud, not the other way around.

The example Overmind leads with on its own site is the right kind of example, so I will describe it rather than invent a worse one. A change adds a memory limit to a Kubernetes deployment, and it looks safe, because the pods normally sit comfortably under the new ceiling. The limit only bites during a traffic spike, when the JVM heap expands for garbage collection, the pods cross the ceiling, get OOMKilled, and the failures cascade as the load balancer keeps routing traffic to pods that are themselves restarting. That is a genuinely hard thing to catch in review. It is invisible in the diff, invisible in the plan, and it depends on how the system behaves under load in production. This is Overmind's home turf, and on it Overmind is doing something neither a config visualiser nor a source parser can do. If the question in front of you is "is this apply safe against my live account", Overmind is a real answer.

So let me be precise about the shape of what Overmind sees. It reasons about cloud resources, in the account a plan targets, at the moment that plan exists, including drift and live runtime relationships. Hold that shape in mind, because the line falls exactly along its edges.

"Terraform blast radius" is three questions wearing one phrase

The reason two engineers can both say "we use a Terraform blast radius tool" and mean completely different things is that the phrase has quietly absorbed three separate questions. They live at different layers. They need different machinery. And most arguments about "the blast radius tool" are really two people standing at different layers talking past each other.

One: the resource graph inside a single config

Ask "what is the dependency graph of this Terraform configuration, and in what order will things change", and you want the in-config graph. This is the oldest sense of the term, and it is the one the open-source tool literally named Blast Radius built: parse the HCL in a working directory, render the resource DAG with Graphviz, let you see what depends on what before you apply. Inframap, Rover and Terraform Visual live here too. It is good for understanding and documenting one configuration, and it is bounded to one configuration. It tells you nothing about the running cloud and nothing about other repositories. It is the resource ordering inside the directory in front of you, and no more.

Two: the live-cloud graph at apply time

Ask "given this plan, what in my running infrastructure could be affected, and is that safe", and you want the live-cloud graph. This is Overmind. The graph is not derived from the config, it is discovered from the cloud, which is precisely why it can include unmanaged resources and runtime relationships the config never mentions. It is bounded to one account's live state, and to the moment a plan exists. Overmind itself drew the first half of this line years ago, when it argued that blast radius is more than another plan-visualisation tool, and it was right to. The live-cloud graph is a genuine step beyond the in-config graph.

Three: the cross-repo graph across the whole org

Ask "which other repositories across my organisation consume the thing I am about to change, and at which version", and you want the cross-repo artifact graph. This is Riftmap. Its nodes are the things repositories share: a Terraform module, a base image, a Helm chart, a reusable CI template. Its edges are the references that bind them across repos: a Terraform source block, a terraform_remote_state lookup, a Dockerfile FROM line, a Helm chart dependencies entry, a GitLab CI include:project. It is built by parsing source across every repository in a GitLab or GitHub org, and it is bounded by nothing except the org itself. It does not look at the cloud and it does not need a plan to exist. It answers the question before you make the change.

Overmind did a real service by separating question two from question one. The thing worth noticing is that question three is a different axis again, and nothing about answering question two gets you any closer to answering it.

Where the edge that bites actually lives

Picture the change that actually causes the bad afternoon. You take a shared Terraform module from v3 to v4 and rename a variable on the way. The module is fine. Your plan is fine. The thing that breaks is two repos away, in a service owned by a team that has never read your module's changelog, whose Terraform pins source = "git::https://gitlab.example.com/platform/modules.git//network?ref=v3" and will fail to plan the next time anyone touches it, or the moment Renovate bumps the ref for them.

Walk that through Overmind's machinery and you can see why it cannot be the tool that catches it. Overmind runs on a plan, in the repo where the plan exists. The plan that exists is yours, in the module repo or wherever you made the edit. The consuming repo has not planned anything. There is no live-cloud signal there yet, because nobody has applied the breaking change, and the failure you actually care about is the one that has not happened. Even if that team also runs Overmind, Overmind will not connect your module edit to their future plan, because it does not model the dependency that links them. That dependency was never a cloud resource. It was a ?ref=v3 in a manifest, in a repository Overmind had no reason to look at.

There is a fair caveat here, and I would rather state it than skate past it. Within a single shared account, Overmind queries the live cloud, so a plan in one repo can surface a resource that another repo also manages, because both touch the same account. In that narrow sense it can cross an ownership boundary at the resource level. But that is one account, at apply time, between resources that already exist. It is not the cross-repo source edge. It is not the consuming repos that have not applied anything yet. And it does not reach across accounts or across platforms. A module pinned at ?ref=v3 in a GitHub repo, while the module is published from a GitLab repo, is an edge no live-cloud tool can draw, because it does not exist in any cloud. It only ever existed in the manifest.

Then there is the entire artifact layer that has no cloud footprint at all. A shared Go module other services require. An internal npm package. A Python library half your repos import. A reusable GitLab CI template that thirty pipelines include. None of these is an AWS resource, so none of them is visible to a tool whose graph is built from cloud state. They are visible to a tool that parses the manifest edge, whether or not the artifact ever becomes a running resource. That is the difference between discovering the graph from the cloud and parsing it from the source. Parsed, not inferred. And parsed across everything, not only the things that happen to run in a cloud Overmind can read.

Two access models, two moments

The split shows up cleanly in two practical places, beyond the layer question itself.

The first is what each tool has to be trusted with. Overmind needs read-only access to your cloud, because that is where its graph comes from. The credentials stay in your environment, which is the right design, but the access still has to exist and be approved. Riftmap needs read-only access to your Git, one token, because that is where its graph comes from. These are different surfaces to reason about, and for a security-conscious or regulated team the question of which systems a tool touches is rarely an afterthought. Neither model is universally better. They are answers to different questions, and they go through different approvals.

The second is when each tool can answer. Overmind answers when a plan exists, which in practice means in CI, on a pull request, at apply time. Riftmap answers from a standing graph of the whole org that is already there before you write the change. You can ask it the moment you are considering a breaking change, before there is a branch, let alone a plan. An AI coding agent about to edit a shared module can ask it before it opens the pull request at all, which is the whole point of treating the graph as runtime infrastructure for agents. Apply time is a good moment to check whether a change is safe. It is a late moment to discover who you needed to warn.

It is worth being precise about determinism too, because it is easy to be unfair on this point. Overmind's dependency graph is not guessed, it is read from real cloud APIs, which is solid. The part that is a judgement rather than a guarantee is the risk list, which is generated automatically from patterns and analysis of the change and reads as advice. Riftmap's graph is parsed deterministically from manifests, and the consumer set it returns is an enumeration: these repositories reference this artifact at these versions, full stop, not a confidence score. Both tools are honest about which of their outputs is a fact and which is a judgement. They simply draw that line in different places, because they are doing different jobs. The deterministic case for parsing rather than inferring is something I have made at more length elsewhere, and it applies to the graph, not to Overmind's risk narrative, which was never trying to be deterministic.

They stack

I have come to think of Overmind less as a competitor than as the tool that owns the layer directly beneath the one Riftmap owns. The honest version of "when would I use each" is not a contest, it is a sequence.

You are about to bump a shared module. Riftmap answers the first question: which repositories consume it, who owns them, what versions they pin, so you know whose pipeline you are about to touch and who needs to be in the loop before you merge. For the repos that take the change and apply it, Overmind answers the second question: against their live account, is the resulting plan safe, and does anything in the running infrastructure react badly. One is the blast radius across your source. The other is the blast radius inside a cloud. They are not the same radius, and they do not fire at the same moment.

I should be equally clear about where Riftmap stops, because a comparison that only lists the other tool's limits is not worth reading. Riftmap will never catch the OOMKilled-under-load example from earlier. That failure lives in runtime behaviour, in how a JVM uses memory during a traffic spike, and Riftmap does not watch your runtime. It does not know your cloud. It does not see drift. If your worst changes are the ones that look safe in source and only misbehave once they are live, Overmind is reaching a layer Riftmap deliberately does not. The two tools are not redundant. Each is blind exactly where the other sees.

The useful coincidence is that both expose their graphs to machines. Overmind has a CLI and posts into the PR. Riftmap ships an HTTP API and an MCP server with every deployment. An agent reviewing an infrastructure change could call both: Riftmap for the repositories downstream of the artifact it is editing, Overmind for the runtime safety of the plan it produces. This was always the shape of it. The agent is a consumer of whichever graph answers its question, and on a real infrastructure change it has more than one question.

So which one is "Terraform blast radius"

Both are, and that is the whole point. A terraform plan tells you what you are touching. Overmind tells you what that touches in the account you are about to apply to, drift and runtime included. Riftmap tells you who else was building on it, across every repository and every platform, before the plan exists. Three questions, three tools, one overloaded phrase.

If your pain is "the apply looked safe and production fell over anyway", that is the live-cloud question, and Overmind is built for it. If your pain is "we changed a shared module and three teams found out when their pipelines went red", that is the cross-repo question, and no amount of live-cloud analysis will answer it, because the edge that broke was never in the cloud. It was a pinned source block in a repo nobody thought to check. Same two words. Different blast, different radius.

A few questions, answered directly

Does Overmind show cross-repo Terraform blast radius?

No, and the reason is structural rather than a missing feature. Overmind builds its dependency graph from your live cloud state at plan time, scoped to the account a Terraform plan targets. The cross-repo edge that breaks when you change a shared module is a source block pinned to a version in a different repository that has not run a plan, often on a different platform or in a different account entirely. That edge exists only in source, so a tool whose graph comes from the cloud cannot draw it. Overmind answers blast radius inside a running account. Cross-repo consumer questions need a graph parsed from source across the whole org.

What is the difference between Overmind and Riftmap?

They answer different questions about a Terraform change. Overmind reads your live AWS, GCP or Kubernetes state at plan time and tells you what in the running infrastructure a plan could affect, including drift and resources Terraform does not manage, plus a machine-generated risk assessment in the PR. Riftmap parses source across your entire GitLab or GitHub org and tells you which other repositories consume the module, image, chart or CI template you are changing, and at which versions, before a plan exists. Live-cloud and apply-time versus source-derived and org-wide. They are complementary, not substitutes.

Does `terraform plan` show blast radius?

Not in any of the three senses people usually mean. terraform plan shows the diff between your configuration and your state: the resources this configuration will add, change or destroy. It does not render the resource ordering as a graph (the in-config tools do that), it does not show what in your running cloud could be affected including unmanaged resources (Overmind does that), and it does not show which other repositories consume what you are changing (Riftmap does that). The plan is the input to blast-radius analysis, not the analysis.

Can Overmind and Riftmap be used together?

Yes, and on a real infrastructure change they answer adjacent questions in sequence. Before you ship a breaking change to a shared artifact, Riftmap tells you which repositories and teams consume it, so you know whom to coordinate with and what to gate the merge on. For the repos that apply the change, Overmind tells you whether the resulting plan is safe against their live account. One maps the blast radius across your source. The other maps it inside your cloud. Both expose their graphs over an API or MCP, so an AI coding agent can call either or both during a review.

You deprecated the internal library. The repos still using it never saw the warning.

Daniel Westgaard — Thu, 18 Jun 2026 00:00:00 GMT

Every deprecation guide tells you how to signal that a module is going away. None of them tell you who to signal. Deprecating an internal library is a consumer-census problem, and the census is the part nobody hands you.

Someone on your team did everything the guides tell you to do.

They had built an internal library years ago. Call it @acme/auth, a shared package half the org imports for token handling. It had outlived its design, a cleaner replacement existed, and it was time to pull it. So they did it by the book. They added the @deprecated tag to the exported functions. They cut a major version so the removal would land on a semver boundary nobody could miss. They wrote a migration guide with before-and-after snippets. They posted in the engineering announcements channel, twice, a month apart. They set a sunset date a full quarter out. And on the date, they removed it and shipped the major.

For a fortnight, nothing. Then a payments service fell over in staging on a Tuesday afternoon, and the on-call engineer spent two hours tracing a build failure back to a package that, as far as anyone in the channel knew, no longer had any consumers. The service had pinned the old major eighteen months earlier. It had never seen the editor warning, because nobody was actively developing it. It had never read the announcement, because the team that owned it had reorganised and the new owners were not in the channel when the message went out. It had simply kept building against the version it was locked to, quietly, until the version went away.

The part I keep coming back to is that this deprecation was not done badly. It was done well. Every step in the standard playbook was executed, and the playbook still let a consumer break. Because the playbook is about one half of the problem, and the half that actually bit was the other one.

The deprecation playbook is all signal

I want to be fair to the playbook, because most of it is correct and hard-won, and the people who wrote it down were solving a real problem.

The advice converges across ecosystems. In JavaScript and TypeScript you add a @deprecated JSDoc tag, you reach for console.warn in the function body, and you remove the symbol only on a major version because that is the boundary semver tells consumers to expect breakage on. In Python you raise a DeprecationWarning, or you wrap the thing in one of the deprecation decorator libraries that write the boilerplate for you. In Go you put a // Deprecated: line in the doc comment. Across all of them you write a migration guide, you announce it where your consumers can see it, and you give people a sunset window rather than yanking the thing from under them. The npm docs put the underlying ethic plainly: deprecate rather than unpublish, because unpublishing pulls the package with no warning to anyone who relied on it.

This is genuinely good practice. Do all of it. None of what follows is an argument against signalling a deprecation properly.

But read back over that list and notice what every item has in common. The @deprecated tag annotates a symbol your consumers import. The migration guide is written for your consumers. The announcement is addressed to your consumers. The sunset date is a promise to your consumers. Every single step takes the set of consumers as an input it already has. The playbook starts at the point where you know who they are.

Every step assumes you already have the list

Here is the quiet conflation. We talk about deprecation as one task, and it is two.

One task is signalling: telling the consumers of a thing that it is going away, on a timeline, with a path off it. The other is the census: knowing who the consumers actually are. The playbook is entirely about the first and silently assumes the second is already done. And for an internal library spread across a polyrepo org, the second is the hard one. It is the one that decides whether the deprecation is safe, and it is the one nothing in the playbook does for you.

You cannot signal a consumer you cannot name. You cannot set a credible sunset date without knowing how many repos have to move and who owns them. You cannot estimate the migration effort, or stage it sensibly, or tell your own management how risky the removal is, until you have enumerated every repo that imports the thing and the version each one is pinned to. The annotation, the guide, the announcement: all of it is downstream of a list you were assumed to already hold. In a single app you do hold it, because the consumers are in the same repo and the compiler finds them. Across an organisation you do not, because the consumers are in other people's repos and nothing walks all of them for you.

The signal is conditional, and often silent

It is tempting to think the signal itself solves the census. Surely if you mark the thing deprecated, the consumers find out. They do not, and it is worth being precise about why, because the failure is mechanical, not careless.

Take the editor warning first. A @deprecated JSDoc tag only surfaces for a developer whose tooling is configured to flag it, through a rule like eslint-plugin-import's no-deprecated, and only when someone actually opens that repo and lints or rebuilds it. A service that is locked to the old version, building green in CI, with nobody in their editor that quarter, gets no signal at all. The annotation is sitting in a version of the package that repo is not even pulling.

Python is sharper still, and the default trips almost everyone. Since Python 3.2, DeprecationWarning is ignored by default for every module except __main__. PEP 565 re-enabled it in __main__ in 3.7, but a deprecated function imported from a library runs in the importing module, not in __main__, so the warning lands in a filter that drops it on the floor. A service can import your deprecated function, run it in production every day, and never emit a visible warning, unless it happens to run its test suite with warnings surfaced or someone has set PYTHONWARNINGS. The signal fires into silence.

npm has the same gap from the other direction. The deprecation message shows up as npm WARN deprecated during install and resolution. A repo with a committed lockfile that is not reinstalling does not resolve anything, so it does not see the warning. The message reaches new installs, not the repos that locked your old version a year ago and have not run a clean install since. For an internal package wired in through a workspace protocol or a private registry, the registry-level deprecation may not reach the consumer at all.

And then the announcement, which is the one humans trust most and should trust least. It reaches the people who read the channel and already understand that they are affected. The team that pinned your library eighteen months ago and forgot is, by definition, the team that does not know it needs to be reading. The announcement is a broadcast; the consumers you are most worried about are the ones not tuned in.

So even in the best case, where a consumer is actively developed and tested, the signal is conditional on tooling plus a rebuild. In the common case, where a consumer pinned a version and went quiet, the signal reaches no one. And the quiet consumers are exactly the ones that break, because quiet is what "we pinned it and stopped thinking about it" looks like from the outside.

So you go looking for the list

Once it is clear the signal will not assemble the census for you, you go and try to build it by hand. Every route you reach for gets you partway and stops at the same wall.

The internal package registry feels like the obvious source. If you run a private registry that records pulls per consumer, maybe you can read the list off download stats. In practice that data is rarely surfaced cleanly, CI caches inflate and distort the counts, and any repo that vendored the code, pinned a git URL, or wired the dependency through a workspace never shows up as a registry pull at all. Download numbers tell you something about traffic. They do not give you a clean set of repositories with owners.

The wiki page is worse, because it looks authoritative and is usually wrong. Someone wrote "consumers: X, Y, Z" once, eighteen months and one reorg ago, and a fourth team added itself the week after and never edited the page. This is the same decay that makes platform teams quietly abandon their service catalogues. A hand-maintained list of consumers is only ever as accurate as the last person who remembered to update it, and "remember to update the consumers page" is precisely the discipline that does not survive contact with a busy quarter.

Code search is closer, and for one ecosystem across a handful of repos, grep genuinely works. Across an org it becomes a string of false starts. The import can be aliased, re-exported from a barrel file, pulled in transitively through another internal package that depends on yours, or referenced by a version range rather than a literal you can match on. Walking that down by hand, repo by repo, is the work the Find Every Consumer series exists to document, one ecosystem at a time, and the recurring lesson of that series is that grep is where you start and not where you finish.

GitHub's dependency graph looks like it should just answer this. It has a Dependents view built for exactly this question. Except GitHub only computes dependents for public repositories. Your internal library lives in a private org, which is the one case the feature does not cover.

And the reverse-dependency tools that do exist are scoped to the wrong thing. apt-cache rdepends and repoquery --whatrequires answer reverse-dependency questions for the packages installed on one machine, not for the repos in your org. jdeprscan and the eslint deprecation rules scan a single repo that already depends and recompiles, to find uses of deprecated APIs inside it. They are good tools. None of them answers "which repositories across my organisation consume this library," because that question is not a fact about any one repo. It is a fact about the relationship between your library and every other repo, and not one of these tools is looking at all the repos at once.

Even automated migration needs the list first

The sophisticated end of this is real and deserves credit before I draw the line. There is a whole tier of tooling built to perform the migration across many repositories once you know where it has to land. Renovate and Dependabot open the version bump in each repo they are configured on. OpenRewrite applies structured, type-aware code transformations across a codebase. Allegro combined Dependabot and OpenRewrite into an in-house system to run migrations across more than two thousand microservices, precisely because doing it by hand when a company-wide library makes a breaking change is brutal and error-prone.

That is impressive engineering, and it is also the mechanical-edit layer, not the census. Renovate and Dependabot keep dependencies current and tell you nothing about who consumes what; they give you the bump, not the blast radius. Every one of these systems operates on the repos it is pointed at, and so it presupposes the list. The repos it was never pointed at, the ones that pinned the old version and dropped out of the automation, are the same quiet consumers from the scene at the top of this post. Automating the edit makes a known migration faster. It does nothing for the consumer you did not know you had, because that consumer was never in the set the automation was handed.

The list is a graph query, not a search

Strip the problem back and the thing you actually need before you deprecate anything is small and specific. Every repository that declares a dependency on this library, directly or transitively. The version each one pins, so you can separate the repos already off it from the ones stranded on the old major. The team that owns each repo, so you know who to route the migration to. And the order, so you migrate the internal package that re-exports your library before the leaf services that pull it in through that package.

That is a query against a graph of dependency edges, and the only honest way to build the graph is to parse it. Read the dependencies in every package.json, the require in every go.mod, the import in every pyproject.toml and requirements file, the source in every Terraform module block, the chart references in every Helm values file, the include in every GitLab CI config. Resolve the version each one pins. Normalise the aliases, the re-exports, and the workspace protocols back to the package they point at. Connect the edges. Parsed, not inferred. Not guessed from names that look similar, not reconstructed from a wiki someone edited last year, not pieced together from a Slack thread. Read from the manifests that already declare the dependency, because those files are the source of truth and they are also exactly where the migration is going to land.

The ecosystem changes the syntax, not the shape of the problem. The mechanics of doing this properly differ enough per ecosystem that they each deserve their own walkthrough, which is why the Find Every Consumer series takes them one at a time: internal npm packages, internal Python packages, Go modules, Terraform modules, and Helm charts each fight back in their own way. But the destination is the same in every case. A set of repositories, with versions and owners, derived from source.

The debt you keep because you cannot see the list

Here is the part that makes this more than an incident story, and it is the reason the census matters even when nothing is actively breaking.

When you cannot enumerate consumers cheaply, the rational response is to never remove anything. Think about what the alternative asks of you. To delete the old auth library, you have to be willing to say "nothing depends on this any more," and if you are wrong, a payments service falls over and it is your name on the change. "I am fairly sure nothing uses this" is not a sentence anyone wants to be holding when the pager goes off. So the safe move, the locally rational move, is to leave it. Leave the deprecated library in place. Leave the forked Terraform module nobody has touched in two years. Leave the old endpoint running just in case. Mark it deprecated, maybe, and never actually pull it.

This is how internal platforms accrete years of undead code. Not because nobody wants to clean it up. Because removal is unprovable-safe, and the cost of being wrong is paid in production at an inconvenient hour. The module stays, the maintenance burden stays, the mental overhead of "is this still load-bearing" stays, and the next engineer inherits all of it plus the same fear that kept the last one from acting.

A cheap, trustworthy consumer census changes the calculus completely. When you can answer "what depends on this" in one query, with versions and owners, removal stops being a gamble and becomes a decision. You see the four repos still on the old major, you route the migration, you watch the number go to zero, and then you delete with confidence instead of hope. The census is not only the thing you reach for in an incident. It is the thing that lets a codebase shrink at all. Without it, the only safe direction is accretion.

Two halves of deprecation

So, stripped down. Deprecation is two jobs wearing one word, and the departure of that payments service showed which one the playbook forgot.

One job is signalling: tell your consumers the thing is going away, on a timeline, with a path off it. The playbook is all about this half, and it is good at it. The @deprecated tags, the semver majors, the migration guides, the announcements. Do every bit of it.

The other job is the census: know who your consumers are in the first place. Nothing in the playbook does this half, and every part of the playbook silently assumes it is already done. The signal turns out to be conditional and frequently silent, the obvious sources of the list are stale or scoped to the wrong thing, and even the automation that performs the migration has to be handed the list before it can run.

The signal tells your consumers. The census tells you who they are. Those are different artefacts, built from different sources, and on the morning a forgotten service falls over, the second one is the only one that would have prevented it. You can deprecate a library in an afternoon. Knowing who was still standing on it is the part you never had.

This is the query Riftmap is built to answer. Point it at your GitHub or GitLab organisation with one read-only token and it parses the dependency edges across every repo. npm, Python, Go, Terraform, Helm, Docker, GitHub Actions, GitLab CI, and the rest. "What depends on this library, at which version, owned by whom" becomes one query instead of one archaeology dig. Before you mark anything deprecated, you get the census the playbook assumed you already had: every repo still on it, the version each one pins, the team to route the migration to. The annotation tells your consumers. Riftmap tells you who they are. And once the graph exists, the census can meet the change where it happens: a forty-line CI gate posts the consumer count on every merge request against the library, so the next breaking change to it gets the review its blast radius deserves.

Riftmap maps cross-repo dependencies across your entire GitLab or GitHub organisation — Terraform, Docker, CI templates, Helm, npm, Go, Python, and more. One read-only token. No YAML to maintain. The free tier is here.

Appendix: the argument in short

Claim. Deprecating an internal library is treated as a single task and is actually two. Signalling (telling consumers it is going away) is what every guide documents and what the tooling is good at. The consumer census (knowing who the consumers are across your repos) is the part nothing in the playbook does, and it is the part that decides whether the removal is safe. The signal is conditional and often silent, the manual sources of the list are stale or wrong-scoped, and even automated migration presupposes the list. The census can only be built by parsing the dependency edges your manifests already declare across every repo.

Consumer census. The set of repositories that depend on a given library, with the version each one pins and the team that owns it, derived from the manifests across an organisation rather than from a registry, a wiki, or an announcement.

FAQ.

Will a deprecation warning reach consumers who pinned an old version? Often not. An npm deprecation surfaces as npm WARN deprecated during install and resolution, so a repo with a committed lockfile that is not reinstalling never sees it. Python's DeprecationWarning is ignored by default for every module except __main__, so a service that imports a deprecated function and runs it in production emits nothing visible unless it runs tests with warnings surfaced. A JSDoc @deprecated tag only flags for a developer whose linter is configured for it and who rebuilds the repo. The consumers you most need to reach are the quiet, pinned ones, and they are the least likely to see any signal.
How do I find every repo that depends on an internal library before deprecating it? Not from the warning, which is conditional and silent for inactive consumers. Not from a hand-maintained consumers page, which goes stale the next time anyone adds a dependency. Not from GitHub's Dependents view, which only computes dependents for public repositories. You parse the dependency edges your manifests declare (package.json, go.mod, pyproject.toml, Terraform source, Helm references, CI includes) across every repo, and query the resulting graph.
How do I find consumers of a private package across repositories? Reverse-dependency tools like apt-cache rdepends answer for one machine, and GitHub's dependency graph only covers public repos. For a private org, the consumer set has to be parsed from the manifests in each repo and assembled into a cross-repo reverse-dependency graph.
What is the first step in safely deprecating a shared internal library? The consumer census, before any annotation or announcement. You cannot set a credible sunset date, estimate the migration effort, or stage the rollout until you know which repos consume the library and at which version.

Related reading.

How to find every consumer of your internal npm package — the per-ecosystem mechanics for the most common version of this problem.
How to find every consumer of your internal Python package — the same census, for Python's packaging and import surface.
You changed the shared CI template. Half the org got it instantly. The other half will never see it — the CI limit case of this post, where the signalling layer is gone entirely: no @deprecated, no DeprecationWarning, no semver boundary, nothing between your merge and someone else's red pipeline.
A CVE just hit your base image. Your scanner won't tell you which repos to fix — the reactive twin of this post: same cross-repo-versus-single-artifact gap, forced by an external shock instead of a planned removal.
Your senior engineer just left. Your bus factor was measuring the wrong thing — what happens when the person who held the consumer map in their head walks out.
The catalog maintenance trap — why the hand-maintained consumers page is wrong by the time you read it.
Monorepo vs polyrepo: the debate is measuring the wrong thing — why "what depends on this" being queryable matters more than where the code lives.
What is cross-repo dependency mapping? — the glossary definition of the parsed graph this post keeps pointing at.

Your senior engineer just left. Your bus factor was measuring the wrong thing.

Daniel Westgaard — Wed, 17 Jun 2026 00:00:00 GMT

It is three weeks after the goodbye lunch. The staff engineer who had owned half your platform for six years is gone, the Slack handle greyed out, the laptop returned. And now there is a change that has to happen. Marketing's base image needs bumping for a CVE, or the old auth module is finally being pulled, or a shared Terraform module everyone forked from needs a breaking edit. Routine work. The kind they would have scoped in an afternoon without opening more than two tabs.

You open the repo. The code is all there. It is readable. Nothing is encrypted, obfuscated, or missing, and you can follow every function in it. And you still cannot answer the one question that has to come before you touch anything. If I change this, what else breaks.

The part that took me a while to see clearly is that this sounds like a paradox and is not one. You did not lose their understanding of the code. The code stayed. Git kept all of it. What left was something that was never in the repo to begin with: the map of how the repos depend on each other. Which services build on that base image. Which repos still import the auth module, at which version. Which of the forty Terraform consumers will actually break on the edit and which only look like they might. They held that map in their head, assembled over six years of being the person who got paged, and it walked out the door with them.

We have a number that is supposed to warn us about exactly this. It is called the bus factor, and on paper their leaving should have tripped it. The uncomfortable thing is that for most teams, the bus factor was quietly measuring something other than the thing that just hurt them.

The bus factor you were measuring was an authorship number

I want to be fair to the bus factor, because the concept is good and the people who formalised it did careful work. The informal definition is clean: the minimum number of people who have to disappear before a project stalls. A bus factor of one is the canonical danger. And there is a real research literature behind making it computable, going back to the truck-factor work on version-control history and continuing into recent papers that model a project as a bipartite graph of contributors and the files or tasks they own. The commercial calculators do the same thing in a friendlier wrapper. Point them at a repository, read the commit history, and see which files only one person has meaningfully touched.

Notice the input in every one of those. It is the commit log. Bus factor, as it is actually computed, is a function of authorship. Who wrote this file, who has touched it since, how concentrated that history is. That is a genuine signal, and it answers a genuine question. If this person leaves, which code has no second author.

But "which code has no second author" is not the question you are stuck on three weeks after the departure. You are not missing the authorship of the auth module. You can read it. You are missing what depends on it across the other eighty repos, and that fact was never written into any commit. Authorship concentration and dependency knowledge are two different quantities, and the standard bus factor only measures the first. The senior could have pair-programmed every line they ever wrote and pushed the authorship bus factor to a comfortable three, and you would still be sitting here unable to bump the base image, because the thing that broke was never about who typed the code.

So it is worth naming the quantity the standard bus factor misses, because it is the one that actually decides how bad a departure turns out to be. Owen Zanzal nudged me toward seeing it this way, and this is the dedicated follow-up I promised in the senior-engineer piece.

A dependency bus factor is the number of people who have to leave before your organisation loses the ability to answer "what depends on this" across its repos. It is not about who wrote any given service. It is about who can still tell you, once they are gone, which repos consume a shared module, at which version, and in what order those repos break when it changes. Where the classic bus factor is computed from commit authorship inside repos, the dependency bus factor lives in the edges between them: the Dockerfile FROM lines, the go.mod requires, the Helm value references, the Terraform source blocks, the GitLab CI includes. A team can have a perfectly healthy authorship bus factor and a dependency bus factor of one, and the second number stays invisible right up until the one person who held the cross-repo map in their head hands in their notice.

What actually walked out the door

There is a whole genre of good writing about inheriting an unfamiliar codebase, and I do not want to wave it away, because the advice in it is sound. Start from the edges. Find an entry point and trace it. Run the thing under a debugger and watch what executes. Make small, safe refactors as you go to anchor what you have learned. Talk to whoever is still around. If your problem is "I have been handed one large application and I do not understand its internal logic," that advice will get you there.

The problem three weeks after a senior leaves is a different shape, and reading harder does not solve it. The auth module is two hundred lines and I understood it the first afternoon. What I cannot get by reading it is the set of repos elsewhere in the org that require it, because that information is not in the module. It is distributed across every other repo's manifests, and no single repo I open will reveal it. The base image is worse, because the dependency runs through indirection the file does not spell out. A leaf service builds FROM acme/runtime-base, which is itself built FROM debian, so the repo I am editing does not even mention the thing I am actually trying to reason about. The senior knew the base was two hops up. The Dockerfile does not say so.

This is why the dependency bus factor is its own quantity and not just "bus factor for teams that documented badly." The knowledge is not absent because someone was lazy about comments. It is absent from any one place by construction, because a cross-repo dependency is a fact about the relationship between two repos, and a relationship does not live inside either endpoint. The senior was, in effect, a human index over those relationships. The index is what you lost, and an index is exactly the thing reading one repo at a time cannot rebuild.

Why the handover doc was never going to hold it

The standard answer to all of this is the knowledge transfer plan. Get it out of their head before they go. Shadowing, a handover document, a wiki page, a fortnight of overlap if the timing is kind. And for a lot of what a senior carries, that genuinely works. The "why did we ever do it this way," the war stories, the half-broken vendor integration nobody should touch on a Friday afternoon. Tacit, judgement-shaped knowledge, the kind you can only get by asking. Write it down. It is worth every hour.

But the people who run knowledge transfer for a living are blunt about where it fails. It runs on memory and goodwill, and both are unreliable narrators. The person leaving leaves out half of what they carry, not from carelessness but because the deepest knowledge is the most internalised, the kind they have stopped noticing they have. And the dependency map is the worst possible candidate for hand-capture, for a reason that has nothing to do with effort. It is large, it is mechanical, and it goes stale on the next merge. The afternoon someone writes "services X, Y and Z build on this base," a fourth team adds itself, and the page is now wrong and nobody knows it is wrong. This is the same failure that makes platform teams quietly abandon their service catalogues. A hand-maintained map of what depends on what is only ever as accurate as the last person who remembered to update it, and "remember to update it" is precisely the discipline that does not survive the one person who cared about it leaving.

So the handover captures the things only a human can give you and quietly drops the one thing you most needed to keep, because that thing is too big and too volatile to write down by hand. You come out of it with the stories and without the map.

The one piece of what they knew that you never had to transfer

Here is the move, and it is almost annoying once you see it. The dependency map is the single part of what the senior knew that you did not need them to transfer at all. Because unlike the war stories and the judgement calls, it is not tacit. It is written down already, just not in prose. It is in the manifests. Every FROM line, every require, every chart reference, every module source is a dependency edge the senior had memorised and the repo had already declared. You do not have to get it out of anyone's head. You can read it straight off the files, deterministically, the same answer every time you ask. Parsed, not inferred.

That is the real split between the two kinds of knowledge a departure takes. The semantic stuff, the intent and the patterns and the reasons, is genuinely lost when the person goes, and a handover is your one shot at it. The structural stuff, the graph of what depends on what, was never really theirs to take. It only felt lost because the only working copy was the one in their head, and nobody had built the other one. I made the longer version of this argument when Meta published their tribal-knowledge writeup: the structural layer is the durable one precisely because parsers are deterministic and re-run on every push, while the human-written layer decays and needs constant tending. A senior leaving is that same argument arriving through a more painful door. You do not transfer the map. You parse it. The closest sibling to this piece, most of what a departing senior knew was in the repos all along, works the same split from the angle of the resignation itself.

Even if nobody is leaving

You do not have to wait for a resignation for this to bite, and the proactive version is where the number earns its name. If you want to lower your dependency bus factor on purpose, the first problem is that you cannot lower a number you cannot see, and you cannot see it from the commit log. The repos that should worry you are not the ones with the messiest history. They are the ones where a single person is the only owner and a lot of other repos depend on what that repo produces. The danger is the product of two things. Sole ownership, which the commit history can show you. And cross-repo fan-in, which it cannot. A repo one person owns that nothing else depends on is fine. A repo one person owns that forty other repos build on is a dependency bus factor of one with a blast radius attached, and it looks identical to the safe one if all you are reading is authorship.

That product, sole ownership crossed with how hard the rest of the org leans on the thing, is the actual risk surface, and you can only compute it if you have the dependency graph to multiply the ownership against. Find those repos while the person who owns them is still in the building, and a future departure becomes a routine offboarding instead of a three-week archaeology dig.

Two bus factors

So, stripped down. There are two numbers here, and the departure showed you which one you had been watching.

The authorship bus factor is real and worth tracking. It is computed from your commit history, it tells you which code has no second author, and it is the one every existing tool measures. Keep an eye on it.

The dependency bus factor is the one that decided how bad last month actually was. It is not in the commit history. It lives in the edges between your repos, the same FROM lines and requires and chart references your manifests already declare, and it can only be computed from those. It was the part of what the senior knew that you could have kept without asking them to write a single word down, and the reason it felt catastrophic to lose is that nobody had built the copy that does not live inside a person.

When the senior left, the code stayed and the map walked out with them. The code was never the part you could not replace. The map was. And the map was the one thing you never needed a goodbye lunch to hand over, because it was sitting in your repositories the whole time, waiting to be read.

This is the query Riftmap exists to answer. Point it at your GitHub or GitLab organisation with one read-only token and it parses the cross-repo edges across every repo. Terraform, Docker, Helm, Kubernetes, GitHub Actions, GitLab CI, Ansible, Go modules, npm. "What depends on this module, at which version, owned by whom" becomes one query instead of one person. And because it crosses ownership against cross-repo fan-in, it will surface the single-maintainer, high-blast-radius repos, your dependency bus factor of one, while the person who owns them is still on the team. The graph is the copy of the map that does not resign.

Appendix: the argument in short

Claim. The bus factor every tool measures is computed from commit authorship, so it answers "which code has no second author." The thing that actually breaks when a senior engineer leaves is different: the cross-repo dependency map they held in their head, which is in no commit and inside no single repo. Call that the dependency bus factor. It is the one part of what they knew that you can keep without a handover, because it is already declared in your manifests and can be parsed deterministically.

Dependency bus factor. The number of people who must leave before your organisation can no longer answer "what depends on this" across its repos. Computed from the dependency edges between repos (Dockerfile FROM lines, go.mod requires, Helm value references, Terraform source blocks, CI includes), not from commit authorship inside them.

FAQ.

Does the bus factor measure dependency knowledge? No. As computed in practice it measures authorship concentration from commit history. It tells you which code has a single author, not which repos across the org depend on that code.
How do you find what depends on what after the engineer who knew leaves? Not by reading the code, because the edges live between repos and not inside any one of them, and not reliably from a handover doc, because that goes stale on the next merge. You parse the dependency edges your manifests already declare and query the resulting graph.
Can a knowledge transfer plan capture cross-repo dependencies? Only by hand, and only as a snapshot. A hand-written "what depends on what" map is wrong the next time anyone adds a consumer, the same way service catalogues go stale.

Related reading.

Most of what a departing senior knew was in the repos all along — the sibling to this piece: tribal knowledge is two things wearing one name, and the structural half was declared in your manifests the whole time.
Meta needed 50+ AI agents to map their tribal knowledge — the architectural version of this argument: the parsed dependency graph is the durable layer; the human-written layer decays.
Monorepo vs polyrepo: the debate is measuring the wrong thing — why "what depends on this" being queryable matters more than where the code lives.
The catalog maintenance trap — why hand-maintained maps of dependencies go stale and get abandoned.
A CVE just hit your base image. Your scanner won't tell you which repos to fix — the same cross-repo-versus-single-artifact gap, on the reactive side.
You deprecated the internal library. The repos still using it never saw the warning — the planned-removal sibling: the consumer set the departing senior held in their head is the same one a deprecation requires, just summoned by a different trigger.
What is cross-repo dependency mapping? — the glossary definition of the parsed graph this post keeps pointing at.

How to Find Every Consumer of Your Internal Python Package

Daniel Westgaard — Tue, 16 Jun 2026 00:00:00 GMT

You maintain an internal Python package on a private index. You need to change its API. Which repos across the org depend on it, and at which version? The public Python ecosystem has an answer to that question. The moment you move the package onto your own index, everything that knows the answer is looking somewhere your package never appears.

npm puts a Dependents tab on the registry page for every public package. PyPI has nothing of the sort. Open the project page for requests or flask and there is no reverse-dependency view, no list of what builds on top of it, no count. What answers the question for public packages is third-party and sits beside the index rather than inside it: Google's deps.dev and libraries.io, both of which crawl the public index and will show you who depends on a given package.

Now make the package yours. Rename it from confparse to yourco-config, set it to private, and publish it to AWS CodeArtifact or the GitLab PyPI registry instead of pypi.org. deps.dev and libraries.io go dark immediately, because they crawl the public index and your package is not on it. pip has nothing to offer either. pip show yourco-config lists a "Required-by" field, but it only reflects what is installed in the environment you happen to run it in, and pip has had an open request for a real reverse-dependency command for years. Dependabot and Renovate know implicitly who depends on what, because they are configured per repo, but they are updaters, not mappers, and only where they are switched on.

There is a second gap underneath the first, and it is worth sitting with. Even for a public package, the dependents that deps.dev and libraries.io can show you are mostly other published packages, because a published package is what an index crawler can see. The things consuming your internal library are overwhelmingly applications. Services, pipelines, DAG repos, batch jobs. None of those are published to any index, so they would not appear as dependents even if your package were public. So the answer exists for the packages that cannot hurt you, and is missing for the one that can. The shared client every service imports, the config package forty repos pull in, the feature library the whole ML platform builds on. The one whose breaking change is your problem is precisely the one with no consumer view at all. This post is about getting that view back, and about why Python makes it genuinely harder than the other ecosystems in this series.

The scenario

Your platform team, or your ML-platform team, publishes a package. Maybe it is yourco-clients, a generated client for your internal APIs that half the services import. Maybe it is yourco-observability, the structured-logging and trace-propagation library every service is supposed to use. Maybe it is yourco-config, a thin package that standardises settings loading so nobody hand-rolls it. Maybe it is yourco-features, a shared feature-store and data-access layer the whole ML org builds on.

It started as a way to stop copy-pasting. A few repos adopted it. Then more. And here is where Python diverges from every other post in this series, immediately, before we even get to the hard part. There is no single place a consumer declares the dependency. There is barely a single format.

One service declares it in requirements.txt:

yourco-clients==2.4.1
yourco-observability~=1.7

Another uses the modern standard, PEP 621 dependencies in pyproject.toml:

[project]
name = "checkout-service"
dependencies = [
    "yourco-clients>=2.4,<3.0",
    "yourco-observability~=1.7",
]

[project.optional-dependencies]
dev = ["yourco-testtools>=0.9"]

A third is on Poetry, which until recently used its own table with its own syntax. The caret is not a PEP 440 operator, the resolution semantics are Poetry's:

[tool.poetry.dependencies]
python = "^3.11"
yourco-clients = "^2.4.1"
yourco-observability = "~1.7"

A fourth predates all of that and declares its dependencies in setup.py, in arbitrary Python:

setup(
    name="reporting-service",
    install_requires=[
        "yourco-clients>=2.4,<3.0",
        "yourco-observability~=1.7",
    ],
)

A fifth never stood up a private index at all and pulls your code straight from git:

-e git+https://gitlab.yourco.com/platform/yourco-clients.git@v2.4.1#egg=yourco-clients

And because the package is private, every consumer that does use the index carries routing config that points at it, the way an .npmrc does for a scoped npm package. In Python that lives in pip.conf, or a .netrc, or a Poetry source, or a uv index table:

# pip.conf
[global]
index-url = https://pypi.org/simple
extra-index-url = https://gitlab.yourco.com/api/v4/projects/42/packages/pypi/simple

Twenty repos adopted the package, across four or five of these mechanisms. Then you stopped counting, because nothing in your toolchain counts for you. Now you need to change it. Drop a parameter, rename an export, cut a major. The question is the one that runs through every post in this series: which repos across the org depend on this package, at which version, and which of them break when I publish?

The change you ship without shipping it

Before the tooling, the part that makes this sharper than it first looks, and it is more acute in Python than in the npm version of this same argument.

A loose constraint is a standing instruction to adopt your next release. A consumer on yourco-clients>=2.4 is not pinned. They will take whatever the newest version is the next time their environment is resolved fresh. The PEP 440 compatible-release operator, ~=1.7, is the same thing inside a band: it means >=1.7, <2.0, so every 1.x you publish is a candidate. Poetry's ^2.4.1 resolves to >=2.4.1, <3.0.0, which is a subscription to every minor and patch you ship in the 2.x line.

Python makes this land more easily than npm does, for one structural reason. A very large number of Python repos have no committed lockfile. They have a loose requirements.txt that gets pip install-ed during a Docker build, on every build, against the live index. There is no poetry.lock or uv.lock holding the line. So the resolution is not a one-time event that someone reviews in a pull request. It happens every time the image is rebuilt, silently, on the consumer's schedule rather than yours. You did not roll out your 2.5.0. They did, the next time CI ran, and the first you hear of a regression is somebody else's red pipeline.

This is not a fringe worry, it is being actively argued about right now. uv, the fast-rising resolver, defaults to constraints with no upper bound, which means uv lock --upgrade will happily pull a breaking major across every transitive dependency, and the friction of that has pushed uv to add a --bounds option so uv add can produce a safer >=2.13.4,<3.0.0. The community has not settled on how tight constraints should be. While that argument runs, your consumers are scattered across every position on the spectrum, and you cannot see which.

The reverse case is just as bad in the other direction. When you do the honest thing and cut a genuine breaking change as a major, 2.x to 3.0.0, a <3.0 pin or a Poetry caret correctly refuses to follow. That is the right behaviour. It also leaves you with a long tail of repos stranded on the old major, indefinitely, with no list of who they are. You cannot deprecate 2.x because you cannot see who is still on it.

Either way the constraint is the mechanism, and the constraint is exactly what a quick search across your repos cannot evaluate. You need to know who consumes the package and how their constraint relates to what you are about to publish. Both halves of that live in files most audits never open, in formats most scripts do not all parse.

What existing tools give you (and where they stop)

I want to be fair to the options, because several are genuinely useful for the slice they cover, and I reach for some of them myself.

PyPI, deps.dev, libraries.io, GitHub dependents

For public packages, deps.dev and libraries.io are the right tools, and I would point you straight at them. GitHub's dependency graph adds a "Used by" panel for repositories that publish a package, though its own documentation calls the dependent counts approximate. The structural problem is not that any of these are bad. It is that they are properties of the public index. A private package is access-controlled by design, served from your own registry behind a token, and never indexed by anything that crawls pypi.org. The same access control that keeps your code off the public internet keeps it off every public consumer graph. There is nothing to fix here. The data is unreachable, on purpose. And as above, even for public packages these views count published packages far better than they count the unpublished services that are usually your real consumers.

`pip show`, `pipdeptree`, and the reverse-dependency tools

These do answer a reverse question, and people reach for them first. pip show yourco-clients lists a "Required-by" field. pipdeptree and deptree will invert the tree and show you dependents with -r. They are the right tools for "what in this environment depends on this."

But they operate on one installed environment at a time, outward from whatever happens to be in that virtualenv. They cannot tell you which other repos in the org depend on your package. There is no index-side reverse query to ask, either. pip has had an open request for a reverse-dependency command for years, and the standing workaround is a script that walks installed distributions. To build the org-wide view you would clone every repo, create a clean environment in each, install, run pipdeptree -r, and aggregate the output yourself. By the time you finished, the resolutions you installed from would have moved.

The private index itself

This is the one people assume covers them, because the index is the thing all the packages flow through. AWS CodeArtifact, JFrog Artifactory, Sonatype Nexus, the GitLab PyPI registry, devpi, GemFury. They host your private packages, cache the public ones, and serve both from one endpoint behind auth.

They are very good at it. What none of them model is consumption at the source level. The index records that some authenticated client downloaded yourco-clients 2.4.1. It does not record which repo's pyproject.toml declared the dependency, which team's CI pipeline the install ran in, or whether the thing that pulled it was a service you care about or a throwaway branch. It is a distribution and caching layer, not a consumption graph. This is the same gap I described for internal Go module proxies in the Go edition: a proxy logs fetches, not the manifest that triggered them. The download event is not the dependency edge.

There is one fair exception worth naming. Some registry products, ProGet among them, do surface a consumer view, listing applications by name and version against a package. That is closer than most, and if you run one, use it. But it sees consumption that flows through that registry, of packages it hosts. It does not read the source manifest in every repo regardless of which index they use, and it does not see the git-ref consumption that never touches a registry at all. The next section is mostly a list of the consumption that escapes a registry-centred view.

Renovate and Dependabot

Both support Python as a first-class ecosystem, including private indexes once you give them credentials, across requirements.txt, Poetry, Pipfile, and setup.py. Because they are configured per consumer, they implicitly know which repos depend on what, and they will open pull requests to bump your package when you publish. As with Terraform modules and the rest of the series, the knowledge is in there.

But they are updaters, not mappers. There is no org-level "show me every repo that depends on yourco-clients, and what constraint each one declares" view to query. They react to new versions going out. The question you have before you publish a breaking one, who is currently consuming the old version and how, is not something either tool surfaces. And both only cover repos where they have been switched on for your private index. A team that never configured private-index auth in their Renovate config is simply invisible.

Code search, and the script

You can search your GitHub org or GitLab group for the package name:

org:yourco "yourco-clients"

For a one-off audit, fine. It finds files that mention the string and gives you a starting list of repos. Then the familiar problems land all at once, and in Python they land harder. It returns the declared constraint, not the installed version. It will not normalise yourco_clients and yourco-clients to the same project. It misses a consumer that pulled the package over git+https. And the index lags your most recent commits.

So someone writes the script. Enumerate every repo, fetch every requirements*.txt, pyproject.toml, setup.py, setup.cfg, Pipfile, and environment.yml, parse all of them, handle three pyproject.toml dialects and arbitrary setup.py code, normalise names, evaluate PEP 440 specifiers, run it on a schedule. People build exactly this. The clearest evidence is all-repos-depends, a real org-scanner whose providers read the setup.py AST for the package name and install_requires and parse the requirements-file conventions. The fact that this keeps getting independently rebuilt is the strongest evidence the question matters. It is also, tellingly, honest about its own limit: it can only read a setup.py that sets its name literally. Which is the first of the corner cases below, and that tool ran straight into it too.

Why this is harder than it looks

A naive search for the package name both overcounts and undercounts, because Python dependency consumption is not one fact in one place. It is spread across constructs that each behave differently, and Python has more of them than any other ecosystem in this series.

There is no single manifest, and the formats disagree. Go has one canonical go.mod. npm has one canonical package.json. Python has at least six families, and once you count the dialects, closer to nine distinct shapes a scanner has to handle: requirements.txt and its requirements-*.txt siblings, split requirements/ trees and pip-tools .in inputs, setup.py install_requires, declarative setup.cfg, pyproject.toml in three different dialects (PEP 621 [project], Poetry's [tool.poetry] with its groups, and the PEP 735 [dependency-groups] that uv and recent pip understand), Pipfile, and conda's environment.yml with its nested pip: block. PEP 723 even added inline dependencies inside a single .py script, so the surface is still growing. The version grammar is not even shared: a Poetry caret is not a PEP 440 operator. And the declared constraint and the installed version are different facts living in different places, with the resolved version buried in whichever of poetry.lock, Pipfile.lock, uv.lock, or a pip-compiled requirements.txt the repo happens to use. Real orgs mix all of this. To find every consumer you have to read all of it, and reconcile it.

The distribution name and the import name are different facts. This one is pure Python. You pip install scikit-learn and import sklearn. PyYAML imports as yaml, beautifulsoup4 as bs4, opencv-python as cv2. Your yourco-data-clients might import yourco_data. To bind a declared dependency you match the PEP 503 normalised name, which lowercases and collapses any run of ., -, or _ to a single -, so Yourco.Clients, yourco_clients, and yourco-clients are one project. A grep treats them as three. The confusion is real enough that scikit-learn ships a defensive sklearn shim on PyPI purely to stop people and tools getting it wrong, and that shim's own remediation advice is, word for word, a find-every-consumer task: track down which packages declare sklearn instead of scikit-learn. It is enough of a trap that GitLab's own SBOM scanner normalised names by the wrong rule and produced incorrect dependency results. That normalised distribution name is what a manifest declares and what you match on. The import name, the thing that actually appears in import statements, is a different layer again, and it is the one a symbol graph lives in. More on that distinction when we get to the limits.

setup.py is code, not data. package.json is JSON and go.mod has a defined grammar, so a parser can trust them. setup.py is a Python script, and install_requires can be a literal list, or read from a file, or assembled in a loop, or gated on markers computed at runtime. The literal case is statically parseable from the AST. The dynamically constructed case is not knowable without executing untrusted code, which no scanner should do. setup.cfg and pyproject.toml are declarative and parse cleanly, so the holdout is specifically the older setup.py repos, and even the literal case is a best-effort heuristic rather than a guarantee. This is not a footnote you have to take on faith, it shows up in the consumer view as a lower confidence score on setup.py rows than on the declarative ones. all-repos-depends hit exactly this wall and drew exactly this line.

The same name is not always your package. A repo whose index routing is wrong, or missing, can resolve a public package that happens to share your internal name, which looks identical in the manifest and is not your code. This is not hypothetical: pip's own documentation warns that --extra-index-url is unsafe precisely because a public index can serve a package with the same name as your private one, the dependency-confusion problem. So the name in a manifest is a claim, not proof. Binding the name to your repo safely means resolving it to the in-org repo that actually produces that package, not assuming every matching string is yours. A name nothing in your org produces is an external dependency, not a consumer of your code.

The value is not always a version, and git references travel without an index. A dependency's value can carry the real target, and for internal Python this is how a great deal of code travels without anyone standing up a private index at all. PEP 508 direct references, yourco-clients @ git+https://github.com/yourco/clients.git@v2.4.1, resolve straight from a repo. So does -e git+https://...#egg=yourco-clients, a bare git+... line, a Poetry { git = ... } source, a Pipfile { git = ..., ref = ... }, and a git+ line inside a conda pip: block. Every one of those points at a repo, with the committish standing in for the version. A purely local ./libs/shared or a file: install carries no cross-repo signal, and a plain wheel or sdist URL is not a repo edge either. So the honest split is: git references are first-class consumers and resolve to a repo, while local paths and non-git URLs are not cross-repo edges at all. A scanner that reads only registry-style names misses the entire git-sourced half of how internal Python is consumed.

constraints.txt and includes mean the line you grep is not always the effective version. A repo can declare yourco-clients>=2.4 in requirements.in and then pin it hard via a global -c constraints.txt that says yourco-clients==2.4.1. Or chain -r requirements/base.txt so the real dependency list is assembled across several files. The line you grep is the declared constraint. The effective version, after a constraints overlay, is closer to a lock. For the question this post is about, who adopts your next release, the declared constraint in the dependency line is the load-bearing fact, and the constraints-pinned version is the adjacent, lockfile-shaped question. They are different facts, and a search that reads one file in isolation cannot tell which it is looking at.

Extras and dependency groups change the blast radius, and markers make the edge conditional. A consumer that needs your package only as a PEP 621 [project.optional-dependencies] extra, a Poetry group.test, or a PEP 735 dev group is a weaker consumer than one that imports it at runtime in production. And a PEP 508 marker makes the dependency conditional outright: yourco-clients>=2.4; python_version >= "3.11", or ; sys_platform == "linux". So a consumer may depend on you only inside an extra nobody installs in production, or only on a platform they do not ship. Flattening every declaration into one undifferentiated "depends on" both overstates and understates the blast radius, depending on which way you are wrong. The scope of each declaration, runtime against dev against optional, is part of the answer, not noise to discard.

Namespace packages mean the import namespace is not the unit of dependency. PEP 420 implicit namespace packages let yourco.clients and yourco.auth live in separate distributions, in separate repos, under one shared yourco namespace. The distributions ship and version independently, so the unit of dependency is the distribution, yourco-clients or yourco-auth, not the yourco namespace they share. A tool that treats the top-level import namespace as one package conflates things that release on different schedules. This is the same crack the distribution-versus-import-name beat opened: the manifest layer is about which distribution you declared, and "who imports yourco.auth" is a question one level down, at the symbol layer.

What the full answer requires

To reliably answer "who consumes this internal Python package," you need a system that:

Scans every repo in the org, parsing each manifest family (requirements.txt and its requirements-*.txt and split requirements/ and pip-tools .in variants, pyproject.toml across the PEP 621, Poetry, and PEP 735 dialects, setup.cfg, setup.py, Pipfile, and conda environment.yml), without requiring each team to opt in or register
Normalises distribution names per PEP 503, so -, _, ., and case variants bind to one project, and resolves each declared dependency to the repo that actually produces the package, so a public package sharing your internal name resolves as external rather than binding to the wrong repo
Reads the value, not just the name, resolving PEP 508 direct references, git+https and -e git installs, Poetry and Pipfile git sources, and conda pip: git lines to the right in-org repo, with the committish recorded as the version
Keeps real cross-repo references while dropping purely local file: and ./path installs and plain wheel or sdist URLs that carry no cross-repo signal
Records the scope of each declaration, runtime against dev against optional or extra, so a test-only or extras-only consumer is not weighed the same as a runtime one
Leaves test, example, and fixture trees out of the consumer count, so a repo that imports your package only in a test harness does not read as a production consumer
Reports the constraint each repo declares, which is the fact that governs who adopts your next release, rather than the exact version a lockfile resolved this minute
Stays current through rescans, rather than a one-time snapshot that is stale the moment a manifest changes

This is one of the specific problems Riftmap is built to solve. It connects to your GitHub or GitLab organisation with one read-only token, scans every repo, and parses requirements.txt, split requirements/ trees and pip-tools .in inputs, pyproject.toml across PEP 621, Poetry groups and PEP 735 dependency groups, setup.cfg, setup.py, Pipfile, and conda environment.yml including the nested pip: block. It normalises names per PEP 503 and resolves each declared dependency to the repo that produces the package, so a name nothing in your org produces is treated as external rather than a consumer. It reads the value rather than just the name, so a pip install git+https://gitlab.yourco.com/platform/yourco-clients.git resolves to the platform/yourco-clients repo and is recorded as a consumer with no private index required, while purely local file: installs and plain wheel URLs are skipped. Each edge carries the constraint the consumer declares and the manifest line where it lives. Parsed from what each repo declares, not inferred from what the index happened to serve.

A few honest limits, in the spirit of the rest of this series. Riftmap reads the declared dependency in the manifest, not the resolved lockfile tree, so it shows the constraint each repo declares, which governs who adopts your next release, rather than the exact version each one has installed right now. It binds at the distribution layer, who declares a dependency on the package, not the import-symbol layer, which repos import the specific function or class you are changing. For that symbol-level question a symbol graph like Sourcegraph is the right tool, and a complementary one, because symbol graphs and artifact dependency graphs are different categories. It records a runtime, dev, or optional scope for each declaration, though surfacing that distinction in the consumer view is still on the near-term roadmap, so the panel today shows the manifest, the line, and the constraint rather than a scope label. And because Python has no @scope convention the way npm does, Riftmap recognises an internal package by the fact that some repo in the scanned org produces it, not by a name prefix. A yourco- prefix is a useful convention, not a guarantee.

The result is the view the rest of this series describes. Before you drop that parameter, rename that export, or cut 3.0.0, you open the graph, click the package, and read the consumer list: every repo that declares a dependency on it, the constraint each one carries, the manifest and line where the dependency lives, whether it came from a registry name or a git reference, and which team owns it. You know who breaks. You know who is riding a loose constraint and will pull your next minor on their next Docker rebuild whether you meant them to or not. You know who is stranded on the old major and needs a migration before you can deprecate it. No clean-installing thirty repos to run pipdeptree. No script juggling nine manifest shapes. No waiting to see whose build goes red.

The dependency was never written down in one place

Here is the closing thought. With the other ecosystems in this series, the reverse question is hard because the consumer graph lives behind access control, or in a proxy that logs the wrong event. That is true for Python too. But Python adds a second, deeper reason, and it is the one worth sitting with.

Python gives you a dozen honest ways to declare a dependency, and two different names for every package, and no single place that reconciles them. The dependency on your library exists, but it was never written down in one canonical form. It is a constraint in a requirements.txt here, a PEP 621 entry there, a Poetry caret somewhere else, a git+https reference in a fourth repo, all under a distribution name that does not match the import name, half of them rerouted by a constraints file you have to read separately. The reverse question is not hard because Python is messy. It is hard because the thing you are trying to find was never recorded as one thing. It lives spread across nine manifest shapes and two namespaces, in the relationship between repos that no single checkout contains. That was never a property of pip, or of PyPI, or of your index. It was a property of asking the question from inside one repo, when the answer was always somewhere between them.

This is the eighth post in the Find Every Consumer series. Previous posts cover Docker base images, Terraform modules, GitHub Actions workflows, Helm charts, Go modules, GitLab CI templates and internal npm packages.

If this is a problem your platform team deals with, I would be interested to hear how you are solving it today. You can find more at riftmap.dev or reach me at the address on the about page.

About Riftmap

Riftmap maps cross-repo dependencies across your entire GitLab or GitHub organisation — Terraform, Docker, CI templates, Helm, Python, Go, npm, and more. One read-only token. No YAML to maintain.

A CVE just hit your base image. Your scanner won't tell you which repos to fix.

Daniel Westgaard — Mon, 15 Jun 2026 00:00:00 GMT

In January 2026, CVE-2026-0861 landed in glibc. An integer overflow in the memalign family, rated high, present in every glibc from 2.30 to 2.42. Which is to say: present in debian:bookworm-slim, and in the default python, node, and golang tags, all of which are Debian underneath. The -alpine variants dodged this one, because musl is not glibc. Everything else inherited it.

If you ran a scanner across your registry, you knew within the hour. The dashboard went red. Trivy, Grype, Docker Scout, whichever one you use, they are good at this now. The CVE is high. It is in your base. Forty images flagged.

And then you sit there with the one question the dashboard does not answer. Which repositories do I open a pull request in.

Those feel like the same question. A scanner found the vulnerable image, so surely it can point me at the fix. They are not the same question, and the gap between them is the whole reason a base-image CVE takes three days instead of an afternoon.

Detecting a vulnerable image and knowing where to fix it are two different jobs. The first is an inventory of what is wrong. It is computed from the image, on the registry side or the runtime side, by reading the layers and matching package versions against an advisory feed. The second is a map of where the edit goes. And the edit does not go into the image. It goes into a Dockerfile, in a repository, that a person owns. Those repositories are a different list, derived from a different source, and your scanner never saw them.

This post is about that second list, and why the tools that produce the first one structurally cannot produce it.

What the scanner actually knows

I want to be fair to the scanners, because they are genuinely excellent and the criticism here is narrow.

Take Docker Scout, the most capable of them at the remediation end. Point it at an image and it builds an SBOM, matches every package against CVE feeds, and shows you the vulnerabilities ranked by severity. Run docker scout recommendations and it will tell you the base is out of date and which newer tag clears the most CVEs, sometimes as specific as "this tag fixes three". It ships an Up-to-Date Base Images policy that flags images still sitting on a stale base. With provenance attestations it identifies the exact base image and digest you built from. And with the GitHub integration wired up, it can open the remediation pull request for you, straight from the dashboard. That is real, and it is good.

Trivy and Grype sit a little further back, by design. You point them at a target. An image, a filesystem, an SBOM, a running cluster. They tell you what is vulnerable in that target. Same shape. The unit of work is a thing you hand them, and the output is the verdict on that thing.

And before someone says Renovate already handles this: partly, and it is worth being precise about which part. Renovate and Dependabot will open a base-image bump in each repo they are configured on, one repo at a time. That is genuinely useful, and it is the other half of remediation, the mechanical edit. But they operate per repo and tell you nothing about the consumer set as a whole. They will not tell you that forty repos share this base, which of them are on which tag, who owns each, or that the real first move is a shared internal base two hops up. They keep versions current. They do not give you the blast radius. An SBOM has the same problem in the other direction: it is an inventory of what is inside one image, the contents of an artefact rather than the consumers of it.

Now notice what the unit is in every one of these. It is an image. Or it is one repository, the one that built a given image, reached from the image through its provenance. Scout's image hierarchy is the ancestry of the image in front of you: what it was built FROM, going up. That is a real and useful relationship, and it runs in exactly the wrong direction for the question you are now asking.

The relationship you need runs the other way

A base-image CVE does not ask what this image was built from. It asks who is built on top of this base. That is the inverse relationship, and it is not one a scanner can give you, because it is not visible from any single image.

Scout, at its best, maps an image to the one repository that produced it. One image, one source repo, via the attestation. That is a one-to-one link, and it answers "where did this image come from".

What a base-image CVE forces is a one-to-many link. One base image, every repository in the organisation whose Dockerfile declares FROM it. Twelve repos, forty, a hundred and ten. Each pinning a different tag. Each owned by a different team. Some built on the base directly, some built on an internal image that is itself built on the base. That fan-out is the remediation topology, and it lives in FROM lines spread across every repo you have. Not in the registry. Not in the runtime. Not in any one image's SBOM. In source.

"What's running" is the wrong index for "what to change"

The reflex is to reach for the registry or the cluster, because that is where the scanner already looks. Both are the wrong index, and it is worth being precise about why, because the reasons are not edge cases.

The registry knows which images exist and, with provenance, what each was built from. The runtime knows what is deployed right now. Neither is the set of FROM lines in your repositories, and the divergence shows up immediately.

A repo whose image is not currently deployed still has a vulnerable Dockerfile, and it will rebuild the vulnerable base on its next merge. The runtime cannot see it. The tag a Dockerfile pins is frequently not a literal: it is FROM ${REGISTRY}/base:${BASE_VERSION}, resolved at build time from an ARG or a CI variable, so the registry's record of what was built and the repo's record of what is requested are two different strings. Internal mirrors and pull-through caches rewrite the name, so the image in your registry is harbor.internal/library/python and the thing you actually have to find across your repos is python. And the base you care about is often two hops up: your teams build FROM acme/runtime-base, which is built FROM debian, so the glibc fix has to propagate from debian to runtime-base to the forty leaf repos, and the scanner that flagged forty leaf images cannot tell you that the real first move is one pull request against runtime-base.

Every one of those is a case where the inventory of what is vulnerable and the map of what to edit pull apart. The edit lands in source. So the index has to be built from source.

The fix is a graph query, not a scan

Strip the panic away and the thing you need at the moment a base-image CVE drops is small and specific. Every repository that declares a dependency on this base, directly or transitively. The tag or digest each one pins, so you can tell who is already on a patched base and who is not. The team that owns each repo, so you know who to route the pull request to. And the order, so you fix runtime-base before you fix the forty repos that sit on it.

That is a query against a graph of your FROM edges. And the only honest way to build that graph is to parse it. Read the FROM lines in every repository, resolve the ARG defaults and the multi-stage AS aliases and the Compose image: references, normalise the internal-mirror names back to the base they point at, and connect the edges. Parsed, not inferred. Not guessed from image names that happen to look similar. Not reconstructed from a catalogue someone updated last quarter. Not pieced together from a Slack thread. Read from the files that already declare the dependency, because those files are the source of truth, and they are also exactly where your fix is going to land.

The enumeration has more sharp edges than it looks: ARG-templated tags, multi-stage builds where only one stage matters, Compose files that reference the image with no Dockerfile in sight, repos that produce the base as well as consume it. I wrote up the full mechanics of parsing all of that in how to find every consumer of your Docker base image. This post is the layer above it. Not how to build the list, but why the scanner that found the CVE was never going to be the thing that hands it to you.

Even "we can wait on this one" needs the list

There is a version of this where the CVE turns out not to be urgent, and it is worth following through, because it makes the same point from the other side.

CVE-2026-0861 is a good example. It is rated high, but exploiting it requires an attacker to control both the size and the alignment passed to memalign, with the alignment pushed into a range no ordinary program ever reaches. In most services it is not practically reachable. A reasonable platform team might decide to let it ride to the next routine base bump rather than scramble at midnight.

But that is a per-consumer decision, and you cannot make it without the per-consumer list. "Is this reachable in our usage" has a different answer in the one repo that does its own aligned allocation than in the forty that never call memalign directly. To triage at all, to say these three we patch tonight and the rest wait for the monthly rebuild, you first have to know which repos those are and how each one uses the base. Deprioritising safely is not the absence of the graph. It is one of the things the graph is for. The scanner's per-image severity score tells you the CVE is high. It does not tell you it is high here, in this repo, given how this repo uses the base, and that last clause is the only one that decides whether anyone loses sleep.

The two lists

So here is the shape of it, stripped down.

Your scanner produced a list: the images that are vulnerable. That list is real and you need it. But it is an inventory of what is wrong, indexed by image, computed from the registry and the runtime.

The list you actually act on is a different one: the repositories that declare FROM this base, with their tags and their owners and their order. That list is a map of where to go, indexed by repository, and it can only be computed from source, because source is the one place the FROM edge is written down and the one place the fix can land.

A scanner is very good at telling you the building has a problem. It is just not the thing that hands you the keys to the rooms you have to walk into. Those are different artefacts, and on the morning a base-image CVE drops, the second one is the only one that shortens the day.

This is the query Riftmap is built to answer. Point it at your GitLab or GitHub organisation with one read-only token and it parses the FROM edges across every repo, resolving the ARG defaults, the multi-stage stages, and the internal-mirror names, and builds the consumer graph. When a base-image CVE drops you select the base, and you get the list: every repository on it, direct and transitive, the tag each one pins, the team that owns it. The scanner tells you the image is vulnerable. Riftmap tells you where the fix goes.

Riftmap scans your GitHub or GitLab organisation with one read-only token, parses Terraform, Docker, Helm, Kustomize, Kubernetes, GitHub Actions, GitLab CI, Ansible, Go modules, and npm, and holds the cross-repo dependency graph as a queryable surface. The "which repos consume this base" query is one call. The free tier is here.

For the parsing detail behind the consumer query, the Find Every Consumer series walks one ecosystem at a time, starting with Docker base images.

For the planned-removal version of the same problem — same fan-out, different trigger — see You deprecated the internal library. The repos still using it never saw the warning.

And for the pre-merge version — checking which repos a change hits before the pull request is open, whether a person or an AI agent is driving — see Can AI check the blast radius of a PR before you merge? The gate itself, a forty-line CI job that posts the consumer count on every pull request, is in How to add a blast-radius gate to your merge pipeline.

Your senior engineer just gave notice. Most of what they knew was in the repos all along.

Daniel Westgaard — Sun, 14 Jun 2026 00:00:00 GMT

Tribal knowledge is two different things wearing one name. The half everyone panics about losing was declared in your Terraform, your Dockerfiles, and your CI config the whole time.

It usually starts with a calendar invite that has no agenda. Thirty minutes, your senior platform engineer, no subject line. You half know before you sit down. They have been here six years. They are leaving in a month.

The first day you feel it as a personal loss, because it is one. The operational version arrives later, usually in a standup. Someone proposes bumping the base image that half the services build from. Routine work. Then somebody asks who actually knows everything that pulls from it, and the room goes quiet, and every face turns very slightly towards the person who is leaving.

That quiet is the sound of a team discovering its bus factor in real time. The reflex that follows is always the same. Get it out of their head before they go. Book the knowledge-transfer sessions. Start a wiki page. Pair them with someone for the notice period and hope.

I want to argue that this reflex is half right, and that the half it gets wrong is the expensive half.

The word that hides two different problems

We call it tribal knowledge, and we say it as though it were one thing. It is not. Two very different kinds of knowledge shelter under that one phrase, and the panic about a departing engineer conflates them, which is why the panic so often spends its energy in the wrong place.

The first kind is genuinely tacit. It is the why. Why the payments service retries three times and not five. Which of the two cloud accounts the staging environment actually bills to, and the historical accident that explains it. Who to call at the vendor when a certificate renewal fails silently, because you have learned the hard way that the support queue will not help you. The incident two years ago whose scar tissue is the reason one config flag exists and must never be flipped. None of this is written down, and most of it cannot be derived from anything. It lives in one person. It will leave with them. This kind of knowledge is real, it is valuable, and getting it out before someone walks out the door is worth doing.

The tools built for this are good at it. Swimm, Confluence, Notion, a decent internal wiki, an afternoon of recorded walkthroughs. The whole category exists to move the contents of a person's head into a form the organisation can read later, and for tacit knowledge that is the right move. There is a reason it so rarely happens, and it is not that teams do not care. It is that the person holding the knowledge does not know they are holding anything unusual. To them, the field that two services name differently for the same value, so that mixing them produces output that is wrong but does not error, is not a secret worth recording. It is just how the thing works. You cannot ask someone to write down what they do not know is worth writing down.

So far, so familiar. Here is the part the panic misses.

Half of it was never tribal

The second kind of knowledge hiding under tribal knowledge is the structural map. Which repositories depend on which. What breaks if the base image moves. Where the shared Terraform module is consumed, and by whom. Which pipelines pull the CI template you are about to edit. Which services still pin the old tag and will fail their next rebuild the moment you ship.

This is what the standup was really asking for when the room went quiet. And it feels identical to the tacit kind, because it also lived in one person's head, and because losing the person feels like losing all of it at once. But it has a property the tacit kind does not, and the whole argument turns on this property.

It was already written down.

Not in a wiki. In the manifests. Every edge your departing engineer carried in their head was declared somewhere in the source, by someone, on purpose. The base-image relationship is a FROM line in a Dockerfile. The module relationship is a source block in Terraform. The chart dependency is a value reference in a Helm chart. The pipeline relationship is an include in GitLab CI or a reusable workflow in GitHub Actions. The library relationship is a require in a go.mod or a line in a lockfile. None of these are tacit. They are facts in plain text, in repositories you already own, waiting for someone to read them.

So why did it ever feel like tribal knowledge? Because nobody else had read all of it. Reading every FROM line and every source block and every include across two hundred repositories, and holding the result in your head as one connected graph, is most of a person's job for a very long time. Your senior did not do it in a sitting. They accreted it, one incident and one migration and one code review at a time, over six years, until they had quietly become the index. When they leave, the index leaves. But the thing the index pointed at, the actual declared structure, is sitting in the repos exactly where it was this morning, entirely unchanged by their resignation.

That is the difference that matters. You genuinely cannot regenerate the why from the source. You can absolutely regenerate the what-depends-on-what from the source, because it was never anywhere else to begin with. One is a memory problem. The other is a parsing problem. The panic treats them as one problem, reaches for a memory solution, the wiki and the handover session, and points it at the thing that was a parsing problem all along.

I want to be precise about the boundary, because this audience will catch me if I am not. Not every coupling between two systems is declared in a manifest. If one service calls another over an internal endpoint that appears in neither side's configuration, no parser will find that edge, and your senior may well have carried it too. That sort of runtime coupling belongs closer to the tacit pile, and it is worth getting onto a diagram while you still can. But the heavy, expensive structure, the build and deploy and infrastructure substrate that everything else stands on, is overwhelmingly declared. That is the part that looks lost when someone leaves and is not.

The handover is the wrong place to rebuild a map

Watch what most teams do with the weeks they have left. They put the departing engineer in a room and ask them to draw the dependency diagram. Map the services. List what depends on the shared module. Write the runbook for the base-image bump. It feels responsible. It is mostly waste, for three reasons.

The first we have already met. They do not know which edges are load-bearing, because to them every edge is just true. They will lovingly document the interesting parts, the clever bits they are proud of, and they will not think to mention the dull tag pin in a sleepy repository that has not changed in a year and will take production down the first time someone bumps the image. The boring edges are the ones that bite. The boring edges are exactly the ones a human brain-dump skips.

The second is that the diagram is stale the moment it is drawn. It is accurate on the day. Then the first migration after they leave moves something, the diagram does not move with it, and nothing tells you it has drifted. Platform teams have been rediscovering this for years under another name. It is the same reason service catalogs rot, and the same reason so many Backstage rollouts quietly stall, which I went through in detail when writing about developer portals. A hand-maintained model of how the system fits together is only ever as accurate as the last person who remembered to update it, and people stop remembering. Developer portals solve real problems and the teams that adopt them are not naive. The catalog rots anyway. A dependency map drawn by hand is a service catalog with a bus factor of one, drawn by the very person who is about to leave.

The third reason is the one that actually matters, and it is why this is not just a tooling preference. The notice period is the single most scarce resource you will have for a long time, and you are spending it on the one kind of knowledge a machine could have reconstructed for nothing, while short-changing the kind that genuinely needed a human. Every hour your senior spends drawing boxes and arrows a parser could have produced in a minute is an hour they are not spending on the why. The vendor contact. The incident scar tissue. The flag that must never flip. That is the knowledge that walks out for good, that the handover should exist to protect, and that gets crowded out because everyone is busy rebuilding a map which was in the repositories the entire time.

Keep them for what only they know

The fix is not a better wiki and it is not a more disciplined handover. It is to stop treating two different problems as one. Separate the piles.

The tacit pile, the why, is what the human's last weeks are for. Sit with them. Record it. Ask the awkward questions about the flag and the vendor and the account. That time is irreplaceable, you will not get it back, so protect it from being eaten by box-drawing.

The structural pile, the what-depends-on-what, does not need the human at all. It needs something to read the manifests across the whole organisation and assemble them into the graph your senior had been assembling by hand. The edges are declared. The only thing ever missing was someone, or something, that had read all of them at once, and kept reading after the person left.

This is the part of the problem I build for. Riftmap reads the declared dependencies across an entire GitHub or GitLab organisation, Terraform, Docker, Helm, CI, package manifests, and builds the cross-repo dependency graph from the source itself, with one read-only token and no catalog to maintain. It is the map your senior held, reconstructed deterministically, and kept current after they are gone, because it re-reads the repositories rather than trusting a diagram somebody drew in their final week. Ask it what breaks if you bump the base image and the answer comes from what the repositories declare today, not from what anyone remembered to write down in March. This is less a new idea than an obvious one once you see the split. Even Meta, with effectively unlimited engineers, landed in the same place on their own pipelines and generated a cross-repo dependency index rather than asking people to maintain a map by hand.

There is a second thing the graph gives you, and if you are the one who just received the resignation it is the thing I would lead with. Once the structure is parsed, you can ask a question the departing engineer could never have answered honestly about themselves. Which of the repositories that everything else depends on are maintained by exactly one person. The high-blast-radius, single-maintainer substrate. The build image, the shared CI template, the base module the whole organisation leans on, that it turns out precisely one human has touched in a year. That is your next resignation, visible before it arrives. An engineer I have a lot of respect for, Owen Zanzal, pushed me towards this framing, and it is worth a post of its own, which is coming. The short version is that the moment you have the dependency graph, ownership stops being a question of who wrote the code and becomes a question of who maintains the things everyone else is standing on.

The map did not leave

When the person who understood how everything fit together hands in their notice, it feels as though the map is leaving with them. It is not. The map was in your manifests the whole time. They were simply the only one who had read all of it. Keep their last weeks for the things only they know. The rest was never theirs to take.

How to Find Every Consumer of Your Internal npm Package

Daniel Westgaard — Sat, 13 Jun 2026 00:00:00 GMT

You maintain a scoped, internal npm package on a private registry. You need to change its API. Which repos across the org depend on it, and at which version? The public npm ecosystem has tools for this question. The moment you put an @ in front of the name and point an .npmrc at your own registry, every one of them stops working.

Open the page for any popular public package on npmjs.com and click the Dependents tab. For lodash you get a number in the hundreds of thousands. The data is incomplete and the ranking is crude, but the question "who depends on this" has a first-class home in the public registry, and a small ecosystem around it: libraries.io, Google's deps.dev, a dozen abandoned npm-dependents CLIs on the registry itself.

Now scope the package. Rename it from confit to @yourco/confit, set its access to restricted, and publish it to Verdaccio or the GitLab package registry instead of registry.npmjs.org. Everything you just relied on evaporates. There is no Dependents tab, because npmjs.com never sees the package. libraries.io and deps.dev crawl the public registry, so they are blind to it too. And there is no local fallback either: as the maintainer of one of those abandoned reverse-lookup tools put it, there is no npm command for retrieving a list or count of modules that depend on a given package, and the registry's own dependents data only covers non-scoped public packages anyway.

So the reverse question is answered for the packages that can't hurt you and unanswered for the ones that can. The package you scoped and locked down, the shared UI kit or the internal SDK that fifteen of your services import, the one whose breaking change is actually your problem, is precisely the one with no consumer view at all. This post is about getting that view back.

The scenario

Your platform or frontend-platform team publishes @yourco/ui. Maybe it's a component library every web app imports. Maybe it's @yourco/sdk, a generated client for your internal APIs. Maybe it's @yourco/config, a thin package that standardises ESLint, tsconfig, and build settings across the org so nobody hand-rolls them.

It started as a way to stop copy-pasting. A few apps adopted it. Then more. Consumers declare it the ordinary way, in package.json:

{
  "name": "@yourco/checkout-web",
  "dependencies": {
    "@yourco/ui": "^4.2.0",
    "@yourco/sdk": "~2.1.0"
  }
}

Because it's scoped and private, every consumer also carries an .npmrc that tells the package manager where @yourco resolves from:

@yourco:registry=https://gitlab.yourco.com/api/v4/packages/npm/
//gitlab.yourco.com/api/v4/packages/npm/:_authToken=${NPM_TOKEN}

Some consumers pin a caret range and float across minors. Some pin tighter. Some live in a monorepo and reference the package over the workspace: protocol instead of through the registry at all:

{
  "dependencies": {
    "@yourco/ui": "workspace:*"
  }
}

And the version each of them actually has installed lives somewhere else entirely, in a lockfile, which may say something quite different from the range in package.json. Twenty repos adopted the package. Then you stopped counting, because nothing in your toolchain counts for you. Now you need to change it. Drop a prop, restructure an export, bump a major. The question is the one that runs through every post in this series: which repos across the org depend on this package, at which version, and which of them break when I publish?

The change you ship without shipping it

Before the tooling, the part that makes this sharper than it first looks. A caret range is a standing instruction to adopt your next release automatically.

A consumer on "@yourco/ui": "^4.2.0" is not pinned to 4.2.0. They are subscribed to every 4.x you publish. The next time their CI runs a fresh install, or someone deletes a lockfile and reinstalls, they pull whatever the newest 4.x is and build against it. You did not roll it out. They did not opt in. If your "harmless" 4.3.0 minor carries a regression, you have just deployed it across every caret consumer on their schedule, not yours, and the first you hear of it is someone else's red pipeline.

The reverse case is just as bad in the other direction. When you do the honest thing and ship a genuine breaking change as a major, 4.x to 5.0.0, caret ranges correctly refuse to follow. Which means every consumer stays on 4.x until a human edits their package.json and migrates. That is the right behaviour, but it leaves you with a long tail of repos stranded on the old major, indefinitely, and no list of who they are. You cannot deprecate 4.x because you cannot see who is still on it.

Either way, the version range is the mechanism, and the version range is exactly what a quick search across your repos cannot evaluate. You need to know who consumes the package and how their range relates to what you are about to publish. Both halves of that live in files most audits never open.

What existing tools give you (and where they stop)

I want to be fair to the options, because several are genuinely useful for the slice they cover.

npmjs.com Dependents, deps.dev, libraries.io

For public packages these are the right tools, and I'd point you straight at them. The structural problem is not that they're bad. It's that they are properties of the public registry. A private scoped package is access-controlled by design, served from your own registry behind a token, and never indexed by anything that crawls registry.npmjs.org. The same access control that keeps your code off the public internet keeps it off every public consumer graph. There is nothing to fix here. The data simply isn't reachable, on purpose.

`npm ls`, `npm explain`, `npm why`

These do answer a reverse question, and people reach for them first. npm explain <pkg> (and yarn why or pnpm why in the other managers) tells you why a package is present in the current install: which dependency path pulled it in. It's the right tool for "why is this transitive thing in my tree."

But it operates on one installed project at a time, outward from that project's own node_modules. It cannot tell you which other repos in the org depend on your package. To build the org-wide view you would run it in every repo, after a clean install in each, and aggregate the output yourself. By the time you finished, the lockfiles you installed from would have moved.

The private registry itself

This is the one people assume covers them, because the registry is the thing all the packages flow through. Verdaccio describes itself as a lightweight private proxy registry: host your private packages, cache the public ones, serve both from one endpoint. The GitLab package registry, Artifactory, Nexus, and GitHub Packages all do the same job.

They are very good at it. What none of them model is consumption at the source level. The registry records that some authenticated client downloaded @yourco/ui@4.2.0. It does not record which repo's package.json declared the dependency, which team's CI pipeline the install ran in, or whether the thing that pulled it was a service you care about or a throwaway branch. It's a distribution and caching layer, not a consumption graph. This is the same gap I described for internal Go module proxies in the Go edition of this series: a proxy logs fetches, not the go.mod that triggered them. The npm version is identical. The download event is not the dependency edge.

(GitLab has at least started exposing what packages exist at the group level, after years of requests for a group-level packages API. That tells you what's published across a group. It still doesn't tell you who consumes it.)

Renovate and Dependabot

Both support npm as a first-class ecosystem, including private registries once you give them credentials. Because they're configured per consumer, they implicitly know which repos depend on what, and they'll open PRs to bump your package when you publish. As with Terraform modules and the rest of the series, the knowledge is in there.

But they're updaters, not mappers. There is no org-level "show me every repo that depends on @yourco/ui, and what range each one declares" view to query. They react to new versions going out. The question you have before you publish a breaking one, who is currently consuming the old version and how, is not something either tool surfaces. And both only cover repos where they've been switched on for your registry. A team that never configured private-scope auth in their Renovate config is simply invisible.

Code search, and the script

You can search your GitHub org or GitLab group for the package name:

org:yourco "@yourco/ui"

For a one-off audit, fine. It finds package.json files that mention the string and gives you a starting list of repos. Then the familiar problems land all at once. It returns the declared range, not the installed version. It doesn't read the .npmrc to confirm the package even resolved from your registry. It won't find a consumer that aliased the package under a different key, or one that references it over workspace:. And the index lags your most recent commits.

So someone writes the script. Enumerate every repo, fetch every package.json, parse the JSON, pull dependencies and the other three blocks, filter for your scope, then fetch the lockfiles to get real versions, handle three or four lockfile formats, run it on a schedule, store the results. People build exactly this. There's a nice writeup of querying every package.json across Microsoft's 4,000+ public repos with SQL to rank their most-declared dependencies, which is the same machinery pointed at the same data. The fact that this keeps getting independently rebuilt is the strongest evidence the question matters. It's also a parser you now own, with every corner case below as your backlog.

Why this is harder than it looks

A naive search for the package name both overcounts and undercounts, because npm dependency consumption is not one fact in one place. It's spread across several constructs that each behave differently.

The declared range and the installed version are different facts. package.json records a range, ^4.2.0. What that range actually resolved to, say 4.7.1, lives in a lockfile, and the lockfiles diverge by manager: npm writes package-lock.json, Yarn Classic and Yarn Berry write incompatible yarn.lock formats, pnpm writes pnpm-lock.yaml, and Bun shipped a binary bun.lockb you cannot grep at all before switching its default to a text bun.lock. For the question this post is about, who adopts your next release and who you'll have to migrate, the declared range is the load-bearing fact, and it sits in package.json. The resolved version answers the adjacent question of what's installed this minute, and it's buried in whichever lockfile the repo happens to use.

The same name doesn't always mean the same package. Scope-to-registry routing lives in each consumer's .npmrc: @yourco:registry=.... A repo whose .npmrc is wrong, or missing, can pull a public package that happens to share your internal name, which looks identical in package.json and is not your code at all. So the name in the dependency block is a claim, not proof. Binding @yourco/ui to your repo safely means confirming the consumer really resolves your scope from your registry, not assuming every matching string is yours.

The value isn't always a version range. A package.json entry's value can carry the real target, and internal packages lean on this constantly. "x": "npm:@yourco/real@^1" is an alias: the key is x, the package is @yourco/real, and a search for the package name never matches. "@yourco/ui": "github:yourco/ui#v4", or git+https://gitlab.yourco.com/yourco/ui.git, is a git dependency that resolves straight from a repo and never touches a registry. "shared": "file:../shared" is local and carries no cross-repo signal at all. A scanner that reads only the key, or treats every value as semver, misses the aliased consumers and the git-sourced ones entirely. For an internal package, git references are not an edge case. They're how a lot of orgs consume their own code without standing up a registry at all.

Workspaces make internal consumers invisible to the registry. In a monorepo, packages reference each other over the workspace: protocol, and pnpm and Yarn refuse to resolve those to anything but the local copy. The dependency never touches the registry, never produces a download event, never appears in any registry-side view. A consumer living in the same monorepo as your package has very real blast radius and a registry footprint of exactly zero. npm, Yarn, pnpm, and Bun implement workspaces a little differently, but they share that property: the edge is a symlink on disk, not a registry transaction.

overrides and resolutions can reroute the version behind the manifest's back. npm overrides, Yarn resolutions, and pnpm overrides let a repo force a dependency, including a deep transitive one, to a pinned version or a forked replacement. The dependency block says ^4.2.0, the override quietly swaps in 4.6.3 or a patched fork, and the version running is not the one declared. This is the npm analogue of a Go replace directive, with the same trap: the apparent consumer and the actual consumer are not the same thing.

There are four declaration blocks, and they mean four different things. A package can appear in dependencies, devDependencies, peerDependencies, or optionalDependencies. A peerDependency on your package means the consumer expects the host application to supply it, so a breaking change ripples differently than it would for a direct runtime dependency. A devDependency breaks builds and tooling, not production. Flattening all four into one undifferentiated "depends on" both overstates and understates the blast radius, depending on which way you're wrong.

What the full answer requires

To reliably answer "who consumes this internal npm package," you need a system that:

Scans every repo in the org, parsing each package.json, without requiring each team to opt in or register
Resolves each declared dependency to the repo that actually produces the package, by matching the package name, with a guard so a public package that shares your internal name doesn't bind to the wrong repo
Reads the dependency value, not just the name, so npm: aliases and github: or git+https git references resolve to the right in-org repo instead of being missed
Keeps workspace: and catalog: monorepo references while skipping purely local file: and link: deps that carry no cross-repo signal
Distinguishes the four declaration blocks, so a peerDependency consumer and a devDependency consumer aren't flattened into one edge
Leaves test, example, and fixture trees out of the consumer count, so a repo that imports your package only in a test harness doesn't read as a production consumer
Stays current through rescans, rather than a one-time snapshot that's stale the moment a manifest changes

This is one of the specific problems Riftmap is built to solve. It connects to your GitHub or GitLab organisation with one read-only token, scans every repo, and parses every package.json to extract npm dependency edges. It resolves each declared dependency to the repo that produces the package, and reads the value rather than just the name, so npm: aliases and github: or git+https git references resolve to the right in-org repo instead of being missed. It separates the four declaration blocks into runtime, dev, peer and optional, keeps workspace: and catalog: references while dropping purely local file: deps, and leaves test and example trees out of the consumer count. Each edge carries the constraint the consumer declares and the package.json line where it lives. Parsed from what each repo declares, not inferred from what the registry happened to serve.

Two honest limits, in the spirit of the rest of this series. Riftmap reads the declared dependency in package.json, not the resolved lockfile tree. So it shows the range each repo declares, which is the fact that governs who adopts your next release, rather than the exact version each one has installed this minute. And it recognises internal packages by their scope, so a shop that publishes unscoped packages to a private registry is the current blind spot.

The result is the view the rest of this series describes. Before you drop that prop, restructure that export, or cut 5.0.0, you open the graph, click the package, and read the consumer list: every repo that depends on @yourco/ui, the constraint it declares, whether it's a runtime, peer, or dev dependency, the package.json line where the dependency lives, and which team owns it. You know who breaks. You know who's riding a caret range and will pull your next minor whether you meant them to or not. You know who's stranded on the old major and needs a migration before you can deprecate it. No clean-installing thirty repos to run npm ls. No SQL over every package.json. No waiting to see whose build goes red.

A scope keeps the package private and the consumers invisible

Here's the closing thought. A scoped, restricted package on a private registry is the right call. It keeps proprietary code off the public internet, and it gives you real control over who can pull it. That's distribution, and the registry does distribution well.

But distribution and blast radius are different questions, and the registry only answers the first. It knows who is allowed to pull your package. It has nothing to say about who already did, what they declared, or what breaks when you change it. The public packages, the ones whose blast radius is somebody else's problem, get a Dependents tab and a crawler ecosystem. Your internal package, the one whose breaking change lands on your own org, gets a download counter. The thing you did to protect the code is the same thing that hides who depends on it. That gap was never a property of npm. It was a property of where you chose to look.

This is the seventh post in the Find Every Consumer series. Previous posts cover Docker base images, Terraform modules, GitHub Actions workflows, Helm charts, Go modules and GitLab CI templates.

If this is a problem your platform team deals with, I'd be interested to hear how you're solving it today. You can find more at riftmap.dev or reach me at hello@riftmap.dev.

About Riftmap

Riftmap maps cross-repo dependencies across your entire GitLab or GitHub organisation — Terraform, Docker, CI templates, Helm, npm, and more. One read-only token. No YAML to maintain.

GitLab Orbit maps your whole SDLC. It still can't tell you what an infrastructure change will break.

Daniel Westgaard — Fri, 12 Jun 2026 00:00:00 GMT

GitLab Orbit is an excellent symbol-and-SDLC graph. It is also the clearest illustration yet of the one layer that kind of graph cannot reach: the infrastructure dependencies running between your repositories.

Somewhere in the GitLab Orbit launch on 10 June is a line about, in GitLab's phrasing, "map vulnerability blast radius in minutes". I have written some version of that line more times than I can count. When a public DevSecOps company ships a graph and reaches for the exact words your product is built on, the responsible thing is to go and read everything they actually shipped before saying a word about it. So I spent two days in the docs, the data model, the source repository, and the customer write-up at the centre of the launch.

Here is what I found. "Blast radius" is two questions wearing one phrase, and Orbit answers the other one. Ask "what breaks if I change this" at the symbol layer and you get one graph. Ask it at the infrastructure layer and you get a completely different one. Orbit builds the first. It builds it well. It is not the graph that tells a platform team what a base image bump is about to take down.

What GitLab actually shipped

I want to be generous about this, because Orbit deserves it, and because what Orbit is good at and what Riftmap is for barely overlap.

Orbit indexes your code and your software lifecycle into one property graph and lets you query it with a Cypher-like language, over MCP, over REST, or from the GitLab CLI. It ships in two shapes. Orbit Local is a single-binary CLI that builds a code-only graph from a repository on your machine. Orbit Remote is the hosted version that spans a top-level GitLab.com group, and it is the one the launch is really about. It is in public beta for GitLab.com Premium and Ultimate. On the code side it parses around a dozen general-purpose programming languages and reads out definitions and cross-file references. On the lifecycle side it ingests the objects GitLab already stores: merge requests, pipelines, jobs, deployments, vulnerabilities, ownership. The docs lay all of this out plainly.

The launch leans hard on one customer, and it is a good choice. Compare the Market ran a careful test of four context strategies for an internal AI code reviewer, across 79 real merge requests with expert-annotated ground truth. The graph-grounded reviewer beat retrieval-augmented generation on inline-comment coverage, roughly 0.70 against 0.58, and the genuinely surprising finding was that RAG did worse than passing the model no context at all. That is well-run engineering and an interesting result, and you can read the whole write-up rather than the press-release version of it. If you run agents over a large GitLab codebase and you want them to stop burning a third of their token budget crawling files to work out what calls what, Orbit is a real answer to a real problem.

So let me be clear about what Orbit does that Riftmap does not attempt. Questions like where a function lives, who calls it, what a method signature touches, which pipeline ran a job, who owns a service. Across a GitLab group, Orbit answers all of that from first-party data, and Riftmap never set out to. If that is your question, use Orbit.

What GitLab Orbit costs

Because the launch keeps drawing pricing questions, here is the shape of it as of July 2026, with the caveat that a public-beta price is a placeholder and GitLab has not committed to what it becomes at general availability.

There is no separate GitLab Orbit SKU. Orbit is not a line item you buy on top of your subscription; it is a capability gated behind the tier you already pay for. The two shapes cost differently:

Orbit Local — the single-binary CLI that builds a code-only graph of one repository on your machine — is effectively free to run. It is a tool you download; there is no hosted service metering it. It is also not the thing the launch is about, because it does not span an organisation.
Orbit Remote — the hosted, group-wide graph that the launch actually markets — is in public beta for GitLab.com Premium and Ultimate. In beta that means the cost of Orbit Remote is the cost of the GitLab.com tier it rides on: Premium and Ultimate are GitLab's paid tiers, billed per seat, and Orbit Remote is switched on within them rather than priced on its own. It is GitLab.com only; there is no self-managed Orbit Remote, and no Free-tier access.

The practical read for a platform team: if you are already on GitLab.com Premium or Ultimate, evaluating Orbit Remote costs you nothing beyond the seats you hold today, and the beta is the moment to test it against your own graph questions before any GA price lands. If you are on GitLab Free, self-managed GitLab, or GitHub, there is no priced path to Orbit Remote at all — which loops straight back to the architectural wall in the next-but-one section: the limit was never the money.

The word doing two jobs

Here is the conflation the whole launch quietly sits on, and it is not GitLab's invention. The industry talks about "the dependency graph of your system" as if it were one thing. It is two.

There is the symbol-and-SDLC graph. Its nodes are directories, files, the classes and functions defined in them, the symbols they import, and alongside those the merge requests, pipelines, deployments and vulnerabilities the platform tracks. Its edges are calls, imports, inheritance, and the lifecycle relationships between objects. This is the graph Orbit builds, and it is the graph that answers "who calls this function" and "which services does this CVE touch".

Then there is the artifact graph. Its nodes are the things your infrastructure is actually made of and shares between repositories. A base image. A Terraform module. A Helm chart. A reusable CI template. Its edges are the references that bind those things together across repos: a Dockerfile FROM line, a Terraform source block, a terraform_remote_state lookup, a Helm chart dependencies entry or a value reference, a GitLab CI include:project. Different nodes, different edges, a different parser surface entirely.

You do not have to take my word for which of those graphs Orbit is. Take the word of the customer GitLab chose to showcase. Compare the Market describe what they integrated as "a symbol graph", and every query they demonstrate is a code query: where is this function called, what inherits from this interface, what does changing this method signature affect. The node legend in their own diagram is directory, file, definition, imported symbol. That is the symbol layer, described precisely, by the customer in the launch. Nobody is hiding the ball here. Orbit is a symbol graph with the lifecycle bolted alongside it.

So Orbit answers blast radius at the symbol layer, change this signature and here are the callers, and at the SDLC layer, this CVE sits in these components owned by these teams. Both are real. Neither is the layer where a platform team's worst change lives.

Where the edges actually live for platform teams

Picture the change that actually keeps a platform team up at night. You bump a shared base image. Or you take a common Terraform module from v3 to v4 and tighten a variable along the way. Or you edit the values block on an umbrella Helm chart that nine services inherit from. The thing that breaks is not in the repository you are editing. It is three repos away, in a service owned by a team that has never read your module's changelog. And the edge that connects you to it was never a function call. It is a source block pinned to a tag. It was never in the code for a symbol graph to find. It only ever existed in the manifest.

This is the layer Orbit does not reach, and it is worth being precise about why, because it is not an oversight they will patch on Tuesday. Orbit's supported-language list is published, and it is general-purpose programming languages, the Pythons and Gos and TypeScripts. There is no HCL parser in it. No Dockerfile parser. No parser for chart manifests. The data model follows from that. It has first-class nodes for functions, files, merge requests, pipelines and vulnerabilities. It has no node for "this base image, consumed by these eleven repositories", because nothing in the indexing pipeline ever parsed a FROM line and resolved it across the group.

This is not laziness, it is a genuinely different problem. Building a symbol graph means running a Tree-sitter parse over source and reading out the definitions and references. That is well understood, and GitLab has done it properly. Building an artifact graph means parsing HCL to follow module source URLs, reading Dockerfiles to resolve base images back to the repositories that publish them, walking Helm value inheritance and chart dependencies, expanding CI include across projects, and then reconciling all of it across repositories that were never designed to know about each other. It is a different parser surface and a different resolution problem. It is, more or less, the entire thing Riftmap is, and it is the same line I have drawn before between symbol graphs and artifact graphs and shown in practice when finding every consumer of a GitLab CI template — or, on the GitHub side, every consumer of a reusable GitHub Actions workflow. Orbit being excellent does not move that line. If anything, it makes the line easier to see. I have since put numbers on it, measuring the split across two real organisations: the infrastructure share of cross-repo coupling ran from 38% to 99.75%, and not one edge was a code symbol — I counted every cross-repo edge in two real orgs. Widening the lens to nine public platform orgs and 1,297 repos, one in four repos turned out to be load-bearing for a sibling and the single most-depended-on repo at Grafana was a CI-workflow file with 188 dependents — exactly the artifact edge a symbol-and-SDLC graph has no node for.

Even on its own turf, the graph stops at the platform boundary

Set the layer question aside for a moment and there is still a wall, and it is structural rather than a matter of pricing. Orbit Remote is GitLab.com only. The lifecycle side streams out of GitLab by change-data-capture into a managed graph, and the code side is served over GitLab's own internal API. There is nowhere in that design for a repository GitLab does not host. Orbit Local exists, but it is a code-only graph of a single repository on your machine, not a picture of your organisation.

The trouble is that the organisations who feel cross-repo pain most acutely, the 50 to 300 repo polyrepo shops, are rarely tidy single-platform estates. They are GitHub with a bit of GitLab. Or GitHub with a self-managed GitLab for the regulated workloads. Or three acquisitions sitting on three different platforms with no intention of consolidating this year. The dependency that actually bites in that world is the one running from a GitHub application repository onto a base image published from a GitLab repository, and that is precisely the edge a GitLab-only graph cannot draw. Reading the edges from source, and reading them across GitHub and GitLab and Bitbucket alike, is not a feature you bolt onto a platform-native graph afterwards. It is a different starting point.

Two graphs, not a fight

I have come round to thinking Orbit is less a competitor than a very large, very well-funded proof that this category is real. For the symbol-and-SDLC layer, inside a GitLab shop, it is a good graph, and I would point people at it. The artifact layer is a different graph that answers a different question. Not "who calls this function" but "what breaks if I change this base image". The two do not compete. They stack.

And the useful part is that both are MCP servers. An agent reviewing an infrastructure change wants the symbol graph for the code in front of it and the artifact graph for the consequences it cannot see. Claude Code can call both in the same review. Orbit for the function being edited. Riftmap for the eleven repositories downstream of the image that function's service is built on. This was always the shape of it. The agent is a consumer of the graph underneath, and the only interesting question was ever which graph. The launch just made the answer sharper.

So here is where two days of reading actually landed me. The biggest player in the space shipped a dependency graph, reached for the words blast radius, and proved with a real customer that a structured graph beats letting a model guess. And it still does not parse a single FROM line. The layer where your worst change lives, the infrastructure your repositories quietly share but no symbol graph can see, is still unmapped. Parsed, not inferred. Auto-discovered, never catalogued. Read across every platform you actually run on, not just the one that happens to host the graph. Those turn out to be different gifts. Only one of them tells you what you are about to break. That parsed-versus-registered distinction is a category line of its own, which I pull apart against Port's model-it-by-hand approach in modeled graphs and parsed graphs.

A few questions, answered directly

What is GitLab Orbit?

GitLab Orbit is GitLab's knowledge graph of a software organisation, launched 10 June 2026 and in public beta for GitLab.com Premium and Ultimate. It indexes source code in around a dozen general-purpose programming languages together with the SDLC objects GitLab already stores, merge requests, pipelines, deployments, vulnerabilities and ownership, into one property graph you can query with a Cypher-like language, over MCP, over REST, or from the GitLab CLI. It ships in two shapes: Orbit Local, a single-binary CLI that builds a code-only graph of one repository on your machine, and Orbit Remote, the hosted version spanning a top-level GitLab.com group.

How much does GitLab Orbit cost, and which tier is it in?

There is no separate GitLab Orbit price or SKU; it is gated behind the GitLab tier you already pay for. Orbit Local, the single-binary CLI, is effectively free to run locally. Orbit Remote, the hosted group-wide graph, is in public beta for GitLab.com Premium and Ultimate — so its cost is the per-seat cost of those paid tiers, not a separate charge, and evaluating it adds nothing beyond seats you already hold. It is GitLab.com only, with no self-managed or Free-tier access. A public-beta price is a placeholder, and GitLab has not committed to general-availability pricing.

Does GitLab Orbit map infrastructure dependencies across repositories (Terraform, Helm, Docker)?

No. Orbit indexes source code in general-purpose programming languages and the SDLC objects GitLab already stores. Its published language list contains no HCL parser, no Dockerfile parser, and no parser for chart manifests, so it does not resolve a Terraform source block, a Dockerfile FROM line, or a Helm value reference into a cross-repo edge. It maps blast radius at the code-symbol and lifecycle layers, not at the infrastructure artifact layer.

Does GitLab Orbit work across GitHub, or only GitLab?

Only GitLab, and the limit is architectural rather than a question of pricing tier. Orbit Remote builds its graph from GitLab data streamed through GitLab's own internal services, so there is nowhere in the design for a repository GitLab does not host. Orbit Local can graph a single repository on your machine, but it is code-only and does not span an organisation. If your estate is GitHub, mixed, or self-managed, Orbit Remote cannot draw the edges between your repos.

What is the difference between a symbol graph and an artifact dependency graph?

A symbol graph indexes the things inside your code: files, the functions and classes defined in them, and the calls and imports between them. It answers "who calls this function". An artifact dependency graph indexes the things your repositories share at the infrastructure layer: base images, Terraform modules, Helm charts, CI templates, and the references that bind them across repos. It answers "what breaks if I change this base image". They are different graphs, built by different parsers, and blast radius on an infrastructure change needs the second one.

How to Find Every Consumer of Your GitLab CI Template

Daniel Westgaard — Thu, 11 Jun 2026 00:00:00 GMT

You maintain a shared GitLab CI template. You need to rename a job, change an input, or restructure the file. Which projects across your org include it? GitLab has been asked this question for nearly six years. Here's the paper trail, and the actual answer.

In October 2020, a platform engineer posted a question on the GitLab forum: we generated a lot of internal templates which others can include in their CI/CD pipelines. Is there a way to see how often a template is included in other projects?

The answer they got was that no API contains this data, and that they could try grepping the nginx and Workhorse access logs on their self-managed instance and aggregating the raw fetch counts with jq. Web server logs. That was the canonical answer to "who consumes my CI template" in 2020.

Browse the sidebar of that thread and you find its siblings. "Reporting on Template Usage/Adoption." "Tool to document CI Template includes." "Find out how many times my gitlab-ci file has been used." "Count the number of usages" predates the 2020 anchor thread by five months. Different years, same question, zero replies on every one of them. Nearly six years of template maintainers asking the reverse question into the void.

The forward question, how do I share CI config across projects, is one of the best-documented patterns in GitLab. The reverse question, who is consuming what I shared, has an answer so bad that grep-the-web-server-logs was a genuine improvement on the alternatives. This post is about the reverse question.

The scenario

Your platform team maintains a devops/ci-templates project. It started as one file. Now it's a small library: build templates, deploy templates, a security scanning include, maybe some shared rules and defaults. Other projects consume it the standard way:

# In some-service/.gitlab-ci.yml
include:
  - project: 'devops/ci-templates'
    ref: v2.4.0
    file:
      - '/templates/build-go.yml'
      - '/templates/deploy-k8s.yml'

Twenty projects adopted it. Then fifty. Then you stopped counting, because there is nothing in the product that counts for you.

Now you need to change it. Rename a job that other pipelines extends from. Change a variable the deploy template expects. Split one file into three. The question is the same one that comes up for every shared infrastructure artifact: which projects across our org include this template, at which ref, and which of them break when I merge?

The part that makes GitLab worse than GitHub here

If you've read the GitHub Actions edition of this series, you know reusable workflows have the same visibility problem. GitLab's version has a structural twist that makes it sharper.

In GitHub Actions, uses: requires a ref. Every caller pins to something, even if that something is @main. In GitLab CI, ref: on a project include is optional, and when it's omitted, the include resolves to the HEAD of the template project's default branch. Per the CI/CD YAML reference, that's documented behaviour, not an accident.

In practice, most templates in most orgs are consumed without a ref. Which means a merge to main in devops/ci-templates is not a release. It is an instant, org-wide deployment of CI configuration to every consumer that didn't pin. There is no rollout. There is no opt-in. The blast radius is the whole estate, and it detonates at merge time.

GitLab says this itself, in writing. The YAML reference now warns that including another project's CI configuration is, from a security perspective, similar to pulling a third-party dependency, and that no pipelines or notifications trigger when the other project's files change. Read that second clause again. The dependency is real, and it is silent. GitLab's own template development guide makes the maintainer-side version of the same point: changes to templates consumed via include can break pipelines for every project using them, which is why GitLab treats its own template changes as breaking changes deferred to major releases.

And GitLab has lived this at platform scale. The master to main default-branch rename broke CI templates with hardcoded refs. In a more recent merge request touching the security scanning templates, a GitLab engineer noted that template changes can prevent whole customer pipelines from starting, described setting up dashboards to monitor for it, and acknowledged that customer feedback would probably surface a problem before their own metrics did. That is the maintainer of the world's largest CI template library saying, candidly, that part of their blast-radius monitoring is waiting for users to complain. If GitLab's own platform team operates partially blind here, your devops/ci-templates repo is not an outlier. It's the norm.

Practitioners writing about this confirm the culture. A recent piece on versioning pipeline logic puts it plainly: an include pointing at main means every consumer inherits template changes immediately with no opt-in, manually pinning SHAs or tags across dozens of repos is labour nobody actually does, so teams ride main and hope. A dev.to author describes adopting git tags for their templates specifically so colleagues would stop fearing that a template change would break their release process. The fear is the default state. The unpinned include is the default configuration.

What existing tools give you (and where they stop)

I want to be fair to the options, because some of them are genuinely useful for parts of this.

GitLab code search

You can search for the template path across a group:

include "devops/ci-templates"

Basic search will find string matches in blobs. Advanced search does it better and faster, but it's a Premium/Ultimate feature, and on self-managed it requires you to stand up and operate the search infrastructure behind it, which a lot of instances simply haven't done.

Even where it works well, code search gives you matches, not answers. It doesn't extract the ref. It doesn't distinguish include: project: from a comment that happens to mention the path. It doesn't see the second hop: if your template is included by a wrapper template in another shared project, code search finds the wrapper, not the forty projects behind it. For a one-off audit it's a reasonable start. It is not a system.

The CI lint API

GitLab can show you the fully merged configuration for a single project, includes resolved, via the CI lint endpoint. This is genuinely good for the forward direction: "what does this project's pipeline actually consist of." But it's per-project, and it answers the wrong direction. To get the reverse view you'd have to call it for every project in the org and parse the results yourself, which brings us to the script people inevitably write.

The script

Enumerate every project via the API, fetch every .gitlab-ci.yml, parse the YAML, extract include: entries, filter for your template, extract refs, handle pagination and rate limits, run it on a schedule, store the results somewhere. Several teams have built exactly this. One platform engineer on r/devops described building an in-house mapper that treats shared CI includes as a first-class dependency edge alongside Terraform sources and Dockerfile FROM lines. The fact that this keeps getting independently built is the strongest evidence there is that the question matters. It is also a project you now own, with all the corner cases below as your backlog.

Renovate

Renovate's GitLab CI include managers can detect project includes and open MRs to bump the ref. As with Terraform modules and GitHub Actions, Renovate implicitly knows who consumes what, because it's configured per consumer. But it's an updater, not a mapper. There's no org-level "show me every project that includes this template" view, and it has nothing to say about the unpinned includes, which are the majority and the most dangerous.

CI/CD Catalog analytics

This one deserves real credit, because GitLab has started answering the question. With GitLab 19.0, the CI/CD Catalog gained a Components Analytics view: usage counts for your published components across all tiers, and on Ultimate, a drill-down showing exactly which projects included a component in a pipeline over the last 30 days and which version each one is on. GitLab's own framing of the problem in the work item is almost word-for-word the premise of this series: component maintainers previously had no way to identify which projects used their component or which versions, making breaking changes and deprecations hard to coordinate.

So the gap is closing. But look at what the closure covers. It covers include:component, resources published to the CI/CD Catalog. It is usage-event-based, derived from pipelines that actually ran recently, rather than parsed from what repos declare. And the per-project answer is Ultimate-only. The include:project template fleets, which is what nearly every self-managed enterprise estate actually runs on, including the devops/ci-templates repo in the scenario above, are not in scope. If you migrated your entire template library to Catalog components and bought Ultimate, GitLab now answers a 30-day usage version of the question. For everyone else, the 2020 forum thread is still the state of the art.

(GitLab also announced Orbit this week, a context graph across code, work items, pipelines and deployments for AI agents to query. It's aimed at agent context rather than artifact consumers, and it's early beta, so I gave it the proper look in a separate post.)

Why this is harder than it looks

A naive grep for the template path undercounts and overcounts at the same time, because include is not one mechanism. It's five.

include:
  - local: '/ci/lint.yml'                       # same repo, not a cross-project edge
  - project: 'devops/ci-templates'              # the core case
    ref: v2.4.0
    file: '/templates/build-go.yml'
  - remote: 'https://gitlab.example.com/devops/ci-templates/-/raw/main/templates/scan.yml'
  - template: 'Jobs/SAST.gitlab-ci.yml'         # GitLab-shipped, not yours
  - component: $CI_SERVER_FQDN/devops/components/build-go@2.4.0

Each form has different semantics, and a consumer-tracking system has to treat them differently. local includes are same-repo plumbing, not a dependency on you. template includes point at GitLab's shipped library, also not you. project includes are the core case. remote includes are sneaky: they can point at the exact same file in the exact same template repo, just over raw HTTP, and a search for include: project: misses them entirely. component includes wrap the project path in $CI_SERVER_FQDN variables and version suffixes that a literal string match won't survive.

Nested includes are where the script dies. Template repos include other template repos. Your deploy-k8s.yml might itself include: project: a shared rules file from devops/ci-base. GitLab resolves these chains at pipeline time, up to 150 includes deep, with the added wrinkle that nested includes execute without context as a public user. If you change ci-base, the projects that break include projects that have never heard of ci-base. They included a template that included you. Finding the direct consumers is a string search. Finding the transitive ones requires a graph.

Includes are not the only cross-project CI edge. Multi-project pipelines via trigger: project: create a dependency on another project's pipeline. Parent-child pipelines via trigger: include: can pull child pipeline definitions from other projects. Cross-project needs: [{project, job, ref}] creates a dependency on another project's job artifacts. None of these are includes, all of them break when the upstream project changes, and a consumer map that only parses include: misses them.

The breaking surface is loosely typed. With spec:inputs, templates and components now have something like a declared interface, which is genuine progress. But the installed base of include:project templates communicates through variables, extends targets, and job names. Rename a job that downstream pipelines extends from and there is no compile-time error. There's a pipeline that fails to start, in someone else's project, at whatever time they next push.

What the full answer requires

To reliably answer "who consumes this CI template," you need a system that:

Scans every project in the group hierarchy, parsing .gitlab-ci.yml plus the template files that template repos themselves carry, in templates/ and .gitlab/ci/, because that's where the nested chain starts
Extracts every cross-project edge type: include:project with its ref and file list, include:remote URLs resolved back to the repos they point at, include:component references with the host variables and version suffixes stripped, plus trigger: and cross-project needs: edges
Knows which forms to ignore: local includes and GitLab-shipped template: includes are noise in a consumer map, not signal
Reconstructs nested chains so a change to a base template surfaces the transitive consumers, not just the wrapper repo that includes it directly
Records the ref each consumer declares, including its absence, so "who is riding an unpinned include" is a queryable fact rather than a suspicion
Stays current through rescans of what the repos declare, not 30-day windows of what happened to run
Makes the result one query: every consumer of devops/ci-templates, with the file and line where the include lives

This is one of the specific problems Riftmap is built to solve. It scans a GitLab (or GitHub) org and parses every project's CI configuration, emitting distinct edge types for project includes, remote includes, catalog components, multi-project triggers and cross-project needs, while deliberately skipping local and GitLab-shipped template includes. Template repos' own templates/*.yml and .gitlab/ci/*.yml files are parsed too, so when a template includes another template, that edge is in the graph, and the transitive chain from a base template to its end consumers is reconstructed across the org. Each edge carries the declared ref as a version constraint, or its absence, plus file and line provenance. Parsed from what the repos declare, not inferred from what recently ran.

The result: before you merge that job rename into devops/ci-templates, you open the graph, click the template repo, and read the consumer list. You know who breaks. You know who's pinned to a tag and has time, and who's riding an unpinned include and gets your change at merge time. You know who to notify, instead of finding out who you should have notified.

For the cross-platform treatment of that merge moment itself — why a shared CI change is really two deployments at once, instant to the unpinned consumers and silent to the pinned ones, and why CI has no deprecation signal to soften either — see You changed the shared CI template. Half the org got it instantly. The other half will never see it.

The dependency GitLab told you about

Here's the closing thought. GitLab's own documentation says that including another project's CI configuration is like pulling a third-party dependency. Take that sentence seriously and follow it to its conclusion. We have norms for third-party dependencies. We pin them. We track who uses them. We check the blast radius before publishing a breaking change. Somewhere along the way, shared CI templates became the one class of dependency where the ecosystem's answer to "who depends on this?" was grep your web server logs, and we collectively decided that was fine.

It was never fine. It was just invisible. The template that fifty projects include without a ref is the highest-leverage, least-observed dependency in your org. Treat it like one.

This is the sixth post in the Find Every Consumer series. Previous posts cover Docker base images, Terraform modules, GitHub Actions workflows, Helm charts and Go modules.

If this is a problem your platform team deals with, I'd be interested to hear how you're solving it today. You can find more at riftmap.dev or reach me at hello@riftmap.dev.

About Riftmap

Riftmap maps cross-repo dependencies across your entire GitLab or GitHub organisation — Terraform, Docker, CI templates, Helm, and more. One read-only token. No YAML to maintain.

Is Backstage worth it? The real question is whether anyone will use it

Daniel Westgaard — Wed, 10 Jun 2026 00:00:00 GMT

The "is Backstage worth it" debate is always about cost: how many engineers, how many months, how much it runs per developer. The person who runs Backstage at Spotify will tell you that's not where it dies.

At BackstageCon, and again in an interview with The New Stack, Helen Greul, who heads Backstage engineering at Spotify, gave a number that should reframe the whole question. Outside Spotify, the average Backstage adoption rate is stuck at around 10%. Inside Spotify it is 99%. And the reason she gave for the gap was not that teams cannot afford the setup. It was that adopters often do not get past the proof of concept, because they never pinned down the problem their developers actually had.

Read that twice. The person responsible for Backstage at the company that invented it is telling you the tool usually fails after the hard engineering is done, not before.

That is worth sitting with, because almost every "is Backstage worth it" debate I see is an argument about the part Greul says is not the problem. Someone quotes the community estimate of around $150,000 per 20 developers in total cost of ownership. Someone else points out it takes two or three full-time engineers and the better part of a year to stand up a real catalog. Both numbers are accurate. Neither one answers the question, because cost tells you what it takes to build Backstage, and worth is decided by whether anyone uses what you built.

The question everyone asks, and the one that decides it

"Worth it" is a ratio. Value returned over what it costs you. The cost side is well documented and not in dispute. The value side is the part that quietly determines the outcome, and value from a developer portal is not delivered at launch. It accrues every time an engineer opens the portal instead of asking in Slack, trusts what it tells them, and acts on it. That only keeps happening if the portal keeps being right.

So the honest worth-it question is not "can we afford to build it". Plenty of teams can. It is "once we build it, will it stay true enough that people keep coming back". The 10% number is the industry's answer to that question, aggregated across thousands of organisations, and it is not flattering. The build is the table stakes. The trust loop is the game.

This reframe also explains a finding that looks paradoxical otherwise. Roadie's 2025 State of Backstage Report, drawn from 105 active practitioners, found that 70% of the companies that describe themselves as very happy with Backstage still dedicate at least three full-time engineers to maintaining it. The happy teams are not the ones who escaped the cost. They are the ones who pay it indefinitely and consider it worth paying, because for them the loop holds. The question is what makes it hold for them and break for everyone else.

Why Spotify gets 99% and you might get 10%

The most useful answer I have found comes from a Backstage founder describing, in an InfoQ talk, why Spotify's catalog stayed relevant when so many copies of it rot. The discipline was simple to state and hard to sustain. The metadata for each component lives in that component's repository, and ownership of the metadata is handed to the team that owns the component. The catalog is not a thing a central team curates. It is a thing every team is on the hook for, next to the code, as part of shipping.

That is the engine under the 99%. When the data lives where the work happens and the people doing the work own it, the data stays current, so the portal stays trustworthy, so people keep using it, so keeping it current stays worth their while. The loop reinforces itself. Break any link and it runs the other way. The data drifts, the portal gets a reputation for being wrong, people stop checking it, and the team maintaining it is now grooming a graph that nobody trusts. That is what 10% looks like from the inside. Not a portal nobody built. A portal nobody believes.

I want to be fair here, because this is where the critics get lazy. When the loop holds, Backstage is genuinely excellent, and the market reflects that. It holds roughly 89% of the internal-developer-portal market as of early 2026, serving thousands of organisations and millions of developers, and the data from teams who run it well is mostly positive. The plugin ecosystem is unmatched and the CNCF governance means it will outlast any single vendor. Backstage is not a bad tool. It is a tool whose worth is unusually sensitive to one variable, and that variable is whether the data inside it maintains itself or has to be maintained.

The diagnostic: does this fact maintain itself, or does someone have to?

This gives you a way to predict your own outcome before you spend a quarter finding out. Take the things you want to put in the portal, and for each one ask a single question. Does this fact stay current as a byproduct of how engineers already work, or does it require a separate act of maintenance that nobody is specifically paid to perform?

Some facts pass easily. Who owns a service. Who is on call. Where the runbook is. What the tech-docs say. The scorecard criteria your platform team defined. These originate with people, they change rarely, and a human decides them on purpose. The catalog model fits them well, because the catalog is the source of truth for that kind of data. There is no other copy to drift away from. For these jobs a portal, Backstage or a managed one, is a good buy, and I would not argue otherwise.

Other facts fail the test immediately, and they fail it in a specific and predictable place. The cross-repo infrastructure dependencies. Which repositories consume a shared Terraform module, via its source block. Which services are built on a base image, via a Dockerfile FROM. Which charts depend on which, via Chart.yaml. Which pipelines pull a shared template, via a .gitlab-ci.yml include. These already exist as declarations in the manifests. The catalog entry that mirrors them is a second copy of a fact the repo already states. Engineers must edit the manifest to ship. Nothing forces them to edit the catalog to match. So the manifest and the catalog entry diverge on the first commit after someone stops being diligent, and on a real team that is roughly immediately. I went through the mechanics of this in detail in the catalog maintenance trap, and the architectural version of the argument is in modeled graphs and parsed graphs.

The diagnostic, then, is a ratio of its own. The more of your intended value sits in the first bucket, the more Backstage is worth it. The more of it sits in the second, the lower your adoption ceiling, no matter how well you build it, because you are asking people to hand-maintain a copy of facts their commits already changed, and they will not, and the graph will be wrong exactly when it matters.

The change that proves it

Here is when it matters, made concrete, because this is the scene that sends teams looking in the first place.

A platform engineer needs to bump a base image, or change a shared Terraform module, the kind of change that fans out across dozens of repos that no single person has in their head. Maybe the person who did have it in their head is leaving in three weeks, and the dependency view in the portal was supposed to be how that knowledge survived their departure. This is the highest-stakes thing a portal's dependency graph is meant to do. Tell you what breaks before you ship.

And it is the exact moment the catalog model lets you down, because the graph is only as current as the last engineer who remembered to update YAML that nothing required them to update. So at the decision point where being wrong is most expensive, you are consulting the data you should trust least. A portal you cannot trust when the change is risky is not a safety net. It is a comfort blanket with holes you find out about during the incident. That is the worth question with the abstraction stripped off. The maintenance cost everyone complains about does not even buy you the one answer you most needed it for.

When it is genuinely worth it

So let me be precise about when the answer is yes, because it often is.

If you have a platform team with real frontend capacity, an organisation large enough that the per-developer cost amortises, a genuine need to own and extend the portal, and, most importantly, the organisational will to enforce the metadata-in-the-repo discipline that makes Spotify's catalog stay true, then Backstage is a defensible and often excellent choice. The teams in Roadie's "very happy" 70% are real. They earned it by paying the standing cost on purpose and putting the data where the work is.

And if you are small, the most honest take comes from a Backstage vendor. Roadie themselves say plainly that not every organisation needs Backstage, and that below a certain size adopting it is over-engineering. The mistake is almost never "adopted Backstage". The mistake is adopting any catalog-model system, Backstage or a commercial successor, for the second-bucket data, and then spending finite organisational willpower keeping humans in sync with facts their repositories already declare. That spend is the maintenance everyone complains about, and for that category of data it does not buy accuracy. It buys a graph that is right up to whenever someone last cared.

So, is it worth it?

After enough of these conversations I have stopped thinking of worth as a property of Backstage at all. It is a property of the match between Backstage's data model and the data you intend to put in it. For the facts humans register on purpose, the match is good, and for the right organisation the portal earns its keep handsomely. For the cross-repo infrastructure dependencies, the match is wrong at the root, and no amount of budget, frontend talent, or vendor support fixes a model that asks people to register a copy of what they already declared. You will land in the 10% for that part of the portal specifically, and you will have paid for the privilege.

If the reason you are evaluating Backstage is some version of "we need to know what breaks across our infrastructure before we change it, and we need that to still be true after the person who knows leaves", then the worth-it calculation is not close, and not because Backstage is bad. It is because that particular fact should never be maintained by hand in the first place.

That last job is the one I build for. Riftmap connects to a GitLab or GitHub organisation with one read-only token and parses the infrastructure dependency edges directly from the manifests that already declare them, across Terraform, Docker, Helm, Kubernetes, CI templates, and more. There is no catalog to maintain because there is no second copy. The graph cannot drift from the source, because the source is the input, which means it is still right at the moment you bump the base image or touch the shared module and need to know what is downstream. It is not a developer portal and it will not become one. If the value you are after is golden paths, scorecards, and ownership pages, use Backstage or a managed portal, and I mapped the honest options by job in Backstage alternatives in 2026. If the value you are after is knowing what breaks before you ship, that is a different tool, and the free tier maps your whole org, up to 250 repos.

FAQ

Is Backstage worth it for a small team?

Usually not, and you do not have to take a competitor's word for it: Roadie, which sells managed Backstage, says plainly that below a certain size adopting an internal developer portal is over-engineering. Backstage earns its cost in organisations large enough that the per-developer overhead amortises and complex enough that the sprawl is a real problem. For a small team, lighter tools for documentation and ownership usually return more for far less standing cost.

Why is Backstage adoption so low outside Spotify?

Spotify's head of Backstage engineering has put the average external adoption rate at around 10%, against 99% internally, and attributed the gap to teams not getting past the proof of concept because they had not pinned down the developer problem they were solving. The deeper mechanism is trust: Spotify keeps its catalog accurate by storing metadata in each repo and making the owning team responsible for it, so the data stays current and people keep using it. Where that discipline does not hold, the data drifts, the portal loses credibility, and usage collapses regardless of how well it was built.

Is Backstage worth it just for the dependency graph?

No. The dependency graph is the part of a portal that ages worst, because cross-repo infrastructure dependencies are facts about source files (Terraform source blocks, Dockerfile FROM lines, Helm chart dependencies, CI includes) that change with every commit, while the catalog copy of them only changes when a human remembers to edit YAML. You end up maintaining a hand-registered copy that is wrong exactly when a risky change makes you need it. For that job a parsed dependency graph, read straight from the manifests, is the right architecture, not a catalog you keep in sync by hand.

Backstage alternatives in 2026: first ask why you wanted Backstage

Daniel Westgaard — Sun, 07 Jun 2026 00:00:00 GMT

Every "Backstage alternatives" roundup lists the same five portals. None of them asks the question that decides which alternative is right: what job sent you looking in the first place?

A senior platform engineer at a Nordic consultancy summarised his Backstage evaluation to me in one sentence: the cost of setting it up and keeping it maintained was bigger than what they got back. He is not an outlier. I have heard the same verdict, in nearly the same words, from engineers across r/devops threads, client engagements, and direct conversations. The team evaluates Backstage seriously, sometimes runs a proof of concept, and walks away. Then they type "Backstage alternatives" into a search box, and the search results take over.

Go read those results. As of mid-2026, every page that ranks is a vendor roundup, and every roundup follows the same script. Port lists alternatives and Port is the best one. Cortex lists alternatives and Cortex is the most comprehensive. OpsLevel lists alternatives and OpsLevel is the fully managed answer. The supporting cast rotates between Roadie, Mia-Platform, Configure8, Rely.io, and Atlassian Compass, but the structure never changes. Backstage is hard, here are five portals that are easier, ours is first.

Here is the thing none of those pages will tell you, because their business depends on not telling you. "Backstage alternatives" is not one search. It is at least three different searches wearing the same query, and the right alternative depends entirely on which one is yours. Two of the three are well served by the portal vendors in those roundups. The third is not served by any of them, because the portals inherit the exact property that made you walk away from Backstage.

This post is the triage the roundups skip. I will try to be fair to every tool in it, including Backstage, because the engineers reading this can smell a strawman from the next time zone. And I will be upfront that I build a tool that fits exactly one of the three jobs, and explicitly does not fit the other two.

What Backstage actually is, honestly

Backstage is an open-source framework for building internal developer portals, created at Spotify and open-sourced in March 2020. It remains a CNCF Incubating project with one of the largest contributor communities in the foundation. It pioneered the developer-portal category, and most of the commercial portals in those roundups exist because Backstage proved the demand first.

The origin story matters more than people give it credit for. Backstage began as an internal Spotify project called System Z, built so that engineers in a fast-growing organisation could understand ownership, dependencies, and versions across an exploding service landscape. Hold onto that word "dependencies". It comes back later.

The criticisms are equally well established, and I will not pretend they are mine. Backstage is a framework, not a product. You clone it, stand up a PostgreSQL database, configure authentication, and start writing or installing plugins, most of which are community-maintained without vendor support. The estimates for what this costs are public and not in dispute. The community site internaldeveloperplatform.org puts the true cost of ownership at around $150,000 per 20 developers, a figure that Port and OpsLevel both cite in their own marketing. Cortex's roundup says most organisations need two or three full-time engineers for six months or more just to stand up a basic service catalog. Other practitioners put production-readiness at six to twelve months. Gartner has noted that organisations mistakenly believe Backstage is a ready-to-use portal, and that the rude awakening during implementation leads to projects being put on hold or abandoned.

So far, the roundups and I agree. Backstage is genuinely expensive to run. Where we part ways is on what that means. The roundup logic is: Backstage is expensive, therefore buy a cheaper portal. The actual logic should be: Backstage is expensive, therefore figure out which part of it you wanted, because you might be able to buy just that part, and for one specific part, no portal sells it.

The three searches hiding inside one query

When a team types "Backstage alternatives", they arrived there from one of three places. The triage question is which one.

Job one: you want what a portal does

Some teams want the portal itself. Golden-path templates for scaffolding new services. Scorecards that track whether services have runbooks, SLOs, and passing security scans. A single pane of glass for ownership, on-call, and documentation. Self-service actions that let a developer spin up an environment without filing a ticket.

If this is your job, the roundups are right and I have nothing contrarian to offer. The commercial portals are real products built by serious teams, and the honest comparison between them comes down to taste and scale. Port gives you a flexible data model you configure visually rather than in code, which suits organisations whose workflows do not fit standard patterns. Cortex leans hardest into scorecards and engineering standards, which suits organisations whose pain is "we have 400 services and no idea which ones meet our bar". OpsLevel is deliberately opinionated, which suits teams that want the vendor to have made the workflow decisions already. All three will get you to a working portal in weeks instead of quarters, and all three cost real money at scale, which is the trade you are making.

What I want you to notice is what these products have in common with Backstage underneath the better onboarding. They are all catalog-model systems. Each one maintains a registry of entities, services, teams, resources, and the relationships between them, and that registry is populated by some mix of integrations and humans registering things. That is the right architecture for the portal job. Ownership is something a human decides. A runbook link is something a human writes down. Scorecards evaluate criteria a human defined. The catalog model fits because the data genuinely originates with people.

Job two: you want Backstage itself, without operating it

Some teams evaluated Backstage and concluded the product was right but the operational burden was not. They want the open-source ecosystem, the plugin library, the CNCF governance, and they want someone else to run it.

This path matured significantly in the last year. Spotify Portal for Backstage went GA in October 2025 as a fully managed, no-code SaaS version of Backstage operated by Spotify itself, with setup wizards in place of the configuration work that used to consume the first quarter. Roadie has offered managed Backstage for years and remains the established independent option, handling hosting, upgrades, and the GitHub rate-limit problems that bite self-hosters.

If your evaluation said yes to Backstage's model and no to its operations, this is your category, and it is a perfectly defensible choice. You keep the ecosystem and shed the toil. I have no quarrel with it.

But notice, again, what does not change. Managed Backstage is still Backstage. The Software Catalog is still populated by catalog-info.yaml files in your repos, and the relationships in it, including the dependsOn entries, are still whatever a human last wrote there. Spotify operating the infrastructure does not update your YAML when an engineer changes a Terraform module source. The hosting was never the part that went stale.

Job three: you wanted to see what depends on what

Now the third search, the one I keep meeting in the wild.

A meaningful fraction of teams never wanted golden paths or scorecards. They reached for Backstage because of the dependency graph. They wanted the answer to "what breaks if I change this", or "which repos consume this base image", or "the engineer who understood how these sixty repos fit together is leaving in three weeks". They saw the Software Catalog's dependency view, recognised the thing they were missing, and adopted a developer portal to get it. That is not a misreading of Backstage. It is the original System Z brief: ownership, dependencies, versions. It is also the kind of question a parsed graph answers concretely rather than in the abstract: when I scanned all 208 kubernetes-sigs repos, 153 of them turned out to import a single shared module — the sort of fan-in a stale catalog never shows you.

For this job, the catalog model is not the solution with some maintenance cost attached. The maintenance cost is the failure mode. I wrote about this pattern at length in the catalog maintenance trap, but the short version goes like this. A dependency entry in catalog-info.yaml is a second, hand-registered copy of a fact your repos already declare. The original declaration is the Terraform source block, the Dockerfile FROM line, the go.mod require, the .gitlab-ci.yml include, the Helm Chart.yaml dependency. Engineers must edit those files to ship. Nothing forces them to edit the catalog YAML to match, so within weeks the manifest and the catalog entry diverge, and the graph in the portal becomes documentation that was supposed to be authoritative. Which is worse than no graph, because people make blast-radius decisions on the assumption it is current. This is the structural weakness of a registered dependency: unlike a declared edge the build re-reads on every run, nothing executes a catalog, so it drifts at exactly the rate attention wanders.

Here is the part the roundups structurally cannot say. Switching portal vendors does not escape this. Port's marketing makes the point against its rivals better than I could: it criticises YAML-based catalogs for creating developer overhead and not updating in real time from the source of truth, eroding trust and adoption. That criticism is correct, and it applies to the entire category whenever the data in question is the dependency graph, because dependencies are facts about source files, and source files change with every commit. A portal can ingest from integrations, and the good ones do for cloud resources and Kubernetes objects. But the cross-repo dependency edges your infrastructure actually runs on, module sources, image references, CI includes, chart dependencies, live in manifests that no portal in those roundups parses.

So if job three is your job, the honest answer to "what is the best Backstage alternative" is: not a portal. Any portal. The alternative is a different architecture entirely, one where the graph is parsed from the declarations that already exist instead of modelled from entries you ask humans to register. I went deep on that architectural distinction in modeled graphs and parsed graphs; the one-line version is that a parsed graph cannot go stale relative to the source, because the source is the input.

The triage, in one table

Why you wanted Backstage	Right category	Representative options
Golden paths, scaffolding, scorecards, ownership, self-service	Commercial developer portal	Port, Cortex, OpsLevel
Backstage's model and ecosystem, minus the operations	Managed Backstage	Spotify Portal, Roadie
Dependency visibility and blast radius across repos	Parsed dependency graph	Riftmap, or build your own parser
Keeping third-party dependencies up to date	Automated update tooling	Renovate, Dependabot
Code search and symbol navigation across repos	Code intelligence	Sourcegraph

I added the last two rows because they are the other jobs I see mislabelled as portal problems. Renovate and Dependabot keep versions current but tell you nothing about who consumes what. Sourcegraph's symbol graph is genuinely excellent at code-level navigation and stops at the infrastructure boundary, a distinction I unpacked in symbol graphs and artifact graphs. Neither is a Backstage alternative, but both get evaluated as one, which tells you how muddled this category's vocabulary is. The muddle gained its biggest entrant in June, when GitLab shipped Orbit, a group-wide symbol-and-SDLC graph. I read everything GitLab Orbit actually shipped, and it stops at the same infrastructure boundary as Sourcegraph: no HCL, no Dockerfiles, no artifact edges.

And a row I deliberately left out: "build your own portal from scratch". Teams do it. Canva did, then migrated off it, and the engineer who ran that migration described the homegrown portal as something they got value from while using it, not wasted work. That is the right way to think about sunk platform investment generally, including a Backstage proof of concept that taught you which job you actually have.

The alternatives, compared head to head

The triage table above sorts tools by the job that sent you looking. This one puts the named alternatives side by side on the attributes that actually decide the choice — including the two Spotify options people mean when they search "Spotify Backstage alternatives" (Spotify Portal, the managed Backstage SaaS, and Backstage itself, the Spotify-born framework). The column that matters most for job three is the fourth one: whether the cross-repo dependency graph stays current on its own, or drifts until someone re-registers it by hand.

Tool	What it is	Graph model	Spans GitHub + GitLab	Cross-repo dependency graph stays current?	Pricing model
Backstage	Open-source portal framework (Spotify-born)	Registered catalog (`catalog-info.yaml`)	Any host, via plugins	No — `dependsOn` is hand-registered and drifts	Free framework; high TCO (~$150k per 20 devs)
Spotify Portal	Managed Backstage SaaS, run by Spotify	Registered catalog	Any host, via plugins	No — same catalog YAML, hosted	Commercial SaaS
Roadie	Managed Backstage (independent)	Registered catalog	Any host, via plugins	No — same catalog YAML, hosted	Commercial SaaS
Port	Commercial developer portal	Configured catalog + integrations	Any host, via integrations	Partial — integrations refresh cloud/K8s entities, not manifest cross-repo edges	Commercial; free tier
Cortex	Commercial developer portal	Registered catalog + scorecards	Any host, via integrations	Partial — same integration limit	Commercial
OpsLevel	Commercial developer portal	Registered catalog + integrations	Any host, via integrations	Partial — same integration limit	Commercial
Riftmap	Parsed cross-repo dependency graph	Parsed from manifests (no catalog)	Yes — GitHub + GitLab from a read-only token	Yes — re-parsed from source, so it cannot drift relative to the repos	Free tier (whole org, up to 250 repos); paid tiers

Read the table by column, not by row. On portal features — templates, scorecards, self-service — Port, Cortex, OpsLevel, and both Backstage flavours are the real field, and the triage table above tells you which fits. On the dependency-graph column, every catalog-model tool lands on "no" or "partial" for the same structural reason: a registered edge is a hand-kept copy of a fact the repos already declare, so it is only ever as current as the last person who remembered to update it. Riftmap is the one row that answers "yes", and it is the only row that is not a portal — which is the whole point of the third search.

Where Backstage genuinely wins

I want to be precise about when the answer to "Backstage alternatives" is "none, use Backstage", because that answer is real.

If you have a platform team with frontend capacity, a genuine need to own and extend the portal, and an organisation large enough that the per-developer cost of the framework amortises, Backstage is a defensible choice that thousands of organisations have made work. The plugin ecosystem is unmatched. The CNCF governance means it will outlive any single vendor's funding cycle. And the things humans should register on purpose, ownership, on-call, runbooks, tech docs, are things Backstage handles well precisely because the catalog model fits them.

The mistake is not adopting Backstage. The mistake is adopting any catalog-model system, Backstage or its commercial successors, for the dependency graph, and then spending organisational willpower trying to keep humans updating a hand-registered copy of facts the repos already state. That spend is the maintenance cost everyone complains about, and it does not buy accuracy. It buys a graph that is accurate to within whenever someone last cared.

The question underneath the query

The roundups argue about which portal. After two years of conversations with teams who walked away from Backstage, I think the better argument is about which job. The portal jobs are well served, by the portals and by managed Backstage, and the vendors fighting over that SERP have earned their places in it. The dependency-visibility job is the one that query quietly smuggles in, and it is the one place where every option in every roundup shares Backstage's actual weakness rather than fixing it.

If the sentence that sent you searching was some version of "we wanted to know what breaks when we change things, and the catalog could not keep up", then you were never shopping for a portal. You were shopping for a graph, and the graph already exists, written across your Terraform sources, Dockerfiles, CI includes, chart dependencies, and module files. The work is parsing it, not registering it again by hand.

That parsing is what I build. Riftmap connects to a GitLab or GitHub org with a read-only token, parses the dependency declarations across twelve ecosystems, Terraform, Docker, Helm, Kubernetes, CI templates, Go, npm, Python, Ansible, and more, and serves the resulting graph two ways: a blast-radius UI for engineers, and a JSON API for coding agents that need cross-repo context at planning time. There is no catalog to maintain because there is no catalog. If your job is one of the other two, use the table above with my blessing; Riftmap is not a portal and will not become one. If your job is the third one, the free tier maps your whole org, up to 250 repos and the first scan takes about ninety seconds, which is less time than reading one more roundup.

FAQ

What is the best alternative to Backstage?

It depends on which job sent you looking. If you want golden paths, scaffolding, scorecards, and self-service, a commercial developer portal like Port, Cortex, or OpsLevel is the right category. If you want Backstage's model and plugin ecosystem without operating it, managed Backstage — Spotify Portal or Roadie — fits. If you wanted dependency visibility and blast radius across repos, no portal solves that well, because the dependency graph is a fact about source files; a parsed dependency graph like Riftmap reads it from the manifests instead of asking humans to register it again.

What are the alternatives to Spotify Backstage?

"Spotify Backstage" is two products people conflate. Backstage is the open-source framework Spotify created and open-sourced in 2020; Spotify Portal is Spotify's own fully managed SaaS version of it, GA since October 2025. Alternatives depend on which one you mean and why. If Spotify Portal's managed model appeals but you want an independent operator, Roadie offers managed Backstage too. If you want the portal capabilities without Backstage's plugin architecture, Port, Cortex, and OpsLevel are the commercial portals. And if what drew you to Backstage was its dependency view — knowing what breaks when you change something across repos — no Backstage flavour, managed or not, keeps that graph current, because it lives in hand-registered catalog-info.yaml; a parsed dependency graph like Riftmap reads it from the manifests instead. The comparison table above puts all of these side by side.

Why do teams abandon Backstage?

The most common reason is that the cost of standing it up and keeping it maintained exceeds the value returned. Backstage is a framework, not a finished product: the community site internaldeveloperplatform.org estimates a total cost of ownership around $150,000 per 20 developers, and roundups note most organisations need two to three full-time engineers for six months or more just to stand up a basic service catalog. The dependency graph in particular goes stale, because catalog YAML is a hand-registered copy of facts the repos already state, and nothing forces engineers to keep it in sync.

Is Backstage still worth using in 2026?

Yes, for the right team. If you have a platform team with frontend capacity, a genuine need to own and extend the portal, and an organisation large enough that the per-developer cost amortises, Backstage is a defensible choice with an unmatched plugin ecosystem and CNCF governance. The mistake is not adopting Backstage — it is adopting any catalog-model system, Backstage or its commercial successors, as the dependency graph, and then spending organisational willpower keeping humans updating facts the repos already declare. The deep-dive on this question, with Spotify's own external-adoption figure of around 10% and a diagnostic for predicting your own outcome before you commit, is in is Backstage worth it?.

How to give GitHub Copilot cross-repo context today

Daniel Westgaard — Sat, 06 Jun 2026 00:00:00 GMT

In March 2026, someone filed a feature request on GitHub Community that I have thought about more than any product announcement from that month. The setup is two repositories. A web app and an orders-service it consumes. The web app calls the service's endpoints, depends on its DTOs, and has to stay aligned with every route rename, payload change, and validation rule. The request walks through what Copilot cannot do across that boundary: it cannot reason about contracts defined in the other repo, cannot detect when the frontend calls an endpoint that no longer exists, cannot coordinate one change across both sides. It ends with two questions. Is this on the roadmap, and are there recommended best practices to approximate this behaviour today?

GitHub has not answered. I eventually left a reply in the thread myself, because the second question deserved one, and this post is the long version of that reply.

The honest answer is more useful than "wait for the roadmap". As of June 2026 there are three working ways to give GitHub Copilot context across repositories. All three are real, all three ship today, and all three have a ceiling that is worth knowing about before you invest in one. Underneath all three sits the same unanswered question, and that question is the part I actually want to get to.

What Copilot can see today, precisely

It is worth being precise here, because the answer is different for each Copilot surface, and it changes fast enough that this paragraph carries a date.

Copilot Chat in VS Code sees the workspace you have open. One folder open means one repo's worth of context. Copilot Chat on github.com is scoped to a single repository, or to a Space, which we will get to. And the Copilot cloud agent, the one you hand an issue and get a pull request back from, runs in its own environment scoped to the single repository where the task was opened, holding a repository-scoped GITHUB_TOKEN that cannot read its siblings.

None of this is an oversight. It is a permissions model doing its job. Which is why every working approach to cross-repo context is a way of routing around that model deliberately: widen the workspace, curate a context set, or hand the agent extra credentials. Those are the three approaches, in that order.

Approach 1: a multi-root workspace in VS Code

The cheapest path, and the one most teams should try first. VS Code supports multi-root workspaces: a .code-workspace file listing several repository folders that open together in one window.

{
  "folders": [
    { "path": "web-app" },
    { "path": "orders-service" },
    { "path": "platform-context" }
  ]
}

Copilot Chat indexes across every folder in the workspace, and #codebase searches all of them. For the web-app and orders-service case this is genuinely transformative: both sides of the contract are in the window, so "does the frontend call anything I just renamed" becomes an answerable question.

The pattern has grown a refinement that is worth copying. Several teams now pair the workspace with repository custom instructions, a .github/copilot-instructions.md per repo, and the more advanced version adds a dedicated context-only repository to the workspace. Arinco published a detailed writeup of running this across a 15-plus-repo platform this week: a repo containing nothing but Copilot customisation files, added as a workspace folder, whose shared instructions file acts as a routing table describing the architecture and pointing at each repo's own conventions.

That is the strongest version of the approach, so let me be fair to it before drawing the line. At two to five tightly coupled repos, with someone who cares keeping the instructions current, this works, and it costs an afternoon.

It stops in three ways, and they compound.

First, the workspace does not load itself into the model's context. The agent searches and greps it, every session, and that cost is paid again every session. Meta's published numbers put a graph lookup for "what depends on X" at roughly 200 tokens against roughly 6,000 for answering the same question by exploration, a 30x difference I went through in detail in the virtual monorepo post. Grep over a workspace is O(N) in workspace size, and the workspace only ever grows.

Second, the instructions file decays. It is a hand-written map of how the system fits together, and the system keeps moving after the map is written. The research on hand-written context files is sobering, marginal gains at meaningfully higher inference cost, and Meta's engineering team named the underlying problem in one line: "context that decays is worse than no context". A confident agent navigating by a stale map does not feel stale. It feels fast, right up until the change lands.

Third, somebody chose which folders go in that .code-workspace file, and they chose from memory. Hold that thought.

Approach 2: Copilot Spaces

The native option, and the one I see teams miss because it lives on github.com rather than in the editor. Copilot Spaces let you assemble a curated context set, including entire repositories, plural, alongside specific files and folders, pull requests, issues, uploaded documents, and free-text notes, then chat with Copilot grounded in exactly that set. You can attach custom instructions, share the space with your organisation, and the GitHub-based sources stay synced as the code changes. Any Copilot licence can use it.

Credit where due: this is zero infrastructure, it is the only genuinely multi-repo Copilot surface GitHub ships today, and for a team that lives on github.com it is the lowest-friction answer on this list. A space holding web-app, orders-service, and the API contract files is a real improvement for onboarding questions, contract questions, and "explain how these fit together" questions.

The ceiling is in how it retrieves. When you attach a whole repository, Copilot searches within it for relevant content rather than loading it, and GitHub's own guidance is to curate the specific files that matter because that is what produces the best answers. So the quality of a space is the quality of its curation. Sources are grounded in the latest state of the main branch, which means in-flight work on branches is invisible to it. And a space is a chat surface: it informs the human asking, it does not gate a deploy or coordinate a change. It answers questions about the repos somebody remembered to add.

That phrase again. Somebody curated the source list, by hand, from memory.

Approach 3: give the cloud agent reach with MCP

The first two approaches help you, working interactively. The third helps the autonomous path, the cloud agent that takes an issue and opens a pull request, which is exactly the surface the original feature request was filed against.

The agent's environment is configured through a copilot-setup-steps.yml workflow file, and the community workaround for its single-repo scoping is now well documented: configure an MCP server in the agent's environment, typically the GitHub MCP server itself, supplied with a fine-grained personal access token stored as an Actions secret, scoped read-only to the sibling repositories it needs. The agent working in web-app can then search and read orders-service mid-task.

This works, and for teams committed to the cloud agent it is currently the only way to get cross-repo awareness into it at all. It is also the approach with the most operational surface: a PAT to mint, rotate, and audit, a workflow file to maintain per repo, and a security review conversation about why an autonomous agent holds credentials to repositories beyond the one it is changing.

And it has the limit I keep writing about, because it is the limit underneath this whole product category: this is access, not structure. I made the full argument in Repo access was never the hard part, so here it is in two sentences. The agent can now read orders-service while editing web-app. Nothing tells it that it should, or that a third repo consumes the same contract and is not in its token's scope at all.

The question all three approaches skip

Look at what the three approaches have in common. A .code-workspace file with a folders list. A Space with a sources list. A PAT scoped to a repository list. Every one of them answers the question "how do I put more repositories in front of Copilot", and every one of them quietly delegates the harder question back to you: which repositories?

That list is a hand-maintained model of what depends on what. Maintaining it has a name on this blog, because platform teams have been running this exact experiment for years with service catalogs: it is the catalog maintenance trap. The list is accurate the day it is written, it drifts the moment the system changes, and nothing tells you it drifted. A workspace missing the repo that consumes your contract does not error. It just gives the agent a confident, complete-looking view of an incomplete world, which is the precise failure mode where a wrong map beats no map for damage done.

What surprised me, going through the tooling landscape for this post, is that nothing else in the stack answers the question either. Renovate understands dependency manifests more deeply than almost any tool in existence, one repository at a time. Asked directly whether cross-repository dependency detection was planned, a maintainer's answer this May was unambiguous: "Renovate only operates on a per-repository basis", with no plans to change. Dependabot has the same shape. The tools that read your manifests every single day read them one repo at a time, and then forget what they saw. The platform vendors are starting to move, though inside their own walls: GitLab Orbit, shipped in June, is a queryable symbol-and-SDLC graph for agents, and it is GitLab-only, so a GitHub estate running Copilot gets nothing from it, and the artifact edges stay unmapped either way.

So the "which repositories" question goes unanswered by default. But here is the thing: for most of the edges that matter, the answer is already written down.

I will concede the exception first, because it is real. The rawest version of the web-app to orders-service edge, a fetch against a service URL, is declared nowhere. No parser will ever find it, and anyone who tells you otherwise is inferring it from names and hoping. But the moment a team formalises that contract, a shared types package, a client SDK, a published schema, and at any scale beyond two repos they do, the edge lands in a manifest. A package.json dependency on the contracts package. A go.mod require. And the edges that carry the rest of the org are declared the same way: Terraform source blocks pointing at module repos, Dockerfile FROM lines pointing at base images built elsewhere, Helm Chart.yaml dependencies, GitLab CI includes and reusable GitHub Actions workflow uses: references. I have spent a whole series walking those edges one ecosystem at a time. They are deterministic. Parsed, not inferred. The dependency graph that should be writing your workspace file already exists in your org's manifests, unassembled.

Feeding the graph back into Copilot

This is the part that turns the argument into a setup, so let me be concrete. A queryable cross-repo dependency graph does not replace the three approaches above. It feeds them, in three places.

It writes the lists. The folders array in the workspace file, the source list in the Space, the repo scope on the agent's PAT: generate them from a dependents query instead of from memory. "Every repo that consumes the orders-service contract package" is one API call, and when the graph changes, the lists change with it. The curation problem does not get solved by curating harder. It gets solved by deriving.

It is a tool call during the task. In agent mode, Copilot can call out to tools, and the graph as an HTTP API means a planning step can ask "who depends on what I am about to change" before the first edit. With Riftmap that is two calls:

# Resolve the working tree to a node in the graph
REPO_ID=$(curl -s \
  "https://api.riftmap.dev/api/v1/repositories/lookup?url=https://github.com/myorg/orders-service" \
  -H "X-API-Key: $RIFTMAP_API_KEY" | jq -r '.id')

# One round-trip: dependencies, dependents, artifacts
curl -s "https://api.riftmap.dev/api/v1/repositories/$REPO_ID/context" \
  -H "X-API-Key: $RIFTMAP_API_KEY"

For the cloud agent, the same pattern works with the API key as an Actions secret in the agent's environment. The agent integration guide covers the full call pattern, and one rule from it matters more than the rest: every response carries last_scanned_at and last_activity_at, and if the repo has been pushed to since it was last scanned, the agent treats the graph as stale and says so. That is the "context that decays" problem handled as a contract rather than a hope.

It is the same map at review time. On a pull request touching a shared component, CI queries the transitive impact and posts the consumer list as a comment, so the human reviewing the agent's change is checking it against the same structural account the agent planned with, instead of against memory.

That last point is the architecture I think this whole category lands on, and you do not need my product to adopt it. Mabl built their own coordination graph by hand and runs agents across 100-plus repos on top of it. The pattern is the point: a parsed, queryable graph underneath, and Copilot, or whichever agent you run, consuming it. Riftmap is the version of that substrate you do not have to build, auto-discovered from one read-only token across GitLab or GitHub, with the API above on every tier.

So, to answer the question the feature request actually asked. The best practice for approximating cross-repo context in Copilot today is one of the three approaches above, chosen by which Copilot surface you live in. The best practice for making any of them survive contact with a changing org is to stop hand-maintaining the repository lists they all depend on, and derive them from the graph your manifests already declare.

Every one of these approaches ends in a list of repositories that somebody has to get right. You can maintain that list, or you can derive it. Only one of those is still correct three months from now.

Monorepo vs polyrepo: the debate is measuring the wrong thing

Daniel Westgaard — Fri, 05 Jun 2026 00:00:00 GMT

The monorepo vs polyrepo argument is old enough that Buildkite was comparing it to the Vim and Emacs wars back in 2024. It should have been settled, or at least gone quiet. Instead, in the space of six months, an AI coding vendor re-litigated it for the agent era, a benchmark firm published PR cycle-time data across hundreds of organisations, and half the platform engineering threads I read found their way back to it. Something pulled the question out of retirement. I think the something is worth naming, because it is not really about repositories at all.

I maintain a product whose entire reason to exist is that most organisations run polyrepos, so I want to be upfront about where I sit before arguing anything. Riftmap parses cross-repo dependencies. If everyone migrated to a monorepo tomorrow, a good part of my roadmap would evaporate. Read what follows with that in mind, and check the sources, all of which are linked.

With that declared: I think both camps in this debate are arguing about a proxy. The real variable underneath, the one that decides whether your team ships confidently or plays dependency archaeology at 2am, is something the standard pros-and-cons lists never name. This post walks the honest trade-offs first, because they are real and you deserve a straight answer to the question you searched for. Then it gets to the variable.

What each side buys you

A monorepo is one repository holding many projects. A polyrepo (or multi-repo) setup gives each project, service, or module its own repository. Both are proven at every scale that matters: Google and Meta run famous monorepos, Amazon and Netflix run famous polyrepos, and none of them are wrong.

The monorepo's case

The strongest monorepo argument has always been atomic cross-project change. Uber's iOS team moved to a monorepo largely for this: when an API contract and all of its clients live in one repo, a breaking change is one commit, one review, one revert path. No choreographed pull requests across six repositories, no compatibility matrix, no deployment ordering.

You also get unified dependency versions. One lockfile discipline, one toolchain, one place where "which version of the logging library are we on" has a single answer. And, the part this post will keep returning to, you get a build graph. Bazel, Nx, Pants, and Turborepo all maintain an explicit graph of what depends on what, because they need it to know what to rebuild. That graph is a by-product of the architecture. It comes for free, by construction.

The cost is that the build system becomes infrastructure. Past a certain size you cannot build everything on every change, so you need change detection, remote caching, and a team that owns the machinery. Airbnb's Bazel migration is the honest writeup of what that takes. There is also a coordination cost that no build tool fixes: shared standards, shared review culture, and consensus across every team in the repo.

The data backs the "it depends on operational maturity" framing. Faros.ai's benchmark analysis from March 2026, drawn from PR data across many organisations, found that monorepo teams show markedly more variable PR cycle times than polyrepo teams, with heavy tails at the 90th percentile where some organisations blow past ten days on worst-case PRs. Their read is that well-engineered monorepo infrastructure can match polyrepo performance, but the infrastructure has to keep evolving with repository scale, and when it lags, cycle times absorb the difference. A monorepo is a bet that you will keep funding that evolution.

The polyrepo's case

Polyrepos buy autonomy. Each repository has its own CI pipeline, its own release cadence, its own ownership boundary that maps cleanly onto a team. A service can deploy twenty times a day while its neighbour ships monthly, and neither blocks the other. Different stacks can coexist without one build tool having to understand all of them. Deprecating a service means archiving a repo, not excavating a directory.

The same Faros data shows the flip side of the monorepo's variance: polyrepo teams sit in a tighter, more predictable cycle-time range. Small repos are comprehensible, reviews are scoped, and nothing in repo A's CI can make repo B's pipeline slower.

The cost is that everything cross-cutting gets harder. A change spanning three services is three PRs with a coordination problem attached. Version skew creeps in quietly until service A and service B disagree about a shared library in a way that only shows up in production. Standardising anything across fifty repos, security scanning, CI conventions, dependency policy, is a campaign rather than a commit.

And there is one more cost, the one the listicles file under "harder dependency management" and move past in a sentence. In a polyrepo, nobody can answer "what depends on this" without going looking. That sentence is doing more work than the debate gives it credit for, and it is where this post is headed.

The trade-offs at a glance

Dimension	Monorepo	Polyrepo
Cross-project changes	Atomic, one commit	Coordinated PRs across repos
Dependency versions	Unified by tooling	Skew unless actively managed
Team autonomy	Shared standards required	Independent by default
Deploy cadence	Decoupled with effort	Decoupled by default
Build infrastructure	Serious investment (Bazel, Nx)	Per-repo, simple, duplicated
PR cycle times (Faros, 2026)	Higher variance, heavy P90 tails	Tighter, more predictable
"What depends on this?"	Build graph answers it	Nobody answers it
Ownership boundaries	Directory conventions	Repository boundaries

If you came here for the short answer to "which should we choose": tightly coupled projects with coordinated releases and an organisation willing to fund build infrastructure point to a monorepo. Loosely coupled services, autonomous teams, and varied stacks point to polyrepo. Most organisations past a certain size end up hybrid regardless. That is the honest conventional answer, and it is fine as far as it goes.

But look at the table again. Seven of those rows are preferences. One of them is a capability.

The variable the debate never names

Here is the quiet conflation at the centre of this debate. We argue about where code should live, as if co-location were the prize. It is not. The prize that co-location happens to deliver is a queryable dependency graph.

In a Bazel monorepo, "what breaks if I change this library" is a command:

bazel query "rdeps(//..., //libs/auth)"

In an Nx workspace it is nx graph, or nx affected scoped to a change. The answer is exact, it is derived from declared build targets, and it is current as of the last commit, because the build system cannot function without it. This is the monorepo's one structural advantage that survives every counterargument: not the co-location itself, but the graph the build tooling is forced to maintain on top of it.

Now run the same question in a 200-repo polyrepo estate. The dependencies are all still there. They are declared, in writing, in the manifests: Terraform source blocks pointing at module repos, Dockerfile FROM lines pulling a shared base image, go.mod requires on an internal module, package.json dependencies on an internal npm package, GitLab CI include statements pulling a central template, Helm charts referenced by release pipelines. The graph exists. Every edge of it is sitting in a file in version control. What does not exist is any system that reads those files and holds the answer. So the question gets answered by grep across checkouts, by asking the senior engineer who was there when the module was written, or by shipping the change and watching what pages.

This is the reframe I would push on anyone choosing between the two: the monorepo vs polyrepo decision is, underneath, a decision about whether your dependency graph is declared to a machine or remembered by people. A monorepo makes the graph declared, by construction, as a side effect of the build system. A polyrepo leaves it implicit, scattered across manifests that no single tool reads. Almost everything painful about polyrepos at scale, the coordination overhead, the version skew, the 2am archaeology, traces back to that one missing capability. I wrote about the blast-radius version of this problem and the tooling landscape around it at length, so I will not re-make those arguments here. The point for this post is narrower: once you see the graph as the variable, the debate changes shape, because repo count turns out to be only one way to influence it. And for a large part of your estate, it is a way you were never offered.

Infrastructure never got a vote

Read any monorepo vs polyrepo piece and notice what the examples are made of. Application services. An auth service, an API gateway, some clients. The tooling named is Nx, Turborepo, pnpm workspaces, Bazel. The entire debate is shaped like application code, and mostly like TypeScript.

Infrastructure code lives in a different world, and that world is polyrepo by ecosystem convention rather than by anyone's choice.

Start with Terraform. The public registry requires one module per repository, named terraform-<PROVIDER>-<NAME>. It is a hard format requirement; the registry will not accept anything else. Private registries inherit the convention. Practitioners have been asking HashiCorp to allow multiple modules per repo since 2020, precisely because maintaining a repository per module is real overhead, and the answer has not changed. If your organisation has forty internal Terraform modules, the ecosystem's defaults have already decided you have forty repos.

The same gravity acts on the rest of the infrastructure estate. Shared Helm charts get their own repos so they can be versioned and published to a chart registry. CI templates get centralised into a repo that dozens of pipelines pull in via GitLab CI include or reusable GitHub Actions workflow calls, because that is the mechanism the CI systems provide. Base images live in their own repos with their own build pipelines because the registry push is the unit of release. None of these were monorepo-vs-polyrepo decisions. They were defaults that arrived bundled with the tools.

Two consequences follow. First, the infrastructure layer is where the polyrepo's missing graph hurts most, because infrastructure components are the highest fan-in nodes in the estate. A Terraform module sourced by forty repos, a base image pulled by every service, a CI template included by eighty pipelines. When I scanned all 208 repositories in the kubernetes-sigs organisation, a single module, sigs.k8s.io/yaml, turned out to be imported by 153 of them. In the Prometheus organisation, 25 of 56 repos import client_golang. Those are healthy, well-run open-source orgs, polyrepo by design, and the concentration is the normal shape of a polyrepo estate, not a pathology. The question is only whether anyone can see it.

Second, and this is the part the migration guides skip: moving your application code to a monorepo does not repatriate the infrastructure layer. The Terraform modules stay where the registry wants them. The CI templates stay where the include mechanism reaches them. The base images stay where the push pipeline lives. You can spend a year of political capital consolidating services into one repository and still wake up with the highest-blast-radius components of your system scattered across repos whose dependency graph nothing reads. The monorepo migration solves the graph problem for the code that moved, and only for the code that moved.

So when the conventional advice says "high interdependency points to a monorepo", it is giving you guidance that the most interdependent part of your stack is structurally unable to take.

What AI agents change, and what they don't

The reason this debate came out of retirement is AI coding agents, so let's take that argument seriously, because the strongest version of it is genuinely strong.

Augment Code's piece on the question makes the case well: an assistant that can see the auth service, the gateway, and the clients in one context window reasons about a cross-service change in a way that an assistant grepping five separate repositories cannot. Large context windows weaken the old polyrepo argument that services are easier to understand in isolation, because the AI can hold the interactions. Their conclusion is that AI shifts the calculation toward monorepos. The observation underneath is correct, and I want to be fair to it before pushing back: agents do perform better with cross-repo visibility, and the teams running agents at scale keep converging on exactly that diagnosis.

The push-back is that the argument conflates two different things: what the agent can see and what the agent can query. Visibility is access. Access is not structure.

Stripe is the cleanest evidence, because Stripe is the maximum case for "monorepo plus large model". Their internal agent system, Minions, was merging over 1,300 AI-written pull requests a week as of February 2026, against a real monorepo of hundreds of millions of lines. And their published architecture does not dump that monorepo into the model. It cannot; in their own words, a global context dump "would overflow any model's window". Instead they built directory-scoped rule files that attach as the agent traverses the tree, and an MCP server exposing nearly 500 internal tools the agent queries for structure it does not hold in context. The team with the world's most complete co-location still had to build the queryable layer on top. Co-location alone did not deliver it.

Meta's number makes the same point from the cost side. In their tribal-knowledge engine writeup, answering "what depends on X" by graph lookup costs around 200 tokens; answering it by letting the agent explore costs around 6,000. A 30x difference that no context-window increase closes, because it is an architecture gap, not a capacity gap. And the Gloaguen et al. study from ETH Zurich showed that the hand-written context files teams reach for instead, the CLAUDE.md system maps, buy a marginal +4% agent success rate at +19% inference cost. Prose descriptions of structure decay and do not scale; I went deep on that failure mode in the virtual monorepo post.

So the AI-era version of this debate is not "which layout lets the model see more text". It is "which layout gives the agent a structure it can query instead of reconstruct". A monorepo with a real build graph is one good answer: the agent calls bazel query and gets blast radius in one tool call. A polyrepo with a parsed cross-repo graph is the equivalent answer for everyone else. A polyrepo with neither, or a monorepo whose build graph stops at the application layer while the Terraform modules sit outside it, leaves the agent exploring, and exploring is the expensive, fuzzy mode.

The agents did not change the answer. They raised the price of not having it, because an agent makes cross-repo changes at a rate no human team ever did, and change failure rates are already absorbing the difference.

How to actually choose

The framework I would use, with the graph as the explicit variable rather than the silent one.

Choose a monorepo when the graph can be complete

If your projects are tightly coupled, your releases are coordinated, your stack is uniform enough for one build tool, and your organisation will fund the build infrastructure as a product, a monorepo is a strong choice, and the build graph is the most underrated part of what you are buying. Go in with the Faros caveat in view: the performance of a monorepo tracks the maturity of its infrastructure, and the investment is recurring, not one-off. And check the graph's edges honestly. If your Terraform, Helm, and CI templates will still live outside the repo, know that your build graph will be blind exactly where the blast radius is largest.

Stay polyrepo when autonomy is the constraint that binds

If your teams ship on independent cadences, your stacks are heterogeneous, ownership maps to repositories, or external contributors and open-source boundaries are involved, polyrepo is not a legacy state to apologise for. It is the layout the Faros data shows delivering predictable cycle times, and it is the layout your infrastructure ecosystem mandates anyway. The cost you are accepting is the undeclared graph, and the mistake is accepting it silently instead of pricing it.

Hybrid is normal, not indecision

Core tightly-coupled services in one repo, periphery and infrastructure in their own repos, is where most large organisations land, usually without announcing it. It is a reasonable equilibrium. It also means the graph question does not go away, because the cross-repo edges between the monorepo and everything around it are precisely the ones no build tool covers.

The fourth option the listicles never give you

Most teams reading this are not choosing. They have 100 or 300 repos, a migration would cost a year of politics, and the conventional framing leaves them with "polyrepo, and suffer" as the default. The option that framing hides: keep the polyrepo, and recover the one structural thing the monorepo would have given you. The graph is already written down in your manifests. The source blocks, the FROM lines, the go.mod requires, the CI includes are all declarations, and declarations can be parsed. Parsed, not inferred: read deterministically from the files, the way a build system reads its targets, rather than guessed from embeddings or filenames. Do that across the estate and "what depends on this" becomes a query in a polyrepo the same way bazel query makes it one in a monorepo. That is the substrate I have been arguing for across this whole blog, and it is the option that turns the debate from a migration decision into a tooling decision.

This is, full disclosure repeated, the thing Riftmap builds: a parsed cross-repo dependency graph over your existing GitLab or GitHub organisation, from one read-only token, with the kubernetes-sigs and Prometheus scans above as public examples of the output. You can also build it yourself; teams like Mabl have, and the tooling survey covers the landscape honestly. The point of this post is not the product. The point is that the capability, not the repo count, was always the thing being argued about.

The question underneath the question

Monorepo vs polyrepo asks where your code should live. After two decades of debate, the trade-offs are well mapped and mostly come down to what your organisation is willing to operate. But the question underneath has a sharper edge: when something changes, can you ask your system what breaks, or do you have to remember? A monorepo is one way to make the graph something you ask. It is not the only way, it stops at the build tool's borders, and for the infrastructure half of your estate it was never on the table. Choose your repo layout for your teams. Then make sure the graph is declared to a machine either way, because that, not the number of repositories, is the thing the debate was always measuring.

FAQ

What is the difference between a monorepo and a polyrepo?

A monorepo is one repository holding many projects, services, or modules. A polyrepo (or multi-repo) setup gives each project its own repository. Both are proven at every scale: Google and Meta run famous monorepos, Amazon and Netflix run famous polyrepos. The difference that actually decides outcomes is not co-location itself but whether your dependency graph is declared to a machine — a monorepo's build system maintains a queryable graph by construction, while a polyrepo leaves the same graph implicit in manifests no single tool reads.

Is a monorepo or polyrepo better for AI coding agents?

Neither layout wins automatically. AI agents do reason better with cross-repo visibility, but visibility is access, not structure. What an agent needs is a dependency graph it can query rather than reconstruct. A monorepo with a real build graph provides one — the agent calls bazel query and gets blast radius in a tool call; a polyrepo with a parsed cross-repo graph provides the equivalent. Stripe's Minions system, running against a giant monorepo, still had to build directory-scoped rules and an MCP server of nearly 500 queryable tools, because co-location alone did not deliver agent-usable structure.

Can infrastructure code like Terraform modules and Helm charts move into a monorepo?

Largely no. Infrastructure code is polyrepo by ecosystem convention, not by choice. The Terraform registry requires one module per repository in the terraform-<PROVIDER>-<NAME> format; Helm charts, CI templates, and base images each live in their own repos because that is the unit of release the tooling provides. Moving application code into a monorepo does not repatriate them — and they are the highest fan-in, highest-blast-radius components in most estates, so a monorepo's build graph stays blind exactly where it matters most.

How do you answer "what depends on this?" in a polyrepo?

The dependency graph already exists in your manifests: Terraform source blocks, Dockerfile FROM lines, go.mod requires, and CI include statements are all declarations sitting in version control. What is missing is a system that reads them and holds the answer. Parsing those declarations across the estate — deterministically, rather than inferring from embeddings or filenames — turns "what depends on this" into a query in a polyrepo the same way bazel query makes it one in a monorepo. That recovers the capability a monorepo provides as a by-product, without a migration.

Sources referenced

Buildkite, Monorepo vs. polyrepo: How to choose — buildkite.com, March 2024
Faros.ai, Monorepo vs Polyrepo: What the PR Benchmark Data Actually Shows — faros.ai/blog, March 2026
Augment Code, Monorepo vs Polyrepo: AI's New Rules for Repo Architecture — augmentcode.com/learn, updated January 2026
Uber Engineering, Building the new iOS monorepo — uber.com/blog
Airbnb Engineering, Migrating Airbnb's JVM monorepo to Bazel — medium.com/airbnb-engineering
HashiCorp, Publish modules to the Terraform registry — developer.hashicorp.com
hashicorp/terraform issue #26586, Allow multiple modules from the same repo — github.com, open since 2020
Engineering at Meta, How Meta used AI to map tribal knowledge in large-scale data pipelines — engineering.fb.com, April 2026
Signadot, Coding Agents Are Only as Good as the Signals You Feed Them — thenewstack.io, April 2026
Gloaguen et al., ETH Zurich and LogicStar.ai, Do Context Files Help Coding Agents? — arxiv.org/abs/2602.11988, February 2026
Joel Parker Henderson, monorepo-vs-polyrepo — github.com
Riftmap, You don't need a virtual monorepo. You need a graph. — riftmap.dev/blog, May 2026
Riftmap, What 208 kubernetes-sigs repos actually depend on — riftmap.dev/blog, May 2026
Riftmap, What 56 Prometheus repos actually depend on — riftmap.dev/blog, April 2026

Appendix: structured summary

Claim: The monorepo vs polyrepo debate argues about a proxy. The variable that decides outcomes is whether the organisation's dependency graph is declared to a machine or remembered by people. A monorepo delivers a queryable graph as a by-product of its build system (Bazel rdeps, nx graph); a polyrepo leaves the same graph implicit in manifests that no single tool reads. Infrastructure code (Terraform modules, Helm charts, CI templates, base images) is polyrepo by ecosystem convention, cannot follow an application-code monorepo migration, and is where fan-in, and therefore blast radius, concentrates.

Definitions: A monorepo is one repository containing many projects. A polyrepo gives each project or module its own repository. Both are proven at all scales.

Evidence:

Faros.ai (March 2026): monorepo teams show higher variance in PR cycle times with heavy P90 tails; polyrepo teams sit in a tighter, more predictable range. Monorepo performance tracks investment in build infrastructure.
HashiCorp's public Terraform registry requires one module per repository in the terraform-<PROVIDER>-<NAME> format; practitioners have requested multi-module repos since 2020 (hashicorp/terraform #26586) without a change.
Riftmap org scans: 153 of 208 kubernetes-sigs repos import sigs.k8s.io/yaml; 25 of 56 Prometheus repos import client_golang. High fan-in is the normal shape of a polyrepo estate.
Stripe Minions (1,300+ AI-written merged PRs/week against a monorepo of hundreds of millions of lines) does not use a global context dump; it uses directory-scoped rules and an MCP server exposing ~500 queryable tools. Co-location alone did not deliver agent-usable structure.
Meta: "what depends on X" costs ~200 tokens as a graph lookup vs ~6,000 by agent exploration, a 30x architecture gap.
Gloaguen et al. (arXiv:2602.11988): hand-written context files improve agent success +4% at +19% inference cost; they do not substitute for queryable structure.

Decision framework: Choose a monorepo when coupling is tight, releases are coordinated, and the organisation will fund build infrastructure as a recurring product. Stay polyrepo when team autonomy, heterogeneous stacks, or ecosystem conventions dominate. Hybrid is the common equilibrium. The fourth option, missing from conventional comparisons: keep the polyrepo and recover the monorepo's structural advantage by parsing the dependency graph already declared in manifests (Terraform source blocks, Dockerfile FROM lines, go.mod requires, CI includes), making "what depends on this" a query rather than an excavation.

Audience: Platform engineers, DevOps/SRE, and engineering leaders weighing repository architecture, especially teams running AI coding agents across multiple repositories or maintaining shared infrastructure components.

The CRA's 24-hour clock is a cross-repo question. Your SBOM answers a different one.

Daniel Westgaard — Tue, 02 Jun 2026 00:00:00 GMT

It is a Tuesday in late September 2026. A maintainer publishes a fix for an actively exploited vulnerability in a base image your platform team maintains: company/base-runtime. Somewhere in a Slack channel a security engineer asks the question the next twenty-four hours turn on. Not "what is inside base-runtime". Your SBOM scanner answered that months ago and the component is right there in the inventory. The question is the other one: "which of the products we have placed on the EU market actually ship this image, and at which tag?" That question is not in any SBOM you currently generate. It is a cross-repo question, and the clock is already running.

A note on what this post is, and isn't

This is not a compliance guide, and I am not a lawyer. There are good CRA compliance guides written by people who are, and I link to several below. This is an engineering post about a structural mismatch: the shape of the artifact the regulation asks you to keep, versus the shape of the question the regulation's timelines force you to answer under pressure.

The argument is narrow. A Software Bill of Materials is a vertical inventory: the components inside one product, down through its dependency tree. The Cyber Resilience Act's reporting clock, when it starts ticking, asks a horizontal question: across every repository in your organisation, which products ship the affected component, and at which version. Those are different graphs. The SBOM is necessary and the regulation is right to mandate it. It is just not sufficient for the question the 24-hour deadline actually asks, and the missing piece is not a better SBOM. It is the cross-repo dependency graph that tells you where each SBOM entry propagates.

Riftmap does not generate CRA-format SBOMs today. That work is on the roadmap, and I will be explicit about where the line currently sits rather than imply the product does something it does not. What Riftmap builds right now is the horizontal graph, the part that answers "which repos ship this", and that turns out to be the part the SBOM tooling category structurally does not produce.

If you are a platform lead or a CISO at a European manufacturer reading about September 2026 reporting deadlines, the practical takeaway is this: budget for SBOM generation, yes, but understand that generating SBOMs and answering "where is this component deployed across our estate" are two projects, not one.

The two questions the regulation forces together

The Cyber Resilience Act entered into force on 10 December 2024. Two dates matter for engineering planning. From 11 September 2026, manufacturers must report actively exploited vulnerabilities and severe incidents through ENISA's single reporting platform, with an early warning inside 24 hours, a full notification inside 72 hours, and a final report no later than 14 days after a corrective measure is available. From 11 December 2027, the full set of obligations applies, including the SBOM requirement that sits in the technical documentation.

Most of the public attention has gone to the SBOM mandate, and the mandate itself is modest in scope. Annex I, Part II(1) requires manufacturers to draw up a software bill of materials "in a commonly used and machine-readable format covering at least the top-level dependencies of the product." That is the legal floor: top-level dependencies, machine-readable, retained as documentation a market surveillance authority may request. The SBOM tooling category already clears this floor comfortably. Syft, Trivy, cdxgen, and the rest produce CycloneDX or SPDX output that lists components and their transitive trees inside an artifact. The SBOM is, for most teams, a solved generation problem.

The reporting clock is the part that is not solved, and it asks a different question.

When an actively exploited vulnerability lands in a component you ship, the 24-hour early warning does not ask "what is inside product X." It assumes you already know that. It asks, in effect, "which of your products with digital elements are affected, and what is the scope of the exposure." For a single product with one SBOM, that is a lookup. For a manufacturer shipping dozens of products that share internal base images, shared Terraform modules, common Helm charts, and reusable CI workflows, it is a fan-out problem across the whole estate. The exploited component is one node. The set of products that ship it is the answer, and that set is spread across every repository that consumes the node directly or transitively.

That is a cross-repo dependency question. It is the question this blog has been about since the first post. The CRA simply attached a 24-hour deadline and a fine of up to €15 million or 2.5% of global turnover to getting it wrong.

Why the SBOM does not answer it

Here is the part that trips up the budgeting conversation. A team hears "the CRA wants SBOMs" and "the CRA has a 24-hour reporting clock" and assumes the SBOM is the thing that answers the clock. It is not, and the reason is in the shape of the artifact.

An SBOM is scoped to a product. It is the inventory of components that go into one shippable thing: one container image, one application build, one firmware blob. CycloneDX and SPDX both model this as a tree: the product at the root, direct dependencies below it, transitive dependencies below those. The tooling that generates it is build-time or filesystem-scoped on purpose. Syft scans an image or a directory. Trivy scans a target. The output is faithful to one artifact and says nothing about the others.

So when the exploited component is in a shared base image, the SBOM of that base image tells you what is inside the base image. It does not tell you which application images were built FROM it, in which repositories, at which tags. Each of those downstream products has its own SBOM, and the component appears in each of those too, but only if those SBOMs were generated, retained, indexed, and queryable as a set, with the base-image relationship preserved as a resolved edge rather than a string. In practice that index does not exist as a by-product of running an SBOM generator. The SBOM generators do not build it, and they are explicit that infrastructure relationships are out of scope.

The tooling draws the line itself

You do not have to take my word for the scope boundary. The SBOM and scanning tools say it themselves. Grype's own documentation is blunt about it: it is a vulnerability scanner and nothing more, and if you need Terraform, CloudFormation, or Kubernetes manifest analysis, you need a separate tool. Trivy does scan IaC, but for misconfigurations: it tells you a security group is too open, not which repositories consume the module that defines it. Checkov runs on infrastructure code to catch policy violations within a configuration. None of these tools resolves the cross-repo artifact relationship: this base image is consumed by those eight application repos, four of which float to the new tag on next build and four of which are pinned behind.

The category split is the same one I wrote about in Symbol graphs and artifact graphs. SBOM generators inventory what is inside an artifact. They do not build the graph of which artifacts consume which other artifacts across an organisation, because that graph requires a parser estate that understands FROM company/base:${TAG}, source = "git::...?ref=v3.2.0", uses: company/actions/deploy@v2, and the registry and git resolution behind each of them. That is artifact-graph work, and it is structurally outside what a component inventory produces.

What the 24-hour clock actually asks for

Walk through the incident concretely, because the gap is clearest under time pressure.

A CVE is published for company/base-runtime and there is evidence of active exploitation in the wild. The CRA clock starts when you become aware. Inside 24 hours you owe ENISA an early warning. To write it, you need to know the scope: which products with digital elements that you have placed on the EU market are affected.

With the standard SBOM pipeline, you have an inventory per product, somewhere: in a registry, in an artifact store, in Dependency-Track if you run it. To answer the scope question you would need every product's SBOM, indexed together, with the base-image edge resolved so that "ships base-runtime" is a query rather than a grep. Most teams do not have this. What they have is the base image's own SBOM, a CI system that built the downstreams, and a frantic afternoon of grep -r "base-runtime" across repositories followed by manual reading of each Dockerfile to work out whether the tag in question is actually the one in production after build-arg substitution.

The grep finds the files. It does not resolve the answer. Which FROM lines pin the affected tag directly, which use ${BASE_TAG} resolved from a build arg in a separate workflow file, which inherit it transitively through an intermediate internal base image that is itself built FROM company/base-runtime. None of that comes out of a text search. It comes out of a parser that reads the Dockerfile, finds the default, reads the build invocation to see if it is overridden, and follows the intermediate-image chain. That is exactly the resolution work a cross-repo artifact graph does once, ahead of time, so that during the incident the scope query is a lookup instead of an investigation.

The shape of the answer you need

The early-warning notification needs the scope of affected products. The 14-day final report needs the remediation status: which products have been patched, which are pending, which are out of scope because the affected code path is not reachable. Both are queries against the same horizontal graph:

Which repositories consume company/base-runtime directly?
Which consume it transitively through an internal wrapper image?
Of those, which pin the affected tag versus float to it on next build?
For each affected product, what is the remediation state once the fixed tag is published?

A component inventory does not have these answers because it was never scoped to ask them. A cross-repo dependency graph is built to. This is not a knock on SBOMs. It is the observation that the regulation mandates one artifact (the vertical inventory) and its reporting clock demands a different one (the horizontal graph), and teams that conflate the two will discover the gap at the worst possible moment, with a 24-hour deadline running.

Where NIS2 and DORA fit, honestly

It is tempting to stack all three EU regimes into one regulatory wall and imply they all mandate the same thing. They do not, and a compliance-literate reader will catch the overstatement, so here is the honest version.

The CRA is the one with an explicit, named SBOM mandate in the legal text. NIS2 raises expectations for software supply chain security. Article 21 requires in-scope entities to manage security-related aspects of the relationships with their direct suppliers, but it does not mandate SBOMs by name. DORA, which has applied to financial entities since January 2025, emphasises ICT third-party risk management and a Register of Information covering third-party providers, rather than an SBOM requirement as such.

So the accurate framing is not "three laws all demand IaC SBOMs." It is that three overlapping EU regimes are pushing the same direction (software supply chain transparency and the ability to answer "what are we exposed to, and where" on a deadline), and the CRA is the one that makes the SBOM explicit and attaches the sharpest clock. The cross-repo graph is useful under all three for the same underlying reason: every one of them, in its own language, eventually asks a manufacturer or an essential entity to know where a given component or supplier sits across its estate. But the CRA's 24-hour reporting obligation is the concrete, dated forcing function, and it is the one to plan against first.

What this means for how you budget the work

If you are scoping CRA readiness for an engineering organisation, the practical decomposition is two projects, not one.

The first project is SBOM generation and retention: wire Syft or cdxgen or your build-tool's native CycloneDX plugin into CI, produce a machine-readable SBOM per product covering at least top-level dependencies, retain it as technical documentation, and ideally manage it in something like Dependency-Track so vulnerability correlation is continuous rather than incident-time. This is well-trodden ground with mature tools and it clears the Annex I floor.

The second project is the horizontal graph: the ability to answer, across every repository, which products ship a given component (base image, shared module, chart, workflow) and at which version, with the resolution work done ahead of the incident rather than during it. This is the project most teams have not separated out, because the SBOM conversation absorbs it. It is also the project that determines whether the 24-hour clock is a lookup or a fire drill.

The two projects share inputs. The same parser estate that resolves "which repos consume base-runtime" is reading the same Dockerfiles, Terraform sources, and Helm charts that feed component inventories. There is a real convergence here, and over time the artifact graph and the per-product SBOM become two views of one resolved dataset. That convergence is on Riftmap's roadmap and it is the subject of a future post once the SBOM-export work ships. For now the honest statement is narrower: Riftmap builds the horizontal graph today, and the horizontal graph is the half of CRA-readiness the SBOM tooling category does not cover.

What Riftmap returns for the cross-repo half

Concretely, the incident question ("which repositories ship company/base-runtime, and at which tag") is a single call against the artifact graph rather than an afternoon of grep and manual Dockerfile reading.

GET /api/v1/artifacts/{artifact_id}/consumers

{
  "artifact": {
    "id": "a17c4f02-8b9d-4e51-9c2a-1f7e6d3b8a90",
    "artifact_type": "docker_image",
    "name": "base-runtime",
    "source_repository_id": "c2d8e1f4-3a6b-4c9d-8e2f-7b1a9d4c6e30",
    "registry_url": "registry.company.com/platform/base-runtime",
    "version": "3.4.1",
    "consumer_count": 6,
    "is_orphan": false
  },
  "consumers": [
    {
      "repository": {
        "id": "f1a2b3c4-d5e6-4f70-8a91-0b2c3d4e5f60",
        "name": "checkout-api",
        "full_path": "polaris-works/payments/checkout-api"
      },
      "version_constraint": "3.4.1",
      "source_file": "Dockerfile", "source_line": 1,
      "is_latest": true,
      "import_count": 1
    },
    {
      "repository": {
        "id": "a9b8c7d6-e5f4-4039-8271-6a5b4c3d2e10",
        "name": "ledger-worker",
        "full_path": "polaris-works/payments/ledger-worker"
      },
      "version_constraint": "3.4.1",
      "source_file": "Dockerfile", "source_line": 2,
      "is_latest": true,
      "import_count": 1
    },
    {
      "repository": {
        "id": "12340000-5678-4abc-9def-000011112222",
        "name": "invoicing-svc",
        "full_path": "polaris-works/finance/invoicing-svc"
      },
      "version_constraint": "3.3.0",
      "source_file": "Dockerfile", "source_line": 1,
      "is_latest": false,
      "import_count": 1
    },
    {
      "repository": {
        "id": "33334444-5555-4666-8777-888899990000",
        "name": "internal-base-python",
        "full_path": "polaris-works/platform/internal-base-python"
      },
      "version_constraint": "3.4.1",
      "source_file": "Dockerfile", "source_line": 1,
      "is_latest": true,
      "import_count": 1
    }
  ],
  "total_consumers": 6,
  "consumers_on_latest": 5,
  "consumers_lagging": 1,
  "latest_version": "3.4.1"
}

The consumer table is the scope of the early-warning notification, already resolved. Each row carries the version constraint the consumer pins, the source file and line where the FROM lives, and whether that pin is on the latest published version. consumers_lagging: 1 is invoicing-svc, still on 3.3.0, evaluated against the published version list rather than left for you to work out by hand. That is the count you reason about for the report: which products ship the affected image, and which are behind.

Two of the resolution problems are worth calling out because they are exactly where a grep over FROM lines goes wrong, and they are resolved before these rows are produced rather than surfaced as separate fields. The first is build-arg substitution: a FROM company/base-runtime:${BASE_TAG} line only resolves to a real tag once the build argument is evaluated, so the consumer relationship has to be recorded against the actual base image rather than left as a literal ${BASE_TAG} string a text search would skip over. The second is the intermediate image: internal-base-python is itself built FROM base-runtime and is in turn consumed by other application repos, so the products that inherit the affected base through that wrapper are reachable by walking the graph one hop further, with a second call against internal-base-python as the artifact. Neither of those is a field you parse out of the response. They are resolution work the graph did so the response is already correct.

This does not generate the CRA SBOM. It answers the question the SBOM does not: where, across the estate, the affected component actually ships. The two halves are complementary, and the second half is the one with no existing category occupying it.

The short version

The CRA mandates a software bill of materials covering at least the top-level dependencies of each product. That is a vertical inventory, scoped to one artifact, and the SBOM tooling category (Syft, Trivy, cdxgen, Dependency-Track) produces it well.

The CRA's reporting clock, which starts on 11 September 2026, asks a different question. When an actively exploited component lands in something you ship, you owe a scope assessment inside 24 hours: which of your products with digital elements are affected, across every repository in your estate. That is a horizontal, cross-repo question. It is not what an SBOM is shaped to answer, and the SBOM tools say as much themselves: infrastructure relationships across repositories are explicitly out of their scope.

The gap between the two is a cross-repo IaC dependency graph: the resolved set of which products consume which shared components, across Docker base images, Terraform modules, Helm charts, and reusable workflows, with build-arg substitution evaluated and intermediate-image chains followed. Budget CRA readiness as two projects: SBOM generation, which is solved, and the horizontal graph, which is the half that turns the 24-hour clock from a fire drill into a lookup.

Riftmap builds that horizontal graph today. It does not yet emit CRA-format SBOMs. That convergence is coming, and it is a post for the day it ships. For now the claim is the narrow, true one: the part of CRA readiness that the SBOM category structurally does not cover is the part Riftmap exists to build.

Riftmap scans your GitHub or GitLab organisation with a read-only token, parses Terraform, Docker, Helm, Kustomize, Kubernetes, GitHub Actions, GitLab CI, Ansible, Go modules, and npm, and builds the cross-repo artifact graph as a queryable surface, for engineers in the UI and for agents over MCP. The "which products ship this component" query is one call. Five minutes to first graph. The free tier is here.

For the per-ecosystem parsing detail behind the consumer queries, the Find Every Consumer series goes one ecosystem at a time, starting with Docker base images.

Repo access was never the hard part

Daniel Westgaard — Sun, 31 May 2026 00:00:00 GMT

Spend an hour reading the support forums for any of the big coding agents right now and you will notice the same thread, over and over, in slightly different words. Someone has their codebase split across a handful of repositories. They point an agent at it. The agent can only see one repo. They want it to see the rest.

This is not a niche complaint. It is one of the loudest things engineering teams are asking for in 2026, and the vendors have heard it. In May, Cursor shipped multi-repo environments for its cloud agents, so that a single environment can hold every repository an agent needs. On the GitHub side, Copilot's cloud agent still runs inside the single repo where the task was opened, and the community has built its own cross-repo workarounds with MCP servers and scoped tokens while a native solution is expected. Agent HQ is pulling Copilot, Claude and Codex into the same GitHub workflows. Everyone is racing in the same direction.

I want to be generous about this, because it is genuine demand validation and I have been saying for a while that multi-repo work is where agents earn their keep. But I also want to name what the race is actually about, because I think most of the industry has quietly mislabelled the finish line.

The race is about access

Read the threads closely and the problem is always the same shape. Can the agent clone the other repo. Does the token have the right scope. Will the environment hold all seven repositories. Can a build secret reach the running agent. This is real, fiddly, important work, and it is also plumbing. It is the difference between an agent that can reach your code and one that cannot.

Plumbing gets solved. It always does. The gap between a single-repo agent and a multi-repo one is a few releases of integration work, and the largest, best-funded tooling companies in the world are spending those releases right now. If your mental model is "multi-repo is hard because access is hard," that model has a short shelf life. Within a couple of quarters, access across repositories will be a checkbox.

So it is worth asking what is left once the checkbox is ticked.

The quiet conflation

Here is the sentence I want to sit with. When Cursor announced multi-repo environments, the framing was that with several repos in scope, agents can "reason about how a change in one part of the codebase affects others."

That is a reasonable thing to say, and at the level of code symbols it is often true. But notice the move inside it. It slides from "the agent can see the repos" to "the agent understands how they depend on one another," and those are not the same claim. The first is about scope. The second is about structure. Scope is necessary for structure. It is nowhere near sufficient for it.

This is the conflation running underneath the whole multi-repo race. Access is being sold, understandably, as understanding. Putting the repositories in front of the agent is treated as the hard part, and the assumption is that comprehension follows for free once the files are reachable. It does not, and the reason it does not is in how these agents actually work out what depends on what.

How an agent actually resolves a cross-repo relationship

Once an agent has all your repos in scope, it still has to answer the question that matters: if I change this, what else breaks. There are three families of technique it can use, and it is worth being precise about each, because none of them is built for the thing I care about.

The first is agentic search, which is where Claude Code and several others have landed. No index, just grep and read, the model navigating the tree the way a person would. There are good arguments for this: grep returns a broad cluster of matches from which the model can infer the codebase's organisation and naming conventions. The key word is infer. The structure is reconstructed from text and from names, and names lie. A service called payments-api and a Terraform module called payments may be tightly coupled or completely unrelated, and grep cannot tell you which.

The second is retrieval over embeddings, the classic RAG approach, which is what codebase indexing in editors leans on. This is semantic similarity over chunks of code. It is excellent at "show me code that looks like this" and it is still, fundamentally, operating on the text. Similarity is not dependency. Two files can be deeply coupled and read nothing alike, and two files can read almost identically and never touch each other in production.

The third, and the most rigorous, is a real symbol graph. Sourcegraph's SCIP is the best example, and I have a lot of respect for it. It powers cross-repository code navigation: click a function in one repo and jump to its definition in another, compiler-accurate, no pattern matching. But look at what SCIP actually indexes. It was built to index programming languages to power go-to-definition and find-references, with a separate language-specific indexer for each language, scip-typescript, scip-python, scip-java, scip-clang. The unit is the programming-language symbol. Cross-repo, yes. But cross-repo symbols.

Where the edges actually live

Here is the problem with all three. The dependency that wrecks your afternoon on a multi-repo change is usually not a function call.

It is the Terraform module in one repo that sources a module in another. It is the Helm chart that deploys an image tag built somewhere else entirely. It is the service whose CI pipeline publishes an artifact that three other pipelines consume. It is the base image in a Dockerfile that lives in a platform repo two teams over. These are the edges that turn a one-line change into an incident, and they share two awkward properties.

They are not programming-language symbols, so the symbol graph, however precise, never sees them. SCIP resolving a TypeScript import across repos is genuinely useful and completely blind to the fact that the same repo's Helm values point at an image your change just rebuilt.

And they are not reliably inferable from text or names, so grep and embeddings can only guess at them. The guess is sometimes right, which is the dangerous part, because it is right often enough to be trusted and wrong often enough to hurt.

These edges are, however, declared. Precisely, deterministically, in the manifests: the Terraform source blocks, the Helm value references, the image tags, the CI artifact names, the package manifests across every ecosystem in the org. The information is not missing. It is sitting in the files, in a form that has to be parsed rather than inferred. I have written before about finding every consumer of a thing across an org and about why you do not need a virtual monorepo to do it. The short version: parse the manifests, per ecosystem, and the graph is just there.

Why this gets worse as agents get better

You could argue this gap has always existed and teams have muddled through. True. What changes the stakes is autonomy. Cursor has said that roughly a third of its own merged pull requests are now opened by agents, and that number has been climbing. Multiply that by an agent that can now touch seven repos in a single session.

An agent operating across a multi-repo system on an inferred map is simply a faster way to ship a cross-repo break. It will make the change confidently, because the relationship it could not see did not show up in its grep results. And then the change lands in front of a human reviewer who is verifying against the exact same blind spot, because the reviewer is also reading the diff and reasoning about blast radius from memory and naming.

This is the part I keep coming back to. The agent making the change and the engineer verifying it need the same thing, and it is not more access. It is a shared, structural account of how the system is actually wired. They need to be looking at the same map, and right now neither of them has one.

The layer nobody upstream is parsing

So this is the bet. Access across repositories is being commoditised in front of us, fast, by companies far larger than mine, and that is fine, because access was never the interesting part. The interesting part is the cross-repo dependency structure, and the reason the incumbents are not parsing it is not that they cannot. It is that their retrieval is built on inference and on language symbols, and parsing infrastructure manifests deterministically across ten or more ecosystems sits at an angle to how their systems are designed.

That is the layer I am building Riftmap to be. It scans a GitLab or GitHub org, parses the manifests across all the ecosystems that actually carry the dependency edges, and produces one queryable graph that answers "if I change this repo, what else breaks." Not inferred. Parsed. The same map for the agent and for the person reviewing what the agent did. For GitHub Copilot specifically, three ways to give it cross-repo context today is the practical companion to this argument — the workspace, Spaces, and MCP approaches, and where each one's repository list should come from.

Give an agent every repo in your org and you have given it access. You have not given it the map. Those are different gifts, and the second one is the one that stops the change from breaking three services you forgot were downstream.

Inferred context is not a dependency graph

Daniel Westgaard — Sat, 30 May 2026 00:00:00 GMT

A pattern I keep running into, first as a consultant and lately in places like r/CursorAI: a developer is working in one repo, asks an agent to change something that touches a shared library living in another repo, and the agent confidently writes code against an interface that changed six months ago. The methods do not exist any more. The suggestion looks right, reviews fine to a tired eye, and breaks at integration time.

The fix everyone reaches for now is an enterprise context engine that indexes the whole organisation and feeds the agent more context. Tabnine shipped a strong one this year. I want to be fair about this up front, because the rest of the post draws a line and the line only means something if the thing on the other side of it is good: the problem these engines target is real, grounding an agent in your actual systems clearly beats letting it guess from training data, and Tabnine is a serious product built by serious people.

But there are two different questions hiding under the phrase "cross-repo context," and they want different machinery. This is the third in a loose series about that confusion. The first looked at why a modelled catalog and a parsed graph are different categories; the second at why a code-symbol graph stops where infrastructure starts. This one is about the difference between context a model infers and a graph a parser derives, and why that difference is invisible right up until the moment it is the whole cost.

A note on what this post is, and isn't

This is not a competitive teardown. Tabnine's Enterprise Context Engine went generally available in February 2026, works alongside Cursor, GitHub Copilot and Claude Code rather than replacing them, and serves whichever agent a team already uses. It connects to repositories, CI, code review, docs and ticketing, builds a continuously updated model of the organisation, and hands the relevant slice to an agent at generation time. Tabnine was named a Visionary in the 2026 Gartner Magic Quadrant for Enterprise AI Coding Agents, for the second year running. The customer logos are the kind you would expect: large, regulated, careful. None of that is marketing fog. It is a real answer to a real problem, and if you are running agents across a large codebase it is worth your attention.

The argument here is narrower. "Context that makes my agent generate better code" and "the graph I check before I ship a breaking change" are different jobs, and the second one has a tolerance for error that inference cannot meet by construction. That is not a flaw in any context engine. It follows directly from the design choice that makes inference powerful in the first place.

If you are a platform engineer evaluating the wave of context infrastructure arriving this year, the practical takeaway is the same one I keep landing on: most teams need both kinds of thing, and the tools should look as different as the questions do.

Two questions hiding under "cross-repo context"

Sit with the problem for a minute and it splits cleanly.

The first question is generative. When the agent writes a call into the shared library, what does that library actually contain right now? What are its conventions, its recent changes, the half-finished migration nobody wrote down? This is a context problem. The better your index of code, conventions and history, the fewer wrong calls the agent makes. An inferred context layer is the right tool here, and a good one is genuinely hard to build. It reads everything, models the relationships semantically, and hands the agent the slice that matters. When it is slightly wrong, the cost is a suggestion you correct, which you were going to review anyway. The error is cheap because it lands inside a loop that already has a human in it.

The second question is structural. Before I change this shared thing, what across the organisation actually breaks? This is not a context problem. It is a graph problem. And the tolerance for being slightly wrong is on a completely different scale. If the answer to "what depends on this Terraform module" misses three repos, you do not find out at review time. You find out in production, three hours later, with Slack on fire. The error is expensive because it lands outside the loop, after the human has already signed off.

Same surface verb, "what depends on this," and almost nothing else in common. The first wants the model's best, fastest, most fluent guess. The second wants an answer you would be willing to gate a deploy on. That last phrase is the bar I hold everything in this post to, and it is a deliberately higher bar than "context that makes my agent a bit better."

Three ways to answer "what depends on this"

Here is the part that has shifted since I first started writing about this. A year ago the honest framing was a binary: inferred context versus a parsed graph. That binary is no longer quite right, because "deterministic" has become contested vocabulary. Several good products now claim some version of structure or determinism, and they mean genuinely different things by it. There are three architectures in the market, not two, and it is worth being precise about all three.

Inferred. A model reads your artifacts and decides what relates to what. This is the RAG-and-semantics camp: Tabnine's Enterprise Context Engine is the strongest current example, and its own materials are admirably direct about the mechanism, describing the engine as combining semantic retrieval with structural reasoning and enriching context with "inferred relationships." The edges are produced by a model's judgement. That is exactly the right tool for the generative question, where a fluent, broad, slightly-fuzzy picture beats a narrow exact one.

Registered. A human writes each entity into a typed catalog and the tooling queries it. This is the developer-portal camp: Backstage, Port, Roadie. Roadie made the case earlier this year, and made it well, that a typed entity graph with declared schemas gives an agent deterministic answers rather than the fuzzy output of semantic search over docs. They are right that it is deterministic to query. The catch is in the word registered: a catalog entry records what an engineer knew at the moment they wrote it, so the graph is only as current as the last person who updated the YAML, and the reason platform teams quietly abandon these catalogs is that the maintenance burden outpaces the value within a couple of quarters. Deterministic to read, stale by construction.

Parsed. Edges extracted from the source files that already define them. A Terraform module block referencing a git URL. A Dockerfile FROM pulling an internal image. A dependencies entry in a Chart.yaml. A reusable workflow referenced by uses:. These are not inferred and they are not separately registered. They are already written down, in manifests, in formats that parse deterministically, and the relationship either exists in the source or it does not. This is the camp Riftmap sits in, and the property that matters is that it is deterministic and self-updating: there is nothing for a human to maintain and nothing for a model to guess, because the declaration is the dependency.

The three are not ranked. Inference wins the generative question. The registered catalog carries metadata a parser will never see, like ownership and on-call. But for the specific question "what breaks if I change this," only one of the three gives you an answer with no maintenance debt and no probability attached. That is the one you can gate a deploy on.

Why inference is the wrong guarantee for the structural question

An inferred graph is built by a model reading artifacts and deciding what relates to what. That is powerful for the messy, semantic, undocumented stuff, and I am not dismissing it: a docker pull buried in a shell script, a convention that took three RFCs to settle, an architectural decision that lives only in someone's head. Recovering that is real value and it is hard to do well.

But for "what consumes this," inference has a property you cannot design away: you do not know what it missed. A confidence score tells you how sure the model is, not whether the edge exists. For impact analysis that is precisely the wrong guarantee, because the entire point of blast radius is that the expensive failures are the edges you did not know about. A tool that is usually right about which repos depend on your module is no help in the one case where being wrong is the whole cost. "Ninety-two per cent confident these are your consumers" is unshippable: you cannot merge a breaking change to a shared module against a probability distribution over its consumer set. You need the actual set, derived from actual source, with an audit trail you can hand to the consumer teams before you ship. A smaller graph you can audit beats a broader graph you have to trust.

This is not a lonely opinion, which is the other thing that has changed in the last year. The distinction between deterministic and inferential machinery is becoming load-bearing across the field. Martin Fowler's site published a piece on harness engineering that splits an agent's supporting tools into computational ones, which are deterministic, cheap and safe to run on every change, and inferential ones, which are semantic, expensive and non-deterministic, useful precisely where you can tolerate the fuzz. Independent academic work points the same way: a January 2026 paper from Tel Aviv University introduces the Repository Intelligence Graph, a deterministic, evidence-backed map extracted from build and test artifacts that agents treat as the authoritative description of repository structure. Giving three commercial agents that deterministic graph improved mean accuracy by 12.2% and cut completion time by 53.9%, with the largest gains in exactly the multilingual, cross-toolchain repositories where inference struggles most. Even Roadie, from the registered camp, is arguing that structure beats semantic retrieval for the questions an agent needs to act on.

The field is converging on the idea that some questions want a deterministic answer and some want an inferred one, and that conflating them is the mistake. The structural question is firmly in the first bucket.

The coverage gap inference does not close

There is a second problem, separate from the confidence-score one, and it is the one I care most about because it is where the actual work lives.

The dependency edges that bite hardest in a DevOps organisation are not function calls. They are a Terraform module block referencing a git URL with a ?ref= pin. A Dockerfile FROM pulling an internal base image whose tag is set by a build-arg in a separate CI file. A Helm chart depending on another chart through OCI, or HTTPS, or a Flux source pointer. A CI template included across thirty repos. A reusable GitHub Actions workflow referenced by uses: org/repo/.github/workflows/deploy.yml@v2. These are declared, in manifests, in formats that parse deterministically. You do not need a model to read a dependencies block in a Chart.yaml. You need a parser, and then you need a resolver that canonicalises the git URL across its three URL forms, evaluates the semver constraint against the published versions, follows the umbrella chart that re-exports your chart, and chases the build-arg into the CI file that sets it.

Most code-intelligence and context engines stop at the language boundary and never touch this layer. That is not an oversight, it is the same structural fact I worked through at length for Sourcegraph: an IaC dependency is not a symbol. It is a value inside a string that an infrastructure tool evaluates at plan or build time. A semantic model can guess at these relationships, and it will get many of them, but "many" is the failure mode, not the success. The whole point of parsing this layer is that the answer is complete and verifiable, with each edge clicking through to the exact line that created it.

This is also why the IaC layer is the part inference is least equipped to fake. A model trained on a lot of code can reason fluently about a Go interface. The relationship between a Terragrunt root and the module it pins at ~> 3.2, mediated by an intermediate wrapper module that floats on main, is not the kind of thing you reason fluently about. It is the kind of thing you parse, resolve, and check.

What about the tools that parse deterministically too?

The honest objection here is not "isn't this just Tabnine." Tabnine infers; the line against it is clean. The sharper objection comes from the small but growing set of tools that do parse deterministically: local context engines like vexp and open-source analysers like codeindex build dependency graphs straight from an AST with tree-sitter, with nodes for functions, classes and types and edges for calls and imports, no model in the path. The Repository Intelligence Graph paper above is in the same spirit, extracted from build systems. These are deterministic, parsed and auditable, and they are right to be.

They also stop at the same place Sourcegraph does. The graph is a code-symbol graph: functions, types, imports, usually within a single project on a single machine. That is genuinely useful, and for "who calls this function" it is the correct architecture. But it is not the cross-repo infrastructure-artifact layer. None of these tools resolves a Terraform module source across an organisation, evaluates Helm version constraints across three reference formats, or follows a Docker base image through a build-arg into the CI file that sets it. The parsed-graph idea is spreading, which I take as validation, and it is spreading at the language-symbol level while the cross-repo IaC artifact layer stays unserved. That gap is the entire reason Riftmap exists.

So the map has three axes, not one. Inferred context engines (Tabnine) for the generative question. Registered catalogs (Backstage, Port, Roadie) for org metadata. Parsed graphs for the structural question, splitting again into code-symbol parsers (vexp, codeindex, Sourcegraph's SCIP) and the artifact parser estate that handles cross-repo IaC. Riftmap is the last of those, and as far as I can find it is currently the only one.

What this means in practice

I think these tools compose rather than compete, and I mean that more precisely than the usual "we play nicely together."

If you are running an agent across a large codebase, a context engine that grounds its generation is worth having. Feed it the cross-repo picture and your agent hallucinates less and writes against the interface that exists today rather than the one from six months ago. That is a real win and I would not argue against it for a second.

But when the actual decision in front of you is "I am about to change this thing, what is the blast radius," you want a graph that was parsed, not inferred. Edges you can click through to the exact line that created them. A version constraint already evaluated against the published versions, so you know which consumers float onto your new release and which are pinned and safe for now. No confidence score, because there is nothing to be unsure about: the module either references that source or it does not.

Concretely, that is the difference between an agent reasoning over a semantic graph and an agent making a call like this before it plans a change:

GET /api/v1/repositories/{id}/impact

{
  "affected": [
    { "repo": "acme/platform-prod", "depth": 1, "version_constraint": "~> 3.2" },
    { "repo": "acme/monitoring",    "depth": 2, "version_constraint": ">= 3.0" }
  ],
  "total_affected": 7,
  "last_scanned_at": "2026-05-30T08:14:00Z",
  "last_commit_sha": "a1b3f9c"
}

That response carries a freshness contract, not a confidence score. If the repo has been pushed to since the graph last looked, the agent knows the data may be stale and can trigger a rescan before it trusts the answer. Staleness is detectable and fixable. A missed edge in an inferred graph is neither.

This is the multi-context future I sketched in the Sourcegraph piece: a serious agent setup in 2027 composes several specialised context layers, each with its own grammar and freshness model and MCP server. Symbol context for code, artifact context for infrastructure, ticket context, docs context, runtime context. An inferred context engine is one of those layers and a good one. The parsed artifact graph is a different layer answering a different question. The composition is the point, not the competition.

The short version

There are two questions under "cross-repo context." The generative one, "what does this library contain," wants the model's best guess, and an inferred context engine is the right tool for it. Tabnine's is strong and the problem it solves is real.

The structural one, "what breaks if I change this," wants a different guarantee. A confidence score answers the wrong question, because blast radius is precisely about the edges you did not know existed, and the IaC edges that hurt most are declared in manifests a parser can read completely rather than guessed at semantically. For that question you want a graph that was parsed, not inferred: deterministic, self-updating, auditable to the exact line, carrying a freshness contract instead of a probability.

The market has three architectures for this now, not two. Inferred context for generation, registered catalogs for metadata, parsed graphs for impact. The parsed camp is filling in at the code-symbol level and still empty at the cross-repo infrastructure level. That is the line I have drawn with Riftmap: deterministic parsing first, across the IaC and DevOps ecosystems where the edges are declared and verifiable, with no model guessing anywhere in the path that answers "what breaks."

Inferred context is useful. It is just answering a different question than the one you ask right before you ship a breaking change. For that question you do not want the model's best guess. You want the graph.

This is the kind of question Riftmap is built to answer. It scans your GitHub or GitLab organisation with a read-only token, parses Terraform, Docker, Helm, Kustomize, Kubernetes, GitHub Actions, GitLab CI, Ansible, Go modules and npm, and builds the cross-repo artifact graph as a queryable surface, for engineers in the UI and for agents over the API. Around ninety seconds to first graph. If you have read this far, the free tier is here, and the agent integration guide shows how to wire the graph in as a tool call.

If you want the underlying parsing work one ecosystem at a time, the Find Every Consumer series goes through Docker base images, Terraform modules, GitHub Actions workflows, Helm charts and Go modules in turn.

Modeled graphs and parsed graphs: two architectures for cross-repo context in the agentic era

Daniel Westgaard — Tue, 26 May 2026 00:00:00 GMT

A platform engineer asks two questions on the same morning. First: "Who owns the payments-api service, what's its on-call rotation, and is it production-ready?" Second: "I'm bumping the shared terraform-modules/networking module to v3.3.0 — which application repos consume it, at what version pin?" The first is a modeled-catalog question and Port answers it at the top of the category. The second looks similar from a distance, has the same surface frame — "what's the cross-repo state of this thing" — and is, mechanically, a completely different graph. This post is about why.

A note on what this post is, and isn't

This is not a competitive teardown. Port raised $100M in December 2025 at an $800M valuation, led by General Atlantic with participation from Accel, Bessemer, and Team8. Their customer list runs through GitHub, British Telecom, Visa, Sonar, StubHub, and Nando's, and they reported 300% revenue growth in the prior year. Their repositioning as the Agentic Engineering Platform is one of the cleaner category pivots in platform-engineering tooling, and Zohar Einy's May 2026 post The hidden technical debt of agentic engineering is the most useful taxonomy of agent infrastructure debt anyone has written this year.

The argument here is narrower: modeled catalogs and source-derived dependency graphs are orthogonal categories. This isn't a flaw in Port. It follows from the design choices that make Blueprints work in the first place. The same way Sourcegraph's symbol graph is structurally outside what an IaC dependency graph needs — which I covered in the companion post on symbol graphs and artifact graphs — Port's modeled catalog is structurally outside what a source-derived dependency graph produces.

If you're shopping for an IDP and want a feature comparison, this isn't that — Port's own comparison pages cover the modeled-catalog category they compete in well, and this post is about an adjacent category that doesn't appear there. The practical takeaway for platform teams evaluating "context infrastructure for the agentic era" is that the modeling layer and the parsed-dependency layer are peers, not alternatives, and the tools should look as different as the questions do.

Two questions that look similar from a distance

Sit down with a platform team in 2026 and they keep coming back to two shapes of question. They sound similar enough that vendor categories blur them.

Question one: Who owns the payments-api service? What's the team's on-call rotation? Is the service tagged as production-ready by our scorecards? What's its tier-of-criticality? Which Jira project tracks its work?

This is a modeled-catalog question. The answers don't live in source files. They live in policies, processes, and human-registered ownership boundaries. The right shape of tool is a catalog: someone registers that payments-api is owned by team-checkout, on-call goes through PagerDuty rotation checkout-primary, tier is T1, runbook lives at this Confluence URL. The catalog aggregates that information across hundreds of services and exposes a unified surface. Port is the standard-bearer for this category in 2026 and has earned that position.

Question two: I'm bumping terraform-modules/networking from v3.2.0 to v3.3.0. Which application repos consume it? Of those, which are pinned to exact v3.2.0, which to ~> 3.2, which to >= 3.0? Which umbrella modules re-export networking and pull it in transitively? What about the consumers that reference it as git::https://gitlab.company.com/infra/terraform-modules.git//networking?ref=v3.2.0 with a git ref pin?

This is a parsed-dependency question. The answers already exist, written down in machine-readable form, in the customer's source files: source = "..." blocks in HCL, dependencies: lists in Chart.yaml, FROM lines in Dockerfiles, uses: strings in GitHub Actions workflows, include: directives in GitLab CI YAML, require statements in go.mod. Nobody registers those relationships into a catalog. The engineer declares them once, in source, when they write the IaC that consumes the artifact. To answer the question, something has to parse that source.

Both questions are reasonable. The first has a clean tool category — Port and the IDP space have made this their territory. The second has a different shape and needs different machinery.

Port's Context Lake, read carefully

Port's clearest architectural statement in 2026 lives on their Context Lake product page. The four feature claims, verbatim:

Feed agents with complete SDLC data — Create a unified knowledge graph. Bring your own data model so agents understand your world.

Build a library of actions for agents — Give agents what they need to operate autonomously.

Set access rules for agents — Protect your organization from destructive AI actions by enforcing guardrails.

Exposed via MCP — The context lake is accessible to every agent in your ecosystem.

The phrase to sit with is the one I emphasized: bring your own data model so agents understand your world. That sentence is the architecture compressed into ten words. The Context Lake holds exactly what the customer's data model models. The customer's data model is defined in Blueprints. Blueprints are JSON Schemas the platform team writes.

Team8, one of Port's lead investors, summarized the same architecture in their December 2025 investment post: "Blueprints power a living graph of context, while agentic workflows run on top." The word "living" matters: continuously ingested, evolving, kept current by integrations. It does not mean source-derived. The Blueprints are alive in the sense that the data flowing into them is fresh. The Blueprints themselves remain the contract the platform team defined.

Stefan Daugaard Poulsen at Eficode — now an official Port partner and one of the most experienced IDP consultants in the Nordic market — describes the same architecture from the inside: "When you start out with Port you put your attention into defining blueprints, which are the basic building blocks of your portal. Each blueprint consists of properties which you can populate from your different integrations." That's not criticism — that's how Port is designed to work. The platform team designs the schema; the integrations populate it. Stefan's broader post is unambiguously positive — titled "Choosing an internal developer portal is hard, but Port made it easy" — and the quoted line is describing the intended workflow approvingly, not flagging modeling overhead as a problem.

What a Blueprint looks like

Here's Port's own canonical example of how a Blueprint declares its relations to other Blueprints:

{
  "identifier": "microservice",
  "title": "Microservice",
  "schema": {
    "properties": {
      "language": { "type": "string" },
      "on-call": { "type": "string", "format": "email" },
      "slack-notifications": { "type": "string", "format": "url" }
    }
  },
  "relations": {
    "owningTeam": {
      "title": "Owning Team",
      "target": "team",
      "required": true,
      "many": false
    },
    "deployedTo": {
      "title": "Deployed To",
      "target": "environment",
      "required": false,
      "many": true
    }
  }
}

Every property the catalog will track is declared in the schema. Every relation the graph will represent is also declared in the schema: the target Blueprint, whether the relation is required, whether it's many. The graph topology is whatever the schema says.

For modeled-catalog questions — ownership, scorecards, on-call, business criticality, deployment tier, compliance class — this is exactly the right architecture. Those properties are not declared in main.tf. They are registered by humans on purpose because humans are the source of truth for them.

What Riftmap returns for the parallel question

Now consider the parallel artifact for the parsed-dependency question. You're the owner of a shared Helm chart at v1.2.0 and you want the list of consumer repos, their version constraints, and which of them will float to the next release.

GET /api/v1/artifacts/{helm_chart_id}/consumers

{
  "artifact": {
    "id": "b3790d64-c693-47d5-83b0-3a2c3872faf9",
    "artifact_type": "helm_chart",
    "name": "helm-library-chart",
    "source_repository": {
      "full_path": "polaris-works/platform/helm-library-chart"
    },
    "version": "1.2.0",
    "consumer_count": 5,
    "is_orphan": false
  },
  "consumers": [
    {
      "repository": { "full_path": "polaris-works/data/data-helm" },
      "version_constraint": "1.1.0",
      "source_file": "Chart.yaml", "source_line": 8,
      "is_latest": false
    },
    {
      "repository": { "full_path": "polaris-works/portal/portal-helm" },
      "version_constraint": ">=1.0.0 <2.0.0",
      "source_file": "Chart.yaml", "source_line": 8,
      "is_latest": true
    },
    {
      "repository": { "full_path": "polaris-works/payments/payments-helm" },
      "version_constraint": "~1.2.0",
      "source_file": "Chart.yaml", "source_line": 8,
      "is_latest": true
    }
  ],
  "consumers_on_latest": 4,
  "consumers_lagging": 1,
  "latest_version": "1.2.0"
}

Every relationship in this response was derived by reading the consumer repos' Chart.yaml files — no Blueprint, no Relation declared in advance, no integration custom-built for helm_chart semantics. The parser estate already knows what a Helm chart is and what its consumer relationships look like, because the IaC tools have their own grammars and the resolver implements those grammars. The constraint shapes the parser normalises (exact-current 1.2.0, exact-behind 1.1.0, tilde range ~1.2.0, explicit range >=1.0.0 <2.0.0) are evaluated against the chart's published version, server-side, before the agent or engineer sees the response.

The contrast is the structural argument. Port's API requires a data model because you are the source of truth for which Blueprints matter at your organization, and that's correct for the questions Port is built to answer. Riftmap's API does not require a data model because the source code is the source of truth for the dependency graph, and that's correct for the questions Riftmap is built to answer.

What Port's "Terraform integration" actually does

It's worth being precise here, because Port and Terraform appear in the same sentence a lot. Port has two distinct things they call "Terraform":

The first is the port_blueprint Terraform provider. This lets you define Port's Blueprints in HCL instead of clicking through the Builder UI. It's catalog-as-code: your catalog schema is versioned in a Terraform state file. The provider manages Port's catalog. It does not parse your .tf source files for module dependencies.

The second is the Terraform Cloud integration. This connects Port to HCP Terraform's REST API and ingests Organizations, Projects, Workspaces, Runs, State Versions, State Files, and Health Assessments into Port Entities. It's an excellent integration for what it does — you can see which workspaces ran which Terraform plans and surface failed runs in a dashboard. It is entirely API-shaped: the data comes from app.terraform.io's REST endpoints, not from parsing customer source files. If your Terraform doesn't run through Terraform Cloud (a great many organizations run it through Atlantis, Spacelift, env0, Scalr, custom GitHub Actions, or terraform apply from a bastion), the integration has nothing to ingest.

There's a sharper distinction worth naming, because it shapes the rest of the argument. Port's integrations parse the outputs of upstream systems — Terraform Cloud's REST API, Kubernetes' CRD schemas, Datadog's runbook YAML, GitHub's CODEOWNERS, PagerDuty's escalation policies. That is a kind of parsing, and Port does it well. What Port's integration estate doesn't do is parse customer source files for the IaC tool's own dependency-evaluation semantics — terraform init's module installer, Helm's chart dependency resolver, docker build's ARG substitution, GitHub Actions' reusable workflow resolution. Those evaluators are part of the IaC tools themselves, not API surfaces of upstream vendors. The dependency relationship between the networking module's source repo and the consumer repos lives in HCL source = "..." declarations across the consumer repos, evaluated by Terraform itself at init time, and Port's integration estate doesn't reach that layer.

Where the architecture pushes back

Concretely, here are the shapes of dependency that show up in every infrastructure-heavy organization and that the Blueprint-plus-integration model doesn't naturally absorb. I covered the parsing details in the Find Every Consumer series, so I'll keep these short.

1. Terraform module sources with git URLs and ref pins.

module "vpc" {
  source = "git::https://gitlab.company.com/infra/terraform-modules.git//networking?ref=v3.2.0"
}

To model this in Port you'd need a terraform_module Blueprint, an application_repo Blueprint, and a consumes_module Relation between them — plus an integration that walks every consumer repo, parses HCL, normalizes git URLs across https://, git@, and stripped-.git forms, parses the ?ref= query parameter, and evaluates whether the ref is a tag, a branch, or a commit SHA. Port doesn't ship that integration. (How to find every consumer of your Terraform module.)

2. Docker FROM with build-arg substitution.

ARG BASE_TAG=latest
FROM company/base-runtime:${BASE_TAG}

The actual base image consumed in production depends on --build-arg values that live in a separate file: .github/workflows/build.yml, docker-bake.hcl, docker-compose.yml, a Makefile target. Resolving the real consumer relationship requires reading the Dockerfile, finding the default, then reading the build invocation across YAML and shell. (How to find every consumer of your Docker base image.)

3. Helm chart consumers across three reference formats.

# Chart.yaml dependency
dependencies:
  - name: platform-services
    version: "~3.2.0"
    repository: "oci://registry.company.com/charts"
    alias: monitoring

# ArgoCD Application
spec:
  source:
    chart: platform-services
    repoURL: https://charts.company.com
    targetRevision: 3.2.1

# Flux HelmRelease
spec:
  chart:
    spec:
      chart: platform-services
      version: ">=3.0.0 <4.0.0"
      sourceRef:
        kind: HelmRepository
        name: company-charts

All three reference the same chart. The first uses OCI, the second HTTPS, the third a Flux source pointer that needs separate resolution. A complete answer to "who consumes platform-services at v3.2.0" needs to normalize all three forms to a canonical chart identity, evaluate constraints against published versions, follow Flux source pointers, and follow umbrella charts that re-export platform-services as a subchart. (How to find every consumer of your Helm chart.)

4. Reusable GitHub Actions workflows.

jobs:
  deploy:
    uses: company/actions/.github/workflows/deploy.yml@v2

The uses: value is a single string encoding <owner>/<repo>/<path>@<ref>. Resolving "who uses my deploy workflow" means parsing this format, normalizing the repo identifier, evaluating the ref pin, and following transitive includes when a reusable workflow itself calls other reusable workflows. None of that is exposed in the GitHub REST API in structured form. (How to find every consumer of your reusable GitHub Actions workflow.)

Port's Blueprint system can absolutely represent the resulting graph once it's been computed. What it can't naturally do is compute it — because the integration estate is shaped to consume upstream system APIs, not to evaluate IaC tools' dependency semantics against customer source files.

The maintenance gradient, scoped properly

I covered the broader version of this in the catalog maintenance trap post and applied it to the buying decision in Backstage alternatives in 2026; the unqualified version of that critique applies more to first-generation IDPs (Backstage in particular) than to Port's current architecture. For the data Port's integrations cover — services discovered via Git, deployments via Kubernetes, on-call via PagerDuty — Port's integration-fed catalog materially reduces the drift problem.

The drift problem applies precisely where it can't apply differently: data that lives in customer source files for which no upstream API exposes structured semantics. The relationship between payments-helm's Chart.yaml and helm-library-chart at v1.2.0 is not in GitHub's REST API as structured dependency data. It's in YAML that the customer wrote, that Helm evaluates at install time, against a registry that the customer also wrote. To get it into a Blueprint, somebody — Port, a platform team, an Ocean partner — has to evaluate that grammar against those sources. The catalog-maintenance argument is unchanged for this specific layer: ask a human to write down what's already declared in source and the registered copy goes stale. Build a parser that reads the source on every scan and it doesn't.

This is the gap. Not modeled catalogs in general — modeled catalogs for IaC-source-derived data specifically.

Steelmanned objections

A few objections, taken at their strongest.

"Couldn't Port add IaC parsers via the Ocean framework?"

In principle, yes. Port's Ocean Extensibility Framework lets anyone build a custom integration that ingests data into Port's Blueprints. Nothing prevents a third party — or Port themselves — from shipping an Ocean integration that parses customer Terraform, Helm, and Docker sources, and populates Port Entities with the resulting graph.

The natural place for that work to live is not inside Port. It's at the layer below Port — a parser estate that does the IaC-specific resolution once and exposes structured output that any downstream consumer can ingest. Port via Ocean. Backstage via a plugin. Cortex via their integration framework. An MCP server for any agent. A REST API for custom dashboards. The parser estate is the same; the consumers differ. The composition story isn't competitive — it's compositional: a source-derived dependency graph is most useful when it's exposed through every catalog and every agent tool list, not when it's locked inside any single IDP.

What Port couldn't do without changing the architecture is make source-derived parsing a native primitive — the way SCIP is native to Sourcegraph. The Blueprint-and-integration model is committed to "data model is platform-team-defined, populated by integrations from external systems." Native parsing of customer source for IaC dependency semantics would mean a separate ingestion pipeline that derives Blueprints rather than being populated into them. That's a sister architecture, not an extension.

"Isn't Port's AEP pitch the same context-for-agents pitch as Riftmap's?"

The pitches converge at the surface and diverge at the layer. Both products are betting that "context for agents" is the next major budget category in platform engineering. Both expose MCP. Both make a credible case that agents without structured context are dangerous in production.

The layer is where they diverge. Port's context layer is the modeled SDLC context: services, owners, scorecards, incident history, deployment history, on-call rotations, ticketing relationships. The agent picking up a Jira ticket needs to know which service is affected, who owns it, what the production tier is, what changed recently. Riftmap's context layer is the source-derived IaC dependency graph: which Terraform modules are consumed by which repos at which versions, which Helm charts are deployed against which Kubernetes manifests, which GHA workflows are reused across the org. The agent doing a cross-repo refactor needs to know which downstream consumers will break.

An agent doing serious work in 2026–2027 needs both inputs. The dual-audience framing here is identical to the one in the symbol-graphs-and-artifact-graphs post: specialized context layers, composed by the agent's tool list, exposed through their respective MCP servers.

Zohar Einy's runtime-context example in the hidden-tech-debt post is actually consistent with this. His example splits cleanly across the two architectures: "what language and framework the service uses" and "who owns the downstream service it calls" are modeled-catalog answers. "How retries are handled in other services in this org" and "whether there's been a recent config change" sit closer to source-derived. The taxonomy his post lays out is right; the inference that one platform layer should provide all of it doesn't follow.

"Doesn't Port's roadmap inevitably head this direction?"

Maybe, eventually. The strategic question isn't whether Port could ship a feature labeled "Terraform module dependency graph." It's whether the architecture that ships it is Blueprint-shaped or parser-shaped. A Blueprint-shaped version — where Port asks the platform team to declare terraform_module and application_repo Blueprints and populate them via a custom Ocean integration — is mostly already possible today and is the recommended path for custom data models. A parser-shaped version — where Port natively ingests customer Terraform source and derives the graph — would require a different architectural commitment.

I expect the Blueprint-shaped path to ship first, because it fits Port's existing architecture. I expect it to underperform what dedicated parsers produce, because the resolver complexity is real and you can't compete with multi-quarter parser investments by writing a custom integration on top of a generic ingestion framework.

Composition, not competition

Every vendor in adjacent categories has repositioned around "context for agents" in 2026. Sourcegraph 7.0 in February called itself "the intelligence layer for AI coding agents and developers". Port relaunched at the December 2025 Series C as the Agentic Engineering Platform with the explicit framing that "humans and agents will run the SDLC together." Cursor, Claude Code, and Amp all ship MCP integrations and rules files. The category language is converging from three different starting points.

The architecture taking shape across the agent ecosystem is multi-context composition. An agent working on a non-trivial cross-cutting change pulls from several specialized context layers:

Symbol context. The code-graph layer Sourcegraph owns: cross-repo function calls, type usages, API references.
Modeled catalog context. The IDP layer Port, Cortex, OpsLevel, Compass, and Backstage compete for: ownership, scorecards, incident history, deployment history, on-call rotations, business criticality.
Source-derived artifact context. The IaC dependency layer Riftmap is built for: Terraform module consumers, Helm chart consumers, Docker base image consumers, GHA workflow consumers, transitive umbrella resolution, version constraint evaluation.
Runtime telemetry context. Datadog, Honeycomb, Sentry, log aggregators.
Project and decision context. Linear, Jira, Notion, Confluence, ADR repos.

Each layer is its own product category, with its own architecture and its own MCP server. The agent's tool list composes them. Cross-layer orchestration — composing the modeled catalog, the parsed dependency graph, the symbol graph, and the telemetry feeds into a single agent context — isn't owned by any one platform. It's configured by the platform team and executed by the agent. Within-layer orchestration is a different and legitimate question — Port's Workflow Orchestrator is exactly that pitch for the modeled-catalog layer, and it's a coherent product inside that scope. Neither it nor any tool from an adjacent layer competes to be the cross-layer orchestrator, because the cross-layer orchestrator is the agent.

This is also the structural answer to the LLM-loop objection (couldn't Cursor or Claude Code just grep through this?) — the artifact-graph case breaks the glob-and-grep loop because the truth requires resolver semantics, not just text matching. The symbol-graphs-and-artifact-graphs post covers the architectural reason in detail.

The test for whether this category has matured is whether nobody is surprised that the IaC dependency layer lives behind its own MCP server, just as nobody is surprised that the code-symbol layer lives behind its own.

The short version

Modeled catalogs hold what humans register about their systems. The schema is whatever the platform team designed; the contents are whatever the integrations ingested. The source of truth is human judgment. For "who owns this service, what tier is it, is it production-ready, what's the on-call rotation" — modeled catalog, Port, end of discussion.

Parsed dependency graphs hold what infrastructure-as-code already declares about itself. The schema follows the ecosystems' own grammars; the contents are derived by parsing source files; the source of truth is the customer's repos. For "who consumes my Terraform module at v3.2.0, which Helm releases pin which chart version, which reusable GHA workflow is called across the org" — parsed dependency graph, Riftmap, built for exactly this.

The questions sound similar. The graphs are different shapes. Most platform teams have both questions, and the right answer is to use both kinds of tool — the same way a serious agent setup composes multiple specialized context layers instead of asking any one platform to serve every question.

This is the kind of question Riftmap is built to answer. It scans your GitHub or GitLab organisation with a read-only token, parses Terraform, Docker, Helm, Kustomize, Kubernetes, GitHub Actions, GitLab CI, Ansible, Go modules, and npm, and builds the cross-repo artifact graph as a queryable surface — for engineers in the UI, for agents over MCP. Five minutes to first graph. If you've read this far, the free tier is here.

If you're interested in the architectural distinction from a different angle, the symbol-graphs-and-artifact-graphs post covers the same shape of argument for Sourcegraph and code-symbol graphs, and the catalog maintenance trap is the shorter companion piece on why modeled catalogs go stale for source-derivable data.

For the underlying parsing work for any single ecosystem, the Find Every Consumer series goes one ecosystem at a time: Docker base images, Terraform modules, GitHub Actions workflows, Helm charts, Go modules.

Symbol graphs and artifact graphs: why Sourcegraph stops where infrastructure starts

Daniel Westgaard — Fri, 22 May 2026 00:00:00 GMT

A platform engineer asks two questions on the same morning. First: "I'm renaming this Go method — who calls it?" Second: "I'm bumping our shared Terraform networking module to v3.3.0 — which application repos will run terraform plan against the new version?" The first is a symbol-graph question and Sourcegraph answers it at the top of the category. The second looks similar from a distance, has the same surface verb — "who depends on this" — and is, mechanically, a completely different graph. This post is about why.

A note on what this post is, and isn't

This is not a competitive teardown. Sourcegraph indexed 54 billion lines of code, created SCIP as an open language-agnostic protocol for code intelligence, and shipped cross-repository navigation at enterprise scale — at the time of writing they host SCIP indexes for over 45,000 public repos and serve customers including Reddit, Stripe, Canva, MongoDB, and Dropbox through their MCP server. Those are real engineering achievements and the product solves real problems well.

The argument here is narrower: code-symbol graphs and infrastructure-artifact graphs are orthogonal categories, and the second one is structurally outside what Sourcegraph's index produces. This isn't a flaw in Sourcegraph. It follows from the design choices that make symbol graphs work in the first place.

If you're a platform engineer evaluating "context infrastructure" — code search, IDPs, cross-repo tooling for humans and agents — the practical takeaway is that most teams need both kinds of graph, and the tools should look as different as the questions do.

Two questions that look similar from a distance

Sit down with a platform team and they will keep coming back to two questions. They sound similar enough that vendor categories blur them.

Question one: I'm changing this function. Who calls it?

This is a code-symbol question. The nodes are functions, methods, classes, types, modules. The edges are references — call sites, imports, type usages, inheritance. The engine that builds this graph is a language indexer: it parses TypeScript or Go or Java with a compiler-aware tool and emits a structured record of where each symbol is defined and where it's referenced. Sourcegraph is built directly on this category and is the standard against which everything in it is measured.

Question two: I'm bumping this shared Terraform module to v3.3.0. Which application repos will re-plan? Which of them are pinned to v3.2.0, which to ~> 3.2, and which to >= 3.0? Of those that float, which umbrella modules pull mine transitively?

This is an infrastructure-artifact question. The nodes are Terraform modules, Docker base images, Helm charts, Kustomize bases, reusable GitHub Actions workflows, Kubernetes manifests. The edges are artifact references inside infrastructure-as-code source files: source = "git::https://...?ref=v3.2.0", FROM company/base:${BASE_TAG}, dependencies[].repository: oci://..., uses: company/actions/deploy@v2, bases: - ../base-app.

The two graphs have the same surface verb — "who depends on this" — and almost nothing else in common.

What SCIP indexes — and what it doesn't

The clearest way to see why is to look at what SCIP, the protocol underneath Sourcegraph's cross-repo navigation, is actually designed to capture.

Sourcegraph's own description of what SCIP indexes covers two categories of structured data: symbols — carrying definition location, symbol metadata (function vs. class vs. variable vs. etc.), and package ownership including which repository and version defines the symbol — and external symbols — tracking cross-repository dependencies, the symbols defined in other packages, and version data for each dependency.

The keyword is symbols. SCIP indexes the things a compiler or language server understands as named declarations: functions, types, methods, namespaces. To produce this data you need a parser that understands the programming language's scoping and name-resolution rules. The same Sourcegraph post lists the official language coverage for auto-indexing as TypeScript, JavaScript, Python, Go, Java, Scala, Kotlin, and C/C++. The broader SCIP protocol has additional community indexers — for Ruby, .NET, Dart, PHP, Rust — but the marketed coverage of Sourcegraph's product is the eight-language list above.

All eight are general-purpose programming languages. The indexer for each is built on the relevant language's compiler or language server. Notice what isn't there, and isn't on the roadmap: HCL, Dockerfile, Helm Chart.yaml, Kubernetes manifest schemas, GitHub Actions workflow YAML, GitLab CI YAML, Kustomize, Ansible playbooks. Not because Sourcegraph forgot about infrastructure-as-code, but because IaC dependency relationships are not symbols. They're values inside strings that the IaC tool evaluates at deploy or build time. The grammar SCIP describes — definition location, symbol metadata, references — doesn't fit the shape of those relationships.

This is by design, not by oversight. A language indexer that tried to also produce IaC artifact edges would be solving a different problem with the wrong abstraction.

How Sourcegraph itself recommends answering IaC dependency questions

The strongest evidence for the category split is in Sourcegraph's own canonical content. Three of their flagship posts on impact analysis and blast radius — the questions that overlap most with the artifact-graph use case — fall back to regex search over manifest files at exactly the point where the answer turns infrastructural.

Multi-repo search: How to search across multiple repositories (March 2025) introduces blast radius and impact analysis as a multi-repo search use case, with the symbol-graph navigation as the precise tool: "It uses SCIP indexes to resolve actual symbol references, so you see real function calls and imports, not just string matches that happen to contain the function name." For the symbol case, that's the right answer.

Why code search at scale is essential when you grow beyond one repository (December 2025) walks through "impact analysis before changes" with a worked example. The example reaches for the artifact case — a Go service depending on a shared library — and the recommended query is:

repo:myorg/.* file:go.mod content:"auth-lib"

That's content: regex over the contents of go.mod files, scoped to repos matching myorg/.*. It works. It will find every go.mod in the org that mentions auth-lib. It will not tell you which version each consumer is pinned to in a way the next tool in your pipeline can act on without further parsing, it won't follow replace directives, and it won't resolve module path aliases.

Cross-Repository Code Navigation (January 2026) reaches the same pattern for npm. The post's worked example for "Finding All Usages of a Dependency" is:

context:global file:package.json "your-internal-lib":\s*"[~^]?1\.2\.3" patterntype:regexp

Again — regex over package.json strings. Again it works for finding the files. It doesn't return a structured consumer list with resolved version constraints across ~, ^, >=, and exact-pin forms; the regex enumerates each one explicitly.

This is not a critique of those posts. They're honest and they reach for the right tool. Symbol search isn't the tool for this question — for this question, text matching over manifest files is. But that itself is the observation worth sitting with: when Sourcegraph's own writers reach for dependency-impact use cases, they pivot from SCIP navigation to regex over manifest files. The reason is structural. SCIP doesn't index manifest files because manifest files are not source code in the sense SCIP was designed for. They're declarations a build tool will later resolve against an external system — a module registry, a container registry, a git remote, a chart repository, a Kubernetes API server.

The regex falls back because the symbol graph has no opinion about manifest declarations. It can't. That's not what it indexes.

The homepage demo, read carefully

Sourcegraph's current homepage runs a side-by-side comparison that illustrates the category split better than any external critique could.

The scenario: a developer asks an AI coding agent to add a Role field to a User struct in models/user.go. The baseline agent edits models/user.go and database/user_store.go, declares itself done, and offers a parting suggestion to add a migration. The post-it-note list of "what the agent missed" reads:

Auth middleware — no role check, any user can access admin routes
API response DTO — role never returned to clients
Audit logging — role changes not tracked, no compliance trail
/admin frontend routes — no guard, UI still accessible to all
Invite flow — new users created without a default role
4 integration tests — assert on user shape, will break

Then the same agent runs with Sourcegraph MCP. The agent calls sg_keyword_search "User struct" across 2,847 repositories, gets 31 files across 7 layers, and produces a complete change.

This is a strong demo and the win is real. But notice the exact shape of the problem and the exact shape of the offered tool. Every item on the "missed" list is a cross-cutting code-level concern: a middleware function that checks the user, a DTO type that serializes the user, an audit hook that writes when a user changes, a route guard that consults the user, an invite handler that constructs a user, integration tests that assert on the user shape. Every one of those is a symbol relationship. They are exactly what SCIP indexes and exactly what find_references and keyword_search are designed to surface.

Now imagine an adjacent scenario: a platform engineer is bumping the shared terraform-modules/networking module from v3.2.0 to v3.3.0 because the new version renames a variable. What does an equivalent demo look like?

The missed items aren't middleware/auth.go, api/dto/user_response.go, routes/admin/guard.ts. They're: the eight application repos that pin ?ref=v3.2.0 directly in a Terragrunt root, the four repos that pin ~> 3.2 and will float to the new version on next plan, the two umbrella modules in infra-platform-modules that re-export networking and are themselves consumed by another twelve repos, the one repo where the module is pulled through an intermediate terraform-aws-modules/internal-wrapper chain, and the three GitOps repos that reference the module path in an Atlantis repos.yaml. None of those relationships is a symbol. None of them appears in a SCIP index. A search for terraform-modules/networking returns a list of files containing that string and leaves the resolution work — git URL canonicalization, ref-pin parsing, semver constraint evaluation, transitive umbrella resolution, GitOps wiring — to whoever reads the results.

The homepage demo is correct that an AI agent without cross-repository context misses cross-cutting changes. It's also correct that a symbol graph closes that gap for code-level concerns. It just doesn't close the same gap for IaC-level concerns, because those concerns aren't built out of symbols.

What a symbol graph cannot resolve — four worked examples

Concretely, here are four shapes of dependency that show up in every infrastructure-heavy org, and that no code-symbol indexer can resolve without becoming a different product.

1. Terraform module sources with git URLs and ref pins

module "vpc" {
  source = "git::https://gitlab.company.com/infra/terraform-modules.git//networking?ref=v3.2.0"
}

Nothing here is a symbol. source is an HCL attribute. The value is a single string with overloaded semantics:

git:: is a Terraform protocol prefix
https://gitlab.company.com/infra/terraform-modules.git is a canonical git URL — which Riftmap normalizes against the same git remote whether it appears as https://, git@gitlab..., or with .git stripped
//networking is a subdirectory inside the module repo
?ref=v3.2.0 is a git ref pin (could equally be a branch, a tag, or a commit SHA)

To answer "which repos consume the networking module of terraform-modules at v3.2.0" you need a parser that understands this string format and a resolver that walks the repo URL back to a canonical identity. A code indexer sees an HCL attribute assignment with a string literal.

2. Docker `FROM` with build-arg substitution

ARG BASE_TAG=latest
FROM company/base-runtime:${BASE_TAG}

The actual base image consumed in production depends on the --build-arg passed at build time, which usually lives in a separate file — .github/workflows/build.yml, a docker-bake.hcl, a docker-compose.yml, a Makefile target. Resolving the real consumer relationship requires reading the Dockerfile, finding the default, then reading the build invocation to see if it's overridden. A symbol graph doesn't model build-time evaluation of CI variables across YAML files.

3. Helm chart consumers across three reference formats

# Chart.yaml dependency
dependencies:
  - name: platform-services
    version: "~3.2.0"
    repository: "oci://registry.company.com/charts"
    alias: monitoring  # the chart is installed under this name

# ArgoCD Application
spec:
  source:
    chart: platform-services
    repoURL: https://charts.company.com
    targetRevision: 3.2.1

# Flux HelmRelease
spec:
  chart:
    spec:
      chart: platform-services
      version: ">=3.0.0 <4.0.0"
      sourceRef:
        kind: HelmRepository
        name: company-charts

All three reference the same chart. The first uses OCI; the second uses HTTPS; the third uses a Flux HelmRepository pointer that needs to be resolved separately to a registry. The first uses a semver constraint ~3.2.0 and an alias that breaks name-matching in values overrides. The second is an exact pin. The third is an explicit semver range. A complete answer to "who consumes platform-services" requires (a) normalizing all three forms to a canonical chart identity, (b) evaluating each version constraint against the chart's published versions, (c) following Flux source pointers, and (d) following umbrella charts that re-export platform-services as a subchart. None of this is a symbol relationship. We covered the full Helm case in detail in How to Find Every Consumer of Your Helm Chart.

4. Reusable GitHub Actions workflows

jobs:
  deploy:
    uses: company/actions/.github/workflows/deploy.yml@v2

The pattern across all four: the consumer relationship is encoded in a string inside an IaC declaration, and resolving it requires understanding the IaC tool's grammar and its evaluation semantics. SCIP indexes none of this, on purpose. A different protocol indexes it, and a different parser estate emits it.

What each tool actually returns

Concretely: imagine you're the owner of platform-services Helm chart at v3.2.0 and you're about to publish v3.3.0, which renames a top-level value key.

With Sourcegraph, the recommended pattern is regex over Chart.yaml (and ArgoCD Application manifests, and Flux HelmRelease CRDs, and any shell scripts that call helm install, each a separate query):

context:global file:Chart.yaml "platform-services" patterntype:regexp

What you get back is a list of file matches: each result is a file path, a line number, a snippet showing platform-services in context, and PageRank-style ranking. You then open each file to read the version constraint, work out which chart identity is being referenced (HTTPS vs OCI vs alias), and manually evaluate which consumers will float to v3.3.0 versus stay on v3.2.x. The work scales with the number of results.

With Riftmap, the call against the same artifact looks like this:

GET /api/v1/artifacts/{helm_chart_id}/consumers

{
  "artifact": {
    "id": "b3790d64-c693-47d5-83b0-3a2c3872faf9",
    "artifact_type": "helm_chart",
    "name": "helm-library-chart",
    "source_repository": {
      "full_path": "polaris-works/platform/helm-library-chart"
    },
    "version": "1.2.0",
    "consumer_count": 5,
    "is_orphan": false
  },
  "consumers": [
    {
      "repository": { "name": "data-helm",               "full_path": "polaris-works/data/data-helm" },
      "version_constraint": "1.1.0",
      "source_file": "Chart.yaml", "source_line": 8,
      "is_latest": false,
      "import_count": 1
    },
    {
      "repository": { "name": "portal-helm",             "full_path": "polaris-works/portal/portal-helm" },
      "version_constraint": ">=1.0.0 <2.0.0",
      "source_file": "Chart.yaml", "source_line": 8,
      "is_latest": true,
      "import_count": 1
    },
    {
      "repository": { "name": "logistics-helm",          "full_path": "polaris-works/logistics/logistics-helm" },
      "version_constraint": "1.2.0",
      "source_file": "Chart.yaml", "source_line": 8,
      "is_latest": true,
      "import_count": 1
    },
    {
      "repository": { "name": "payments-multi-artifact", "full_path": "polaris-works/payments/payments-multi-artifact" },
      "version_constraint": "1.2.0",
      "source_file": "Chart.yaml", "source_line": 8,
      "is_latest": true,
      "import_count": 1
    },
    {
      "repository": { "name": "payments-helm",           "full_path": "polaris-works/payments/payments-helm" },
      "version_constraint": "~1.2.0",
      "source_file": "Chart.yaml", "source_line": 8,
      "is_latest": true,
      "import_count": 1
    }
  ],
  "total_consumers": 5,
  "consumers_on_latest": 4,
  "consumers_lagging": 1,
  "latest_version": "1.2.0"
}

Five consumers, four pin shapes the resolver normalises (exact-current 1.2.0, exact-behind 1.1.0, tilde range ~1.2.0, explicit range >=1.0.0 <2.0.0), and consumers_lagging: 1 already evaluated against the chart's published version — the consumer table is the structured answer to "who consumes my chart at v1.2.0" without leaving anything for the agent to parse.

What you get back is a structured consumer list. The same chart identity has been resolved across HTTPS, OCI, and Flux pointer forms before you see it. Each consumer carries its version constraint (~3.2.0, >=3.0.0 <4.0.0, exact 3.2.1) already evaluated against the published versions, so consumers within range of v3.3.0 are flagged. Umbrella charts that re-export platform-services are followed transitively; their downstream consumers appear with their own constraints. The work doesn't scale with the result count — the structure has been resolved once, server-side, by the parser estate.

Neither answer makes the other one wrong. They're answers to different questions, with different shapes, returned by different machinery.

Steelmanning the obvious objections

A few obvious objections, taken at their strongest.

"Couldn't Sourcegraph add IaC parsers?"

Yes, in principle. SCIP is an open protocol. Someone could write scip-hcl or scip-helm and emit Terraform-shaped or Helm-shaped records into the same index format Sourcegraph already serves.

The hard part isn't the parser. The hard part is the evaluator. The output of scip-hcl would have to be a different kind of fact — not "this symbol is defined here and referenced there" but "this source = "git::..." string, when evaluated by Terraform's module installer against the current state of remote git repositories, resolves to repo X at commit Y, in the context of which an attribute called Z is defined, which is consumed by a module block in repo W that depends on commit V of the same module." That's not a symbol-graph fact. It's an artifact-graph fact. You can serialize it in SCIP if you want, but the data model and the consumer code paths in Sourcegraph (go-to-definition, find-references, version-aware symbol lookup) are built for the symbol case. You'd have to build a parallel pipeline that resolves git URLs, parses semver constraints across ~/^/>=, follows umbrella charts, evaluates ARG defaults, walks reusable workflow chains, and normalizes container image references across registries. At that point you've built a different product that happens to share an index format with the first one.

The same logic applies to any code-symbol vendor — Cody, Greptile, OpenGrep, Augment, the rest of the category. The category isn't structurally suited to the artifact question. That's the whole point.

"Can't an LLM with Cody's @-mention just figure this out?"

This is the version of the objection that requires the most care, because Anthropic's lead on Claude Code has staked out a clear public position on the opposite side. In Boris Cherny's Pragmatic Engineer interview, the team described trying local vector databases, recursive model-based indexing, and other RAG-shaped approaches for agentic search. The conclusion was that "plain glob and grep, driven by the model, beat everything," and Claude Code shipped with that as the architecture.

Don't read this as a counter-argument to refute. Read it as structural validation of the category split. The Cherny bet is specifically that for symbol-level questions inside a working session, an LLM driving primitive tools (glob, grep, read) outperforms a pre-built index whose maintenance cost includes staleness, permissions, and integration complexity. That's a coherent and defensible position for the symbol case, and a careful reader of the Pragmatic Engineer interview will notice why it works: when the model greps for a function name, the relevant truth — the call site, the import statement, the type signature — is sitting in the source code the model can read. The model can iterate. It runs another grep, opens another file, and converges on a verified answer within the session. The primitive tool plus the model plus the source code is a complete loop.

The artifact case breaks the loop because the truth isn't sitting in the source files in a form grep can converge on.

Grep terraform-modules/networking across an org and you get a list of files that mention the string. What grep cannot return — and what reading those files cannot recover without rebuilding the parser estate inside the conversation — is the resolved answer: which of those references canonicalize to the same module across git::https://, git@gitlab:, and stripped-.git URL forms; which version constraints (~3.2.0, ^3.0.0, >=3.0.0 <4, exact 3.2.1) include v3.3.0 after evaluation against the published version list; which Flux HelmRepository source pointer in gitops/sources/ resolves to which registry; which umbrella module re-exports networking and pulls in its own downstream consumers; which ARG-substituted FROM line in a Dockerfile actually resolves to which base image after CI evaluation. The resolver complexity doesn't surface in grep output. It has to be built once, somewhere, against the IaC tools' grammars and against external registries — or the model has to rebuild it on every query, against text matches, with no audit trail.

That's why dependency questions want deterministic answers and why "92% confidence that these are your consumers" is unshippable. You can't merge a change to a shared Terraform module against an LLM probability distribution over its consumer set; you need the actual set, derived from actual source, with an audit trail you can hand to the consumer teams before you ship. The deterministic-graph approach has to survive even if Cherny's bet wins everywhere it's making its bet — because in the artifact case the model can't iterate to verification from primitive tools. The verification primitive is the parser estate itself.

"Doesn't `terraform graph` already solve this?"

terraform graph is excellent and frequently misunderstood. It produces the DAG of a single configuration — the resource dependencies inside one root module, used by Terraform's planner to schedule create/update/destroy operations in the correct order. It is not cross-repo, it is not cross-ecosystem, and it has no opinion about Docker base images, Helm charts, or reusable workflows. The same applies to Atlantis stack graphs, Spacelift stack dependencies, and HashiCorp Cloud Platform's Module Explorer — each solves a slice of the Terraform-orchestration problem from within a specific runner. The artifact graph in this post sits one level up: source-derived, cross-repo, cross-ecosystem, runner-agnostic.

What this means for the agent layer

If you've followed agent-context infrastructure in 2026 at all, you've watched every vendor in adjacent categories reposition around "the intelligence layer for AI coding agents and developers." Sourcegraph 7.0 (February 25, 2026) used that exact phrase to formalize the shift. Their MCP server lists Reddit, Stripe, MongoDB, Canva, Dropbox as customers using keyword_search, nls_search, go_to_definition, find_references, commit_search, diff_search, deepsearch, and a small set of related primitives.

That's the right shape of MCP server for symbol-level agent context. It's the shape Sourcegraph has been building toward for over a decade and the customer list reflects that fit.

It's also not the only MCP server a serious agent setup will compose by 2027.

The architecture taking shape across the agent ecosystem is multi-context composition. An agent working on a non-trivial cross-cutting change pulls from several specialized context layers: symbol context (the code-graph layer Sourcegraph dominates), artifact context (the IaC dependency layer Riftmap exists to provide), ticket and project context (Linear, Jira, GitHub Issues), documentation and decision context (Notion, Confluence, ADR repos), observability and runtime context (Datadog, Honeycomb, Sentry, log aggregators). Each layer has its own grammar, its own retrieval primitives, its own freshness model, its own MCP server. The agent's orchestration layer composes them.

In that picture, Riftmap and Sourcegraph aren't alternatives and they aren't complements in the usual "we play well together" sense either. They're peers in a converging architecture. The fact that the IaC artifact layer now has dedicated infrastructure is not evidence that Sourcegraph is wrong about code-symbol context. It's evidence that the architecture is maturing — that the field has gotten serious enough about agent context to specialize the layers instead of asking one tool to serve every question.

Both MCP servers can sit in the same agent's tool list. They answer questions Sourcegraph was built to answer well, and questions Sourcegraph was reasonably not built to answer at all. The composition is the point.

The short version

Symbol graphs index how code calls itself. The nodes are functions and types; the edges are references; the indexer is a language-aware parser; the protocol is SCIP. Sourcegraph is the standard-bearer for this category and has been for over a decade. For "where is this function called, who depends on this API, what's the blast radius of a refactor" — symbol graph, Sourcegraph, end of discussion.

Artifact graphs index how infrastructure consumes itself. The nodes are Terraform modules and Docker images and Helm charts and reusable workflows; the edges are artifact references inside IaC source; the parser estate is one-per-ecosystem and the resolution heuristics are IaC-tool-specific. For "who consumes my Helm chart at v3.2.0, which repos will re-plan on a Terraform module bump, what's the blast radius of changing a shared GitHub Actions workflow" — artifact graph, Riftmap, built for exactly this.

The questions sound similar. The graphs are different shapes. Most platform teams have both questions, and the right answer is to use both kinds of tool — the same way a serious agent setup in 2026 composes multiple specialized context layers instead of asking any one tool to serve every question.

That's the test for when this category has matured: when nobody is surprised that the IaC dependency graph lives behind its own MCP server.

I have since measured this across two real organisations — Prometheus and Cloud Posse — counting every cross-repo edge: the infrastructure share runs from a third to nearly all, and not one edge is a code symbol. The breakdown is in I counted every cross-repo edge in two real orgs.

The category has also since gained its largest entrant. GitLab shipped Orbit in June 2026, a property graph of code symbols and SDLC objects spanning a whole GitLab.com group, served to agents over MCP. It is a serious graph, and it draws the same line this post draws: no HCL parser, no Dockerfile parser, no artifact edges. I spent two days in the docs and the data model and wrote up what GitLab Orbit maps, and the layer it cannot reach.

There is a second axis worth separating from this one. This post splits graphs by what they index — code symbols versus infrastructure artifacts. A different split asks how the graph is produced: parsed from the manifests your repositories already declare, or modeled by hand in a catalog someone maintains. I drew that line against Port's Blueprints in modeled graphs and parsed graphs, and pushed declared vs inferred further into a three-way split — declared, inferred, or registered — in a separate post on how a tool comes to know an edge exists at all.

This is the kind of question Riftmap is built to answer. It scans your GitHub or GitLab organisation with a read-only token, parses Terraform, Docker, Helm, Kustomize, Kubernetes, GitHub Actions, GitLab CI, Ansible, Go modules, and npm, and builds the cross-repo artifact graph as a queryable surface — for engineers in the UI, for agents over MCP. Five minutes to first graph. If you've read this far, the free tier is here.

If you're interested in the underlying parsing work for any single ecosystem, the Find Every Consumer series goes one ecosystem at a time: Docker base images, Terraform modules, GitHub Actions workflows, Helm charts, Go modules.

Cross-repo context is in product docs. The graph is not.

Daniel Westgaard — Tue, 19 May 2026 00:00:00 GMT

Where the vocabulary moved, what the products shipped against it, and the layer that's still uncovered.

Six months ago, "cross-repo context" lived in dev.to posts and HN comments. Today it lives in vendor product documentation, in CPO interviews, in feature pages. It is in Warp's Codebase Context docs. It is on Augment Code's product pages as a feature called the Context Engine MCP. The phrase JetBrains coined in March to describe what AI agents produce without structural understanding, "shadow tech debt," was the framing of their Junie CLI launch. And in Microsoft's December 2025 look-ahead to AI in 2026, GitHub's chief product officer Mario Rodriguez named the category by a different name, "repository intelligence," and framed it as the new competitive advantage for AI-assisted software.

The vocabulary has crossed a threshold. In roughly sixty days it has moved from practitioner discourse into vendor product surfaces, which is faster than most category terms travel. The phrase used to belong to people who were losing sleep over the problem. Now it also belongs to people selling against it.

That distinction matters because vocabulary leads product. The language a vendor uses in docs encodes a promise about what the product delivers. When several vendors describe their offerings using the same phrase, the readers of those docs start to expect the phrase to mean something specific. The category forms in language before it forms in products. Once the phrase is in CPO interviews and product documentation, the window for defining what it means starts to close.

This post is about the gap between the two. The vocabulary moved. The products moved, but mostly not in the direction the vocabulary points. The thing the language most directly describes, a queryable cross-repo dependency graph derived from source manifests, exists. It lives in Meta's tribal knowledge engine, in Mabl's 850-line hand-maintained coordination graph, and in Riftmap. It does not yet live in the product that most readers reach for when they read "cross-repo context" in their AI tool's docs.

What the products actually ship

The landscape past the vocabulary line is finer-grained than I thought before doing the research. Four distinct things sit under the same phrase. Each is real. Each answers a different question. Only one of them is the thing the language most directly promises, and that one is the one no consumer vendor has shipped.

The workspace pattern. This is the largest cohort by vendor count. Warp, Cursor, Cline, Continue, Aider, Zed, Windsurf, GitHub Copilot, and Claude Code all sit here. They give the agent access to more files. Warp's docs are explicit: "During cross-repo tasks, Warp's Agents have access to the file paths of all indexed repos." Cursor's recommended pattern is the multi-root workspace; their community forum has open feature requests for cross-repo agent communication from December 2025 and February 2026, both still open. GitHub Copilot's most relevant recent shipping is picking the repository when assigning issues to Copilot, which lets an agent operate in a different repo per assignment. That is the workspace pattern at organisation scale. (For the three workarounds that give Copilot cross-repo context today — multi-root workspaces, Copilot Spaces, and MCP for the cloud agent — and where each one stops, see how to give Copilot cross-repo context today.) None of these is a dependency graph. None resolves an artifact to its consumers. The agent sees more files. It does not see how they relate.

The semantic retrieval index. This is Augment Code's Context Engine MCP. Augment indexes code across multiple repositories, runs the index locally, and exposes a retrieval interface (codebase-retrieval, codebase-search) that other agents can call via MCP. Augment publishes benchmark numbers showing real quality gains for downstream tools that wire it in. This is genuine substrate work. It answers questions of the form "find me code relevant to authentication" very well. The retrieval is semantic, with embeddings over code chunks, which means the index is excellent for navigation and comprehension. It is not, by design, a parser-derived index of how a Terraform module gets consumed by which Helm chart and deployed by which CI pipeline.

The code-symbol graph. This is Sourcegraph Cody. Cody sits on a code intelligence graph that understands symbols, including function definitions, references, and call paths, and supports queries across multiple repositories. "Where is this function used?" gets a precise answer that includes callers in repositories the user has not opened. This is closest to what the word "graph" implies, but it is a code-symbol graph, not an infrastructure-dependency graph. It is also enterprise-only since Sourcegraph discontinued the Free and Pro tiers in July 2025. Pricing starts at $59 per user per month, and the chat UI caps @-mention selection at ten repositories per query. Real product, with the scope its product design implies: code symbols, not infrastructure manifests.

The JS/TS project graph. Nx Synthetic Monorepos, announced in their 2026 roadmap, is the closest publicly-shipped equivalent to the architectural bet under Riftmap. Nx parses cross-repo dependencies into a workspace graph, runs a coordinator agent that walks the graph and spawns per-repo workers, and ships impact analysis and conformance rules across boundaries. This is the same shape of architecture. The ecosystem coverage is JavaScript and TypeScript first, with plugin-based extension to other languages, and the orientation is build orchestration and CI rather than infrastructure-as-code blast radius. Nx independently arriving at the same answer is, if anything, the strongest single piece of evidence that the substrate is the right architecture. Their product extends the JS/TS monorepo ecosystem across repository boundaries. It does not parse Dockerfile FROM lines, Terraform module sources, or Helm chart dependencies across twelve manifest ecosystems.

Each of these does something real. None of them is the artifact the vocabulary most directly describes.

The layer that hasn't moved

The thing the vocabulary points to most directly is a parser-derived, queryable dependency graph across the manifests that govern deployment. That means Terraform module sources and registries, Dockerfile FROM statements across registries, Helm chart dependencies, Kubernetes manifest references, Kustomize overlays, ArgoCD application sources, Go modules, npm packages, Python requirements, Ansible role dependencies, GitLab CI includes, and GitHub Actions workflow calls. Twelve ecosystems, give or take, that together encode how an organisation's software actually runs in production.

The question this layer answers is structurally distinct from the questions the four above answer. "Where is this function called?" lives in code symbols. "Find me code relevant to authentication" lives in semantic embeddings. "Which packages need to rebuild?" lives in the JS/TS workspace graph. "If I bump python:3.11-slim to python:3.12-slim, which services pull that base image, which Helm charts deploy those services, which CI pipelines need to retrigger, and which downstream Terraform modules reference the resulting images?" lives in the infrastructure-manifest graph. None of the four above will give you that answer, because none of them parses those files in that way.

Meta's tribal knowledge engine post named the cost of not having this layer at runtime. The "what depends on X" question costs roughly 6,000 tokens as a multi-file exploration and roughly 200 tokens as a single graph lookup. That is a thirty-times architecture-level efficiency gap on one of the most common planning questions an agent asks. The number is durable. It is not a model-quality problem and it does not close as context windows grow. It is the cost of reconstructing structure from grep every session instead of querying an index that already knows.

Meta built that index in-house. Mabl built theirs by hand, with 850 lines of registry maintained by a platform team across 79 repositories. Harness named it in their April essay on Source Context Management, framing it as "the blast radius of every change before it merges." Harness sells CD, so the post is content marketing rather than competing product. The architectural conclusion these three teams reached independently, that the dependency graph should be parser-derived, queryable as a primitive, and treated as runtime infrastructure rather than per-session context, is the conclusion Riftmap shipped a productised version of. The substrate the vocabulary now describes in product docs is the same one Mabl, Meta, and Harness named in engineering blogs. It is the one that has not yet made its way into any consumer AI coding product.

The CPO and the feature request

The clearest signal of where this category is going might be the asymmetry between what GitHub says and what GitHub ships.

In early December 2025, GitHub's chief product officer Mario Rodriguez named "repository intelligence" as the inflection point for 2026 in Microsoft's annual AI trends piece. The framing is direct: AI that understands code at the level of relationships and history rather than just lines of code. In Rodriguez's words, repository intelligence "will become a competitive advantage by providing the structure and context for smarter, more reliable AI." The phrasing is good. The category is real.

In March 2026, a GitHub user filed Discussion #189213, titled Feature Request: Cross-Repository Context for Copilot (Web ↔ Microservice), describing the exact problem the CPO is naming. Web app consumes microservice; service API changes; both repos need coordinated updates; Copilot should be able to see across the boundary. Three upvotes. Two months later, the discussion is still marked Unanswered. It is one specific feature request; I do not want to read too much into a single thread. But the asymmetry is concrete. The CPO of the dominant code platform names the category. The same platform's flagship coding product has not yet answered the feature request that defines it. That is the clearest signal I have found that the language is moving faster than the products.

Cursor's situation is similar in shape. The product is excellent within a single repo. The community forum has cross-repo feature requests from December 2025 and February 2026, both still open, both with the same pattern of users describing dependency relationships across repositories that the agent cannot see.

This is not an indictment of either vendor. It is a description of where the leading edge of a category sits when the language has crossed into mainstream product surfaces but the substrate has not. Vendors who use the phrase get credit for the diagnosis. Vendors who ship the layer underneath get credit for the category. The two are different things and right now they are owned by different people.

The window where that authorship gets decided is finite. Once a major vendor ships a parser-derived cross-repo dependency graph as a first-class feature, the category gets named after their product and everyone else becomes a comparison. That has not happened yet. It is the most interesting bet to be making over the next two quarters.

Where Riftmap sits

Riftmap is the productised version of the layer Meta, Mabl, and Harness have separately described. Twelve parser ecosystems today (Terraform, Dockerfile, Helm, Kubernetes, Kustomize, ArgoCD, Go, npm, Python, Ansible, GitLab CI, GitHub Actions), auto-discovered from a single read-only token, with more on the way. The roadmap extends the parser surface into contract layers (OpenAPI, protobuf, GraphQL) and schema registries, because the manifest plane and the contract plane are both part of the same dependency graph at runtime. No registry to maintain. No catalog YAML. The graph re-runs on every push; freshness is by construction rather than by process. Three endpoints (/repositories/lookup, /repositories/{id}/context, /repositories/{id}/impact) are designed to be called by an agent during planning rather than read by a human in a dashboard.

The position against the four above is not that they are wrong. Augment's semantic retrieval is excellent at what it does. Cody's code-symbol graph is excellent at what it does. Nx's synthetic monorepo is the right answer for organisations whose primary stack is JS/TS. The position is that none of them is the parser-derived infrastructure-manifest graph, because that is not what they were designed to be. The reader who needs that graph today either builds it like Mabl, runs it like Meta, or queries Riftmap.

The bear case

If a major model provider (Anthropic, OpenAI, GitHub) ships a platform-level MCP for cross-repo context as a standard feature, the API layer of this category gets commoditised fast. The defence against that scenario is the part that is hardest to copy: the breadth of the parser surface (twelve ecosystems is more work than it looks, particularly around private registries and transitive resolution), and the freshness contract (the index is parser-derived and re-runs on every push, which is structurally different from any context layer that depends on LLM summarisation). A platform MCP for cross-repo context would still need someone to actually parse the manifests. That work does not become easier because the agent has a new channel to call into.

The bull case

The bull case is the architectural choice underneath all of this, and it is the one I keep coming back to. Declarations are deterministic. A Terraform module source, a Dockerfile FROM statement, a Helm chart dependency, a GitHub Actions uses: reference: these are file-based facts. A parser produces the same graph for the same input on every run. There is no temperature, no top-p, no retry-and-hope-it-converges. The output is binary. A dependency either exists in the graph or it does not.

That has three consequences that compound over time, and they are why I think the deterministic-first architecture wins this category rather than loses it.

The first is testability. Every parser case is a fixture. "Given this Dockerfile with this ARG default, the graph should contain edge X→Y." You can write that test, run it in a millisecond, and pin the behaviour for the lifetime of the codebase. You cannot write that test against an LLM-extracted dependency graph; the same input produces different outputs across runs, model versions, and prompt revisions. The deterministic foundation makes the system improvable in a way that probabilistic extraction is not. Every false positive becomes a permanent test case. Every edge case becomes a permanent regression check. Improvement compounds.

The second is cost. A parser pass over a repository is microseconds and free. An LLM pass over the same repository is hundreds of milliseconds and bills per token. At organisation scale, with continuous re-scanning on every push, the cost gap is several orders of magnitude. The product that built its dependency layer on a deterministic foundation can offer it cheaply forever. The product that wired LLM extraction into the same loop pays a continuous tax that grows linearly with the size of the codebase and the frequency of change.

The third is what sits on top. The graph being deterministic does not mean AI has no role. It means AI sits on top of it for the things AI is genuinely good at: ranking, summarising, explaining, planning, prioritising. The agent calls /repositories/{id}/impact to get the deterministic blast radius, then uses the model to reason about which of the affected repos matter most, which changes are highest-risk, and how to sequence the work. The base layer is the part that needs to be correct. The reasoning layer is the part that needs to be flexible. The bet is that the right architecture for AI coding agents at scale is deterministic at the base and probabilistic at the top, not the other way around. I argued this case in more detail in the blast radius post.

The thing I most want to be wrong about is the timing. If the window is wider than two quarters, the bet is easier. If it is narrower, the next post should already be live.

Closing

The vocabulary moved. The CPO of the largest code platform on the planet has named the category. Several vendors use the phrase in their product surfaces. JetBrains coined a phrase for what AI ships without it. The language now describes a thing more precisely than most of the products that use the language actually deliver.

The layer the language describes is the parser-derived cross-repo dependency graph. It exists in Meta's in-house system, in Mabl's hand-maintained registry, and in Riftmap. It does not yet exist in the AI coding product that most readers of this post will reach for tomorrow. The window for that to change is open. The next two quarters decide who ends up owning what the language now promises.

Riftmap is the bet that whoever ships the deterministic substrate during this window, while the language is still being formed and before a major vendor consolidates the category, is the one whose product the language ends up describing.

If you're running AI coding agents across more than a handful of repositories and the language in their docs is starting to feel ahead of what they deliver, the layer underneath is the gap. You can build it yourself, the way Mabl did. Or you can start a free scan and let the parsers find it.

Sources referenced

Warp, Codebase Context — docs.warp.dev
Susanna Ray, Microsoft, What's next in AI: 7 trends to watch in 2026 — news.microsoft.com, December 8, 2025 (Mario Rodriguez on repository intelligence, section 6)
Augment Code, Context Engine MCP — augmentcode.com
Sourcegraph, Cody documentation — sourcegraph.com
Nx, Synthetic Monorepos — nx.dev
Nx, 2026 Roadmap: Expanding Agent Autonomy — nx.dev/blog, February 4, 2026
prateek-odev, Feature Request: Cross-Repository Context for Copilot (Web ↔ Microservice) — GitHub Discussion #189213, March 2026
Cursor Community Forum, Working on multiple repositories — forum.cursor.com, December 2025
Cursor Community Forum, Feature Request: Cross-Window / Cross-Repo Agent Communication — forum.cursor.com, February 2026
Engineering at Meta, How Meta used AI to map tribal knowledge in large-scale data pipelines — engineering.fb.com, April 6, 2026
Geoff Cooney, mabl, How We Built a System for AI Agents to Ship Real Code Across 75+ Repos — mabl.com, April 8, 2026
Ompragash Viswanathan, Harness, Your Repo Is a Knowledge Graph. You Just Don't Query It Yet. — harness.io/blog, April 1, 2026
Riftmap, AI Doesn't Understand Blast Radius: Why Change Failure Rates Are Up 30% — riftmap.dev/blog, April 19, 2026
Riftmap, You don't need a virtual monorepo. You need a graph. — riftmap.dev/blog, May 12, 2026
Riftmap, AI coding agents need cross-repo context — riftmap.dev/blog, May 12, 2026
Riftmap, Meta needed 50+ AI agents to map their tribal knowledge — riftmap.dev/blog, May 8, 2026

Appendix: structured summary

Claim: Vocabulary describing cross-repo dependency intelligence has crossed into vendor product documentation, but the layer the vocabulary most directly describes, a parser-derived cross-repo dependency graph across infrastructure manifests, has not yet shipped in any consumer-facing AI coding product. Four distinct things now sit under the same phrase: the workspace pattern (Warp, Cursor, Cline, Continue, Aider, Zed, Windsurf, GitHub Copilot, Claude Code), semantic retrieval (Augment Code's Context Engine MCP), code-symbol graph (Sourcegraph Cody), and JS/TS project graph (Nx Synthetic Monorepos). None of the four covers the infrastructure-manifest layer where deployment-time blast radius lives.

Evidence:

Warp Codebase Context docs, Augment Context Engine MCP product pages, Sourcegraph Cody @-mention semantics, and Nx Synthetic Monorepos in their 2026 roadmap all use the cross-repo vocabulary explicitly.
Mario Rodriguez, GitHub's chief product officer, named "repository intelligence" as the inflection point for 2026 AI in Microsoft's annual trends piece (December 2025).
GitHub Copilot Discussion #189213 (Cross-Repository Context for Copilot, March 2026) remained Unanswered two months after filing.
Cursor community forum has cross-repo feature requests open from December 2025 and February 2026.
Meta's published number: graph lookup for "what depends on X" costs ~200 tokens; multi-file exploration costs ~6,000. A ~30x architectural efficiency gap.
Mabl's 850-line Repo Coordination Graph spans 79+ repositories and is maintained by hand.

Architectural takeaway: The vocabulary leads the products by approximately two quarters. The kind of substrate the language most directly describes, a parser-derived infrastructure-manifest dependency graph across Terraform, Docker, Helm, Kubernetes, CI manifests, and other ecosystems, exists only in in-house systems (Meta), hand-maintained registries (Mabl), and Riftmap. The window for owning the productised definition of "cross-repo context" closes when a major vendor ships that layer.

Why deterministic-first wins: Declarations are deterministic. A parser produces the same graph for the same input on every run, which makes the system testable as fixtures, cheap to operate at organisation scale, and reliable to wire into agent planning loops. AI sits on top of the graph for ranking, summarising, and prioritising. The base layer is the part that needs to be correct; the reasoning layer is the part that needs to be flexible. The right architecture for AI coding agents at scale is deterministic at the base and probabilistic at the top.

Audience: Platform engineers, DevOps leads, and engineering managers running AI coding agents across multi-repo organisations, particularly those whose dependency graph crosses infrastructure-as-code boundaries.

What 208 kubernetes-sigs repos actually depend on

Daniel Westgaard — Sat, 16 May 2026 00:00:00 GMT

A scan of the kubernetes-sigs organisation, rendered as a graph: 208 repos, 1,128 cross-repo dependencies, and 153 repos that depend on yaml.

If you've worked on a Kubernetes operator, you have a rough mental model of how kubernetes-sigs fits together. controller-runtime and controller-tools at the framework layer, kubebuilder above them as scaffolding, cluster-api and its army of cloud providers off to one side, kustomize and kind as standalone tools, dozens of CSI drivers each doing their own thing, and an unglamorous foundation of small utility libraries (sigs.k8s.io/yaml, sigs.k8s.io/json, sigs.k8s.io/structured-merge-diff) underneath the lot.

What you probably haven't seen is what that mental model looks like rendered as a graph.

This is the second post in the series. The first scanned the Prometheus org with Riftmap and used it as a calibration target: 56 repos, well-understood, you could check the scanner against your own intuition. The shape mostly matched. kubernetes-sigs is the harder test. 208 public repos, structured very differently from Prometheus, no single owning team that holds the whole thing in their head.

The shape mostly matches here too. There are also a few specific things it doesn't see, which I'll get into below.

The biggest single observation, before any of the screenshots: kubernetes-sigs is a federation. Where Prometheus had a hub-and-spoke shape with client_golang and prometheus/common at the centre, kubernetes-sigs has a thin shared utility layer at the bottom and otherwise-independent projects on top. That's not a flaw in the scan. It's what a 208-repo SIG-governed org actually looks like.

The series has since scanned a third shape again: Cloud Posse turned out to be a keystone, one convention module holding up 61% of its 242 repos with a cliff and nothing in between. Three orgs, three genuinely different topologies.

The shape of the org at a glance

The numbers from a single scan: 208 repositories, 1,128 cross-repo dependencies, 528 distinct artifacts consumed somewhere in the org. The breakdown is heavily Go-skewed (857 Go module references, 257 git URL references, 8 GitHub Actions, 5 Kubernetes manifests, 1 Helm), which is what you'd expect for a Go-native operator ecosystem.

The top of the impact list reads about how a Kubernetes contributor would predict the bottom of it but maybe not the top:

kubernetes-sigs/yaml — 152 dependents
kubernetes-sigs/json — 142 dependents
kubernetes-sigs/randfill — 110 dependents
kubernetes-sigs/controller-runtime — 109 dependents
kubernetes-sigs/structured-merge-diff — 102 dependents

The calibration moment here isn't quite the same as Prometheus. With Prometheus the top of the ranking confirmed the mental model: prometheus/common, client_golang, client_model, the predictable centre. The top of the kubernetes-sigs ranking has controller-runtime where you'd expect it at #4, but the three repos above it are utility libraries most contributors couldn't pick out of a lineup. sigs.k8s.io/yaml is a thin wrapper around gopkg.in/yaml.v2 with some helpers. sigs.k8s.io/json is a small JSON marshaller. sigs.k8s.io/randfill is a randomised-value fuzzer used in test generation.

These three sit at the top because every operator-flavoured repo in the org imports them, directly or one hop away through controller-runtime or apimachinery, and Riftmap counts every direct import. The story isn't that they're surprising. It's that the most-depended-on things in a 208-repo Kubernetes org are not the ones with public-facing names. That's how shared infrastructure works.

The out-degree list tells a complementary story. Most-importing repos in the org:

#	Repo	Out-degree
1	`cluster-api`	29
2	`kueue`	29
3	`cluster-api-provider-aws`	29
4	`cluster-api-provider-azure`	27
5	`cluster-api-operator`	21

The cluster-api family dominates. Each provider imports the core, the shared utilities, and a dozen integration libraries. Combine the two rankings and you get the actual shape of the federation: a small utility floor at the bottom, controller-runtime as the framework layer, and the cluster-api family as the densest coordination cluster on top.

The graph view

The default graph view shows the kubernetes-sigs org after auto-clustering — all 208 repos folded into a navigable set of cluster nodes. The first thing worth noticing is what's missing. Prometheus's graph had eight tight clusters around clear anchors (common, client_model, procfs, exporter-toolkit, promci) and a single dense hub-and-spoke pattern. kubernetes-sigs has a much flatter shape. The cluster-api family forms a recognisable group. The CSI drivers form a loose constellation. The kubebuilder-adjacent repos cluster together. And a wide row of standalone projects (kind, kustomize, gateway-api, kueue, metrics-server) sit on their own.

That isn't a clustering failure. The auto-clustering groups repos with similar dependency profiles, and on kubernetes-sigs there genuinely are fewer profiles to find. Most cluster-api providers look like each other and cluster together. Most CSI drivers look like each other and cluster together. But kind doesn't look like kustomize, and neither looks like gateway-api, and the graph faithfully reports that.

The clustering is what makes 208 repos legible at this zoom. Without it you get a hairball. With it you can see, at a glance, which parts of the org are coupled and which parts are independent neighbours.

The pattern at the centre

I picked cluster-api for the focus-mode shot. controller-runtime would be the easier choice. It's the closest analogue to client_golang from the Prometheus post, with 109 in-org consumers radiating outward. cluster-api is more interesting. It sits at #10 on the in-degree ranking (38 dependents) but tied for #1 on out-degree (29 imports). That combination is rare. Most heavy importers aren't also heavy producers. Most central repos don't pull in two dozen of their siblings. cluster-api does both.

What focus mode shows: cluster-api sits in the middle of a two-sided neighbourhood. On the consumer side, the cluster-api-provider family (-aws, -azure, -gcp, -vsphere, -ibmcloud, -openstack, -cloudstack, and a long tail) fans in. On the dependency side, cluster-api pulls in controller-runtime, the shared utilities (yaml, json, randfill, structured-merge-diff), apimachinery integrations, and an observability subgraph including metrics-server.

You don't need to be a Cluster API maintainer to read this graph. A new engineer joining one of the provider teams could open it on their first day and see the coordination layer that ties their work to everyone else's, plus the upstream layer they share with cluster-api itself.

Where the receipts live

Click any node and the side panel opens with file-level evidence. For cluster-api the worth-pausing-on detail is this one: cluster-api consumes the metrics-server Helm chart at version 3.13.0, referenced from hack/observability/metrics-server/kustomization.yaml:5. Confidence 0.9.

That's not a Go module edge. It's a Helm chart referenced from a kustomization file, in a different repo, in a directory most contributors never open. The Prometheus post leaned hard on go.mod parsing: three separate go.mod files in prometheus/prometheus, each with its own pinned version of client_golang. Cross-ecosystem edges like the metrics-server one are where the cost of not having this kind of graph compounds. If metrics-server publishes a breaking change in the chart and cluster-api's observability hack directory still references 3.13.0, no Go tooling will flag it. The Helm chart edge sits at confidence 0.9 rather than 1.0 because chart references resolve through registry name matching rather than exact module paths. Across the full scan, 83% of edges resolve at confidence 1.0 and the rest at 0.6 to 0.9. The confidence is part of the receipt, not a hedge.

A second receipt worth noting, on the Go side: sigs.k8s.io/yaml is imported by 149 distinct repos via two raw module paths (sigs.k8s.io/yaml and github.com/kubernetes-sigs/yaml). Both resolve to the same artifact. 212 total declarations from those 149 unique repos. The gap is the multi-module monorepos importing yaml from several go.mod files. kubernetes-sigs/cluster-addons is the strongest example: it's a multi-module monorepo with submodules for bootstrap, coredns, dashboard, flannel, metrics-server, nodelocaldns and others. Each produces its own go_module artifact (sigs.k8s.io/cluster-addons/bootstrap, sigs.k8s.io/cluster-addons/coredns, and so on). Each submodule's yaml import is tracked separately. "We updated yaml in the root go.mod" and "we updated every reference to yaml" remain different statements.

One related quirk: cluster-addons' kubeproxy/go.mod declares module addon-operators/kubeproxy (no domain, no sigs.k8s.io prefix). Riftmap surfaces it exactly as declared. When you scan an org, the right behaviour is to report what's in source rather than to normalise it.

If I changed cluster-api, what breaks?

Toggle Impact Mode on the same focus view and the canvas lights up. Red cascade edges radiate from cluster-api through every repo in its blast radius. 38 repos affected at maximum depth 3: the seven cluster-api-providers you've heard of, the four you haven't (kubevirt, packet, hetzner, and a handful more), cluster-api-operator, cluster-api-addon-provider-helm, the standalone consumers like kueue, and a small transitive tail.

The side panel has the list with depth labels and the file:line that would need to change in each downstream. There's a Markdown export at the bottom. Click it and you get a copyable list of every affected repo with its evidence pointers, ready to paste into a deprecation announcement, a v1beta migration RFC, or a release-notes block. That loop, "show me the blast radius and let me hand the list to the team that owns each downstream repo," is the same workflow the Prometheus post described. The list is just longer here.

What Riftmap didn't see (and why)

Same honesty section as the Prometheus post. Three categories.

Real parser gaps. Riftmap can't currently parse:

pyproject.toml, requirements.txt, and setup.py, so the four detected Python packages in the org (inference-perf, jobset, k8s-agent-sandbox, kubespray_component_hash_update) show as produced artifacts but with no cross-org consumption resolved
Terraform module consumption from a downstream repo's module "x" { source = "..." } blocks. Riftmap detects produced Terraform roots and modules (6 and 4 respectively) but doesn't yet resolve the consumer side
Ansible playbook and collection consumption. Same pattern: 1 collection and 3 playbooks produced, zero consumption resolved
Cargo.toml, so the org's one Rust experiment sits unconnected

These are real, named gaps. They are roughly the next four on the parser roadmap, in that order. Current ecosystem coverage is documented in the auto-discovery write-up.

Correctly parsed, deliberately not drawn. Most CSI driver repos sit as leaves with low or no in-degree. aws-ebs-csi-driver, azuredisk-csi-driver, gcp-compute-persistent-disk-csi-driver and their siblings have no kubernetes-sigs consumers. That's correct. They consume k8s.io/... upstreams (different org) and external SDKs (aws-sdk-go, azure-sdk-for-go), and they produce their own container images that get consumed by cluster operators outside the org. Their dependency graph leaves kubernetes-sigs and never comes back. Drawing them as connected when they aren't would be the bug.

The GitHub Actions edge count is similarly low (8 in-org references) for the same reason. kubernetes-sigs repos overwhelmingly use actions/checkout, actions/setup-go, actions/cache from the actions/* org. Cross-org Actions inside kubernetes-sigs are genuinely sparse. The eight that exist are real.

The single in-org Helm edge looks low until you check the chart sources. kubernetes-sigs charts mostly depend on external bases (bitnami, cert-manager, ingress-nginx, prometheus-community), all of which live in other orgs. The one in-org Helm edge that exists is the metrics-server reference above.

Federation means less clustering. Riftmap's auto-clustering finds fewer cohesive groups on kubernetes-sigs than on Prometheus, and that reflects the org rather than a clustering shortcoming. cluster-api providers cluster tightly because they share dependency profiles. CSI drivers form a looser group. Standalone projects (kind, kustomize, gateway-api, kueue) cluster with whichever repos they happen to share imports with, which often isn't very many. The flat shape is the finding.

The polyglot Python packages are parser gaps. The unconnected CSI drivers are correct silence. Both look the same in the graph at first glance. They are not the same thing, and the difference is what the side panel is for.

Methodology, briefly

Before Prometheus and kubernetes-sigs, Riftmap was validated against two private adversarial test groups designed to mimic production orgs. The first (27 repos, 83 expected edges) covers 20 intentional edge cases: diamond dependencies, dual-artifact repos, nested CI includes, ARG-based Docker FROM lines, Terraform subdirectory syntax, COPY --from cross-repo references, and version lag across pinned consumers. The second (55 repos, ~135 expected edges across nine ecosystems) adds cross-language artifact reuse, circular Go module deps, multi-artifact single repos, dependency chains five levels deep, and unsupported-ecosystem node rendering. Both have hand-verified ground-truth edge lists. Every scanner change is tested against them.

The kubernetes-sigs scan completed in 13m 34s across all 208 repos, with 0 skipped and no errors. 83% of edges resolved at confidence 1.0 (exact path matches); the remainder at 0.6 to 0.9 (Helm chart references and Kubernetes image references that resolve through name matching rather than exact paths).

None of the heuristics involved in artifact resolution are public. The scan output is.

Two asks

If you work on a kubernetes-sigs repo and you spot something Riftmap got wrong about it, a missing edge, a misattributed version, a parser failure I should add to the roadmap, email me at daniel@riftmap.dev. I'll fix the parser and credit you in the follow-up.

If you're running something similar in your own org and want to see what your graph looks like, Riftmap is at riftmap.dev. The kubernetes-sigs scan took about 13 minutes for 208 repos. Yours probably finishes in a fraction of that.

You don't need a virtual monorepo. You need a graph.

Daniel Westgaard — Tue, 12 May 2026 00:00:00 GMT

In the past weeks, two engineers have published some of the most concrete writeups I've seen of how to give AI coding agents context across more than one repository. Owen Zanzal's The Virtual Monorepo Pattern (March 23, 2026) and Rafferty Uy's Repo-of-Repos (May 2, 2026). Both describe a similar shape of solution. Bundle your repos into a workspace folder. Hand the agent a system map. Ship.

Both posts are good engineering. They're worth reading carefully. They also describe the strongest version of an approach that stops working at exactly the scale where the problem starts to matter, and the failure mode is the kind that's painful to retrofit.

What follows is an argument with the pattern, not with the authors. Both posts are the kind of thing I want more of: specific, shipped, written from real use. The disagreement is about where the pattern's ceiling is, and what's worth building above it.

This is the third post in a loose series. The first looked at Meta's tribal knowledge engine and the structural-vs-semantic decomposition hidden inside it. The second walked through three teams converging on cross-repo context as runtime infrastructure. This one is about the alternative response, why I think it's a stopgap rather than a destination, and the asymmetric upgrade path that makes the difference matter.

What the workspace pattern gets right

Owen Zanzal's piece is the cleanest articulation. Three files in a workspace directory:

.repos, a bash script that clones every relevant repo into a structured local folder.
CLAUDE.md, a hand-written system map describing how services relate to each other.
README.md, a deeper narrative for why the system is structured the way it is.

He calls this the virtual monorepo pattern. The thesis line is the part worth taking seriously: "the problem isn't repo structure. The problem is context visibility. Your AI assistant doesn't need to live in a monorepo. It just needs to see one. You don't need a monorepo. You need a monorepo view."

I think that's a correct assessment, and it's the right diagnosis for most teams in this position. They do not actually want to migrate to a monorepo — and as I argue in monorepo vs polyrepo: the debate is measuring the wrong thing, the repo layout was never really the variable that mattered anyway. The migration cost is real, the political friction across teams is real, and the CI/CD changes are real. The workspace pattern delivers a wider context window without paying any of those costs. It's purely additive. It exists alongside the existing repo structure. Nothing breaks.

Rafferty Uy's repo-of-repos pattern, published a week ago, is a more polished version of the same idea, named after the agent (Tony) it powers. An outer "agent" repo pulls in all related repos under a repos/ folder as workspace folders, while commits still flow back to each underlying repo's own origin. He ships it as a GitHub template. He explicitly names three things that have changed in the last year that make the pattern work right now: context engineering is now a discipline, context windows got significantly larger, and "agents grep before they answer."

I want to single out the second of those because it's the load-bearing assumption of the entire pattern, and the rest of this post is going to push on it.

The load-bearing assumption

The workspace pattern works as long as two things hold simultaneously:

The bundled workspace fits in the agent's context window.
Grepping over that workspace is cheap enough that the agent reaches for it routinely.

Both of those hold for Owen Zanzal at 35 repos. They hold for Rafferty Uy at the size he describes. They will hold for many readers of this post. However, I don't think they hold at 200 repos, and the failure isn't gradual.

Frontier model context windows are around a million tokens at the upper end. A typical mid-sized service repository runs to several hundred thousand lines of code, much of it dependencies and tests. Bundle 200 of them and you don't fit. You don't fit in the next generation either, because organisations grow repos faster than frontier labs ship context length increases.

Even when the workspace fits in the window, the workspace doesn't load itself into the prompt. Agents grep before they answer, in Rafferty's framing. Grep is O(N) over workspace size. Asking "what depends on X" by grepping 200 repos costs token, time, and latency that doesn't scale, and the answer is fuzzy at best. Meta's published number on this is the cleanest data point in the public record: a graph lookup answers "what depends on X" in around 200 tokens, the same question by exploration costs around 6,000. That's a 30x reduction. It isn't a frontier-model problem. It's an architecture problem.

There's also a third issue, smaller in any single session but compounding over time. The CLAUDE.md system map at the heart of the workspace pattern is a hand-written context file. The Gloaguen et al. paper from ETH Zurich and LogicStar.ai (February 2026) studied this directly across four coding agents on 138 niche-repository tasks plus SWE-bench Lite. Their finding: developer-written context files give a marginal +4% improvement in agent success rate, at +19% inference cost. LLM-generated context files give a -3% effect at +20% cost. Across the board, "context files do not provide effective overviews." Agents take the same number of steps to find relevant files whether a context file is present or not.

That doesn't make CLAUDE.md useless. The +4% case is real. But it caps the upside of the pattern, and it makes maintenance non-negotiable. Owen Zanzal himself names this cost explicitly: "Keeping .repos in sync. New repos need to be added to the script. Repos that change names or move need to be updated. This is low-friction but not zero-friction." That's true at 35 repos. At 200, with five new repos a quarter, it is a part-time job nobody's job description includes.

How the pattern actually breaks

I want to be specific about how this breaks, because abstract failure modes don't land. Five concrete things go wrong as you scale.

One. The bundled workspace exceeds the context window. The agent silently truncates or the editor refuses to load the folder. You can mitigate this with multiple smaller workspaces scoped to different domains, which Owen Zanzal recommends as a workaround, but you've now manually re-implemented domain partitioning that the dependency graph would have given you for free.

Two. The agent grep over a 200-repo workspace becomes a 30x token tax on every "what depends on X" query. This isn't theoretical. Even Stripe, which has a real monorepo with hundreds of millions of lines of mostly Ruby code, doesn't dump everything into the agent's context. Their published architecture for the Minions agent system uses directory-scoped rule files that attach automatically as the agent traverses the filesystem, "rather than a single global context dump that would overflow any model's window." If Stripe at monorepo scale can't dump it all, neither can your virtual monorepo at 200 repos.

Three. CLAUDE.md decays. New service added, old service deprecated, schema changes, ownership boundaries shift. The system map drifts from reality. By the time someone notices, the agent has been confidently shipping changes against a stale model of the system. This is the failure mode Meta's engineering team named in their April 6 post on tribal knowledge: "context that decays is worse than no context." It's the reason their system uses a self-refreshing critic swarm. The workspace pattern has no equivalent, because nothing's running against it.

Four. Workspace gives the agent read access. It does not give the agent dependency awareness. The agent can grep through every repo in the workspace and still ship a change to the API repo that breaks the consumer it never opened that session. The cross-repo dependency graph is exactly the data structure that closes that gap, and grepping the workspace doesn't reconstruct it.

Five. You can't bolt the substrate on cheaply once the workspace pattern has settled in. Once teams are committing CLAUDE.md updates, scripts depend on .repos layout, and onboarding tells new engineers "open the agent workspace," migrating to a queryable graph is a second project, not a refinement of the first. The substrate has to exist before you need it.

The point both authors gesture toward but don't reach

Here's what surprised me when I read Owen Zanzal's piece carefully. His final section is called "Where This Pattern Can Go." It reads:

Auto-generating CLAUDE.md from service metadata, API contracts, and event schemas, keeping the system map current as the system changes.

Dependency graphs derived from import analysis, Terraform dependency trees, or event topic mappings, and feeding those into the AI context automatically.

Architecture doc generation as a CI artifact, so the README stays in sync with the actual system rather than drifting toward fiction.

That is the substrate. He has named it precisely. He has written the bullet points for what comes next. The only thing he hasn't done is build it.

This is the pattern with most workspace posts I've read. The author solves the immediate problem at their current scale, lists "auto-generated dependency graph" as future work, and ships. Rafferty Uy's repo-of-repos template assumes the agent grepping the workspace is the operating model and never asks at what scale grepping stops being affordable. Both posts are written for the scale where the workspace is the right level of investment. The substrate question opens up at a different scale, and neither author was writing at that scale.

I think the better read is: the workspace pattern is the stopgap, and the substrate is what it grows into. Specifically, the auto-generated dependency graph bullet at the end of Owen Zanzal's post is doing the load-bearing work. Without it, the pattern hits the maintenance ceiling somewhere between 50 and 100 repos. With it, the maintenance ceiling moves from "engineer with a weekend" to "platform that auto-discovers."

That second thing is what Riftmap exposes today. It's what Mabl built by hand into their 850-line Repo Coordination Graph in Part 1 and now extended to 100+ repositories with explicit blast-radius-for-tech-debt framing in Part 2. It's the cross-repo dependency index Meta produced as a byproduct of their tribal knowledge engine. It's what Harness, the CD vendor, called the "knowledge graph" that lets you see "the blast radius of every change before it merges" in their April 1 essay on Source Context Management. Four independent teams have built it or named it as a primitive in the past six weeks. The workspace pattern is the thing you ship while you wait for that primitive to exist for your stack. If it already exists, the pattern is the alternative bet, not the better one.

Stripe is the proof

If I had to pick one piece of evidence that the workspace pattern alone doesn't carry you, it's Stripe.

Stripe runs an internal coding agent system called Minions. As of February 2026, Minions produced over 1,300 merged pull requests per week, all written entirely by AI, all reviewed by humans. They run against Stripe's actual codebase, which is hundreds of millions of lines of mostly Ruby. Stripe is not 35 repos. They are the maximum case for what "monorepo plus large model" can do.

And it isn't enough. Stripe built an MCP server called Toolshed that exposes nearly 500 internal tools to Minions. They built directory-scoped rule files instead of a global context dump because, in their own published words, the global dump "would overflow any model's window." They built pre-warmed devboxes, deterministic verification gates, and a custom fork of Block's Goose agent. Signadot's piece Coding Agents Are Only as Good as the Signals You Feed Them puts it cleanly: "Stripe did not achieve this volume simply by pointing a large language model at its monorepo."

If the team with the world's most demanding monorepo can't simply bundle everything and let the agent figure it out, the bet that a virtual monorepo will solve it for the rest of us might be structurally unsound. The substrate is what you build because the workspace alone, even when the workspace is real, isn't where the leverage lives.

The asymmetric upgrade path

Here's how I think about the buy/build decision for teams in this range.

At 30 to 50 repos with one engineer who has a weekend. The workspace pattern is genuinely fine. Build it. Owen Zanzal's three files will get you most of the way. Rafferty Uy's repo-of-repos template will get you the rest. Don't overthink it.

At 100+ repos and growing. The workspace pattern is a maintenance bet you're going to lose. CLAUDE.md will decay, .repos will drift, and the agent will gain false confidence in stale information. The fix is structural, not procedural. The dependency graph derived from source code, refreshed on every push, is what closes the gap, and you want it before you need it.

At any scale, if the substrate already exists for your stack. The workspace is the alternative bet, not the better one. If Riftmap or something like it can already auto-discover your dependency graph from a read-only org token, the workspace pattern is solving by hand a problem you don't have to solve manually.

The asymmetry that matters is on the upgrade path. Going from no-workspace to workspace is a weekend. Going from workspace-with-decayed-CLAUDE.md-and-stale-dependency-bullets-in-prose to a queryable graph is a project. The migration tax goes up the longer you wait. "We'll do the graph later" is how teams end up with a context file they don't trust and a dependency model they have to recompute by reading.

Closing

Owen Zanzal's deeper principle from the closing of his post is "context beats structure for AI effectiveness." That's a good line and I agree with it as far as it goes. The structural codebase organisation isn't what determines whether an agent ships safe code; the context the agent has is.

The version of that principle I'd push for is one step further: structure beats context that has to be rewritten by hand. The kind of context that wins is the kind that updates when the code does, by construction, on every push. The workspace pattern delivers context. The substrate delivers context that doesn't decay.

I believe if you're going to invest in either, invest in the one that doesn't need a maintainer.

The architectural bet hasn't changed. Deterministic parsers first. Graph as the durable layer. AI as the layer on top, anchored to verified structure rather than reconstructing it from grep across a workspace that someone has to remember to update.

If you're running AI coding agents across more than a handful of repositories and finding yourself maintaining a CLAUDE.md that's drifting from reality, that's the gap. You can build the substrate yourself, the way Mabl did. Or you can start a free scan and let the parsers find it.

Sources referenced

Owen Zanzal, The "Virtual Monorepo" Pattern: How I Gave Claude Code Full-System Context Across 35 Repos — medium.com/devops-ai, March 23, 2026
Rafferty Uy, Repo-of-Repos: Tony's Multi-Repo Workspace for AI Coding Agents — raffertyuy.com, May 2, 2026
Ompragash Viswanathan, Harness, Your Repo Is a Knowledge Graph. You Just Don't Query It Yet. — harness.io/blog, April 1, 2026
Geoff Cooney, mabl, How We Built a System for AI Agents to Ship Real Code Across 75+ Repos (Part 1 of 2) — mabl.com, April 8, 2026
mabl, How We Built a System for AI Agents to Ship Real Code Across 75+ Repos (Part 2 of 2) — mabl.com, April 28, 2026
Engineering at Meta, How Meta used AI to map tribal knowledge in large-scale data pipelines — engineering.fb.com, April 6, 2026
Gloaguen et al., ETH Zurich and LogicStar.ai, Do Context Files Help Coding Agents? — arxiv.org/abs/2602.11988, February 2026
Signadot, Coding Agents Are Only as Good as the Signals You Feed Them — thenewstack.io, April 2026
Riftmap, AI coding agents need cross-repo context — riftmap.dev/blog, May 12, 2026
Riftmap, Meta needed 50+ AI agents to map their tribal knowledge — riftmap.dev/blog, May 8, 2026

Appendix: structured summary

Claim: Two patterns have emerged for giving AI coding agents context across multiple repositories. The workspace pattern (Owen Zanzal, Rafferty Uy) bundles repos into a local workspace and hands the agent a hand-written system map. The substrate pattern (Mabl, Meta, Harness, Riftmap) builds a queryable cross-repo dependency graph derived from source code. Both work at small scale. Only the substrate survives the transition past ~100 repos, because the workspace pattern's load-bearing assumptions (workspace fits the context window, grep is cheap, hand-written context stays current) all break at the same point.

Evidence:

Frontier model context windows top out around 1M tokens; 200 mid-sized service repos do not fit, and the next generation of models will not close the gap because organisations add repos faster than context lengths grow.
Meta's published data: graph lookup for "what depends on X" costs ~200 tokens; the same answered by exploration costs ~6,000. A 30x architecture-not-model gap.
Gloaguen et al. (arXiv:2602.11988): hand-written context files give +4% agent success rate at +19% cost. LLM-generated context files give -3% at +20% cost. Context files do not provide effective overviews.
Stripe Minions (1,300+ merged PRs/week, hundreds of millions of LOC): even with a real monorepo, Stripe uses directory-scoped rule files because a global context dump "would overflow any model's window." The Toolshed MCP server exposes ~500 tools to agents.
Harness, mabl, Meta, Riftmap (and adjacent: Augment, Depwire, Modulus) have all named the queryable dependency graph as a substrate primitive in the past six weeks.

Architectural takeaway: The workspace pattern is a stopgap with a known maintenance ceiling between 50 and 100 repos. The substrate is what it grows into. Owen Zanzal's "Where This Pattern Can Go" section names auto-generated dependency graphs from import analysis, Terraform trees, and event topic mappings as the next step; the substrate is exactly that, exposed as a queryable graph rather than as bullets in prose. The migration tax goes up the longer you wait, so substrate-first is the correct call for any team above 100 repos and any team that expects to be there within a year.

Audience: Platform engineers, DevOps leads, and engineering managers running AI coding agents across more than a handful of repositories, especially those weighing whether to invest in a virtual-monorepo workspace or in a queryable dependency substrate.

AI coding agents need cross-repo context. The teams running them at scale are already building it themselves.

Daniel Westgaard — Sun, 10 May 2026 00:00:00 GMT

Three weeks ago, the Cortex 2026 Engineering in the Age of AI Benchmark put incidents per pull request up 23.5% and change failure rates up roughly 30% since AI adoption accelerated. I wrote about that data and what it means for blast radius shortly after it landed.

What I underestimated at the time was how fast the language was going to shift. The phrase that's settled into the conversation since isn't "blast radius" or "service catalog." It's cross-repo context. And it's almost always being used in the same sentence as "AI coding agents." The reason becomes obvious once you read what teams operating AI coding agents at scale are publishing right now. They're not writing about AI making them faster. They're writing about the infrastructure they had to build so AI could ship safely across more than one repo at a time.

Three teams have published, in the last six weeks, the same diagnosis with three different solutions. The shape of what they're converging on is more interesting than any single one of them, and it has direct implications for how the rest of us should be thinking about agent runtime infrastructure.

What three teams just shipped

Neilos (@neil_agentic on dev.to), March 27. A solo founder running 15+ repositories across Go, Rust, TypeScript, Python, and C++, coordinating ten specialised Claude Code agents through Telegram. His post is How I Manage 15+ Repos with Claude Code (Without Losing My Mind). The diagnostic line is direct: you end up "copy-pasting context between sessions, manually tracking which PR depends on which, and babysitting agents that can't see the full picture."

His solution, called ttal, separates "read and explore" from "write." A lightweight exploration agent can read across any repository to gather context. Worker agents only ever write to one repository at a time, in isolated git worktrees. A manager agent holds the cross-repo plan in its head and routes work to the right repo at the right time. There's no dependency graph as a data structure. The cross-repo coordination lives in the manager agent's reasoning and a project registry that maps names to file paths.

Mabl, April 8. A team of 25 engineers managing 100+ repositories, pushing 200+ pull requests and 40+ production releases a month before AI acceleration. By February 2026, 39% of their commits were AI-assisted, 60% in infrastructure repos. Their post, How We Built a System for AI Agents to Ship Real Code Across 75+ Repos, describes a four-layer architecture. The layer that matters here is what they call "Cross Repo Base."

Inside Cross Repo Base sits a "Repo Coordination Graph": 850+ lines of structured registry covering 79 repositories with detailed dependency graphs, Pub/Sub topic maps, database table ownership, and prescribed release ordering. When an agent works on a cross-repo feature, it queries this graph to determine which repos need updates, what the merge order should be (upstream libraries before consumers), and which reviewers to tag based on CODEOWNERS and dependency chains. They report that without this layer, "every agent invocation required a human to provide context." With it, "context drift dropped from ~40% of our failures to <5%."

Meta, April 6. I wrote about the Meta tribal knowledge engine post earlier this week, so I'll keep this short. Meta built a multi-stage AI pipeline with 50+ specialised agents to map tribal knowledge across one of their large data pipelines. Buried near the end is the line that matters: "we generated a cross-repo dependency index and data flow maps showing how changes propagate across repositories. This turns 'What depends on X?' from a multi-file exploration (~6000 tokens) into a single graph lookup (~200 tokens)."

A 30x token reduction for one of the most common questions an agent asks during planning.

What's the same, what's different

The pain is identical. All three describe agents shipping locally-correct code that breaks consumers the agent didn't know existed. Mabl frames it as context drift. Meta frames it as tribal knowledge. Neilos frames it as agents who "can't see the full picture." The phenomenon is one phenomenon: the dependency graph that determines whether a change is safe lives outside any single repository's boundary, which means it lives outside the agent's context window.

The solutions diverge in a way that's instructive.

Mabl and Meta both built dependency graphs as a queryable substrate. Mabl's lives as a structured 850-line registry that agents consult at planning time. Meta's lives as a parser-derived graph index that agents call as a tool. The shapes are slightly different but the operating model is the same. Deterministic structure. Refreshed automatically (Mabl from registry updates and CODEOWNERS, Meta from re-parsing source). Queryable as a single lookup rather than a multi-file exploration. The graph exists separately from the agents and outlasts any single agent session.

Neil's ttal takes a different approach. The cross-repo information lives in the manager agent's working memory plus a TOML file mapping project names to file system paths, with the architecture isolating writes to one repo at a time and keeping the coordination model in the manager's prompt. This is well-fitted to a solo operator with ten agents and fifteen repositories. At Mabl's scale, the same problem reshapes the solution. Once you have 25 engineers across 79 repos, no single agent's context window is big enough to hold the coordination model and no manual registry stays current at that throughput, so the dependency model has to live outside any agent.

What I read into this is that the dependency graph as a queryable substrate isn't a stylistic choice. It's what falls out of the problem when you scale it. Three teams hit the same wall. Two engineered the substrate explicitly. One handled it through coordination, which is the right call at solo scale. Once the team running the agents grows past that, the substrate is what you build.

Why this should be a primitive, not something every team rebuilds

The Mabl post lists this layer almost matter-of-factly. The Meta post mentions it in one paragraph after sections on agent swarms and critic passes. Both teams treated it as table stakes for what they were actually trying to do. And in both cases, the structural layer is the cheapest, most reusable, most durable part of what they built. Mabl's CLAUDE.md per repo decays without a maintainer. Meta's LLM-generated context files decay without a self-refreshing critic swarm. The dependency graph doesn't decay, because parsers run on every push.

Which raises the question for every team that isn't Meta or Mabl: do you really want to be writing your own 850-line repo-coordination-graph.md by hand? And keeping it current as repos are added, archived, renamed, and refactored? At a 50-engineer org, this is a fully-loaded engineer-month of upfront work and an ongoing maintenance tax that nobody's job description includes. At a 200-engineer org, it's a dedicated platform team responsibility competing with everything else they could be doing.

This primitive belongs above any single team. The graph itself is structural, derived from source code, and identical in shape across orgs. The thing you actually want from it (which repositories import from which, who consumes which artifact, what's in the transitive blast radius of a change) is the same question whether you have 50 repos or 500. There is no good reason for every multi-repo org running AI coding agents to be writing their own version of this from scratch. It's a substrate, not a feature.

The vendors have since started shipping exactly this shape. GitLab Orbit, launched in June, is a queryable property graph of code symbols and SDLC objects that agents consult over MCP, which is the substrate argument made by the largest player in DevOps. What it indexes, and the infrastructure artifact layer it leaves unmapped, got its own post.

What this looks like as an API

Riftmap auto-discovers the cross-repo dependency graph from a GitHub or GitLab org via a single read-only token, parsing manifests across twelve ecosystems: Terraform, Docker, Helm, Kubernetes, Kustomize, ArgoCD, Go, npm, Python, Ansible, GitHub Actions, and GitLab CI (and more to be added in the future). The graph is queryable through an HTTP API designed to be called by AI agents during planning.

The natural agent flow is three calls. Given an agent working in a clone of github.com/myorg/payments-api:

# 1. Resolve the local clone URL to a Riftmap repo
curl -s "$RIFTMAP_BASE_URL/repositories/lookup?url=https://github.com/myorg/payments-api" \
  -H "X-API-Key: $RIFTMAP_API_KEY"

# 2. Hydrate context in one round-trip:
#    repo + dependencies + dependents + artifacts + freshness fields
curl -s "$RIFTMAP_BASE_URL/repositories/$REPO_ID/context" \
  -H "X-API-Key: $RIFTMAP_API_KEY"

# 3. Only when actually needed: transitive blast radius
curl -s "$RIFTMAP_BASE_URL/repositories/$REPO_ID/impact?max_depth=3&min_confidence=0.8" \
  -H "X-API-Key: $RIFTMAP_API_KEY"

Three calls to answer the questions Mabl's Repo Coordination Graph and Meta's dependency index were built to answer. The full schema is published at https://app.riftmap.dev/openapi.json. Fetch it once, hand it to your agent, and the rest is typed httpx or fetch calls. Python and TypeScript versions of these examples are in the agent integration docs, along with the freshness contract every response carries (last_scanned_at, last_commit_sha, last_activity_at, archived) so an agent can tell when the graph is stale and either warn the user or trigger a rescan.

This is the substrate today, exposed as an HTTP API. An MCP server and CLI are next, in that order, so any Claude Code, Cursor, or Cline agent can drop them in without orchestrating HTTP calls. The order and current state are tracked on the public roadmap page.

The interface outlasts the model

The reasonable objection at this point is: won't models eventually get good enough at cross-repo reasoning that none of this is necessary? Won't Claude 5 or whatever comes next just figure it out?

I don't think the question goes the way the objection assumes. Even granting that models keep getting better at cross-repo reasoning, three things stay true.

First, parsing the dependency manifests of a multi-repo organisation from inside a model's context window is doing a job a parser could do deterministically and cheaply. Even if a frontier model does it perfectly, it's still paying token cost on every invocation for what is structurally a precomputed lookup. Meta's 30x token reduction isn't a model-quality problem. It's an architecture problem. A graph index will always be cheaper to query than to reconstruct.

Second, models change every six months. The dependency graph doesn't. A queryable graph behind a stable API has the same shape whether the agent calling it is Claude 4.7, Claude 5, or whatever is running in 2027. The interface outlasts the model. Investing in the substrate is on a different time horizon to investing in any specific agent's context strategy.

Third, the freshness problem is structural. A model trained today does not know about repositories your team created last week. A graph derived from last night's scan does. As long as the rate of change in your repository graph exceeds the rate at which models retrain, that gap exists, and the substrate is how you close it.

What models getting better at cross-repo reasoning probably does change is what gets layered on top of the graph. Better semantic reasoning over verified structure. Better automated PR review against known consumer impact. Better natural-language interfaces to the graph itself. Those are real things, and they'll matter. They all sit above the substrate, not in place of it.

Closing

The three posts I started this with are the same shape of evidence I built Riftmap, just with bigger names attached. Engineers willing to spend real engineering time building a thing means the thing is needed. When three independent teams publish the same diagnosis in two weeks, the pattern is the pattern.

The architectural bet hasn't changed. Deterministic parsers first. Graph as the durable layer. AI as the layer on top, anchored to verified structure rather than reconstructing it from scratch. What's changed is who's confirming it publicly, and how much louder the confirmation has gotten.

If you're running AI coding agents across more than five or six repositories and finding yourself writing prompts that include cross-repo dependency information by hand, or reviewing PRs where the agent shipped a change that broke a consumer it didn't know existed, that's the gap. You can build the substrate yourself the way Mabl did, on the trajectory the Mabl post describes. Or you can start a free scan and skip the 850-line registry. Either way, the substrate is the substrate. It's the part that doesn't lie.

Sources referenced

Geoff Cooney, mabl, How We Built a System for AI Agents to Ship Real Code Across 75+ Repos [Part 1 of 2] — mabl.com, April 8, 2026
Engineering at Meta, How Meta used AI to map tribal knowledge in large-scale data pipelines — engineering.fb.com, April 6, 2026
Neilos (@neil_agentic), How I Manage 15+ Repos with Claude Code (Without Losing My Mind) — dev.to/neil_agentic, March 27, 2026
Cortex, Engineering in the Age of AI: 2026 Benchmark Report — cortex.io
Riftmap, AI Doesn't Understand Blast Radius — riftmap.dev/blog, April 19, 2026
Riftmap, Meta needed 50+ AI agents to map their tribal knowledge — riftmap.dev/blog, May 8, 2026

Appendix: structured summary

Claim: AI coding agents at scale need a queryable cross-repo dependency graph as runtime infrastructure. Three independent teams have just published the same diagnosis. Two built the substrate. The third handled it through coordination, which works at solo scale.

Evidence:

Neilos (ttal, Mar 27): solo operator, 15+ repos, 10 specialised agents. Diagnostic: "manually tracking which PR depends on which." Solution: coordination layer with manager/worker planes, fitted to solo scale.
Mabl (Apr 8): 25 engineers, 100+ repos, 39% of commits AI-assisted by Feb 2026. Solution: 850-line Repo Coordination Graph spanning 79 repositories, queried by agents at planning time. Reduced context drift from ~40% to <5% of failures.
Meta (Apr 6): cross-repo dependency index reduces "what depends on X" from ~6,000 tokens to ~200 tokens, a 30x efficiency gain.

Architectural takeaway: The dependency graph as a queryable substrate isn't a stylistic choice. It's what falls out of the problem when scale forces externalisation of cross-repo coordination. The graph itself is structural, parser-derived, and identical in shape across orgs, which makes it a primitive that should live above any single team rather than be re-implemented inside each one.

What Riftmap exposes today: auto-discovered graph across 12 ecosystems via a single read-only org token. HTTP API with /repositories/lookup, /repositories/{id}/context, /repositories/{id}/impact. Static OpenAPI schema at https://app.riftmap.dev/openapi.json. MCP server and CLI on the public roadmap.

Audience: Platform engineers, DevOps leads, and engineering managers running AI coding agents across more than a handful of repositories.

Meta needed 50+ AI agents to map their tribal knowledge. The most durable piece of their stack is the part you can build today.

Daniel Westgaard — Fri, 08 May 2026 00:00:00 GMT

In early April, Meta's engineering team published a piece describing how they used a swarm of 50+ specialised AI agents to map tribal knowledge across one of their large data pipelines: four repositories, three languages, 4,100+ files. The post has been making the rounds in platform engineering circles for good reason. It names a problem most polyrepo organisations live with quietly, and shows what an industrial-scale solution looks like.

I read it twice. I think there are actually two posts inside it. One is a complex AI orchestration story about agent swarms, critic passes, and self-refreshing context files. That's the one most takes have focused on. The other is a quieter architectural argument that gets one paragraph and is the more useful piece for everyone who isn't Meta.

This is about the second one.

What Meta actually built

Meta's pipeline is config-as-code: Python configurations, C++ services, Hack automation scripts working together across multiple repositories. A single data field onboarding touches six subsystems that must stay in sync. Pointing AI coding agents at this codebase produced predictable results. The agents would compile but be subtly wrong. They didn't know which "deprecated" enum values must never be removed because of serialisation compatibility. They didn't know that two configuration modes use different field names for the same operation, and that swapping them produces silent incorrect output. None of this was documented anywhere outside engineers' heads.

Meta's response was a multi-stage AI pipeline they call a "pre-compute engine." Two explorer agents map the codebase. Eleven module analysts read every file and answer five questions per module. Two writers produce 25–35 line context files. Ten or more critic passes do three rounds of independent quality review. Four fixer agents apply corrections. The output is 59 concise context files covering 100% of code modules, up from ~5% before. Every few weeks, the system self-refreshes: validates file paths, detects coverage gaps, re-runs critics, auto-fixes stale references.

The results, on a six-task evaluation, are real: roughly 40% fewer tool calls per task. Workflow guidance that used to take two days of asking engineers now takes 30 minutes.

I'm not going to argue with any of that. It's clearly working at Meta. But it works at Meta partly because Meta has a platform team large enough to build, run, and continuously maintain a self-refreshing critic swarm. That's not a small footnote. It's the whole reason the system stays trustworthy over time, and it's the part that doesn't transfer to a 100-engineer company.

The argument hidden in the article

Buried near the end of Meta's post, under the heading "What We Built," there's one paragraph that did more for me than the rest of the article combined. I'll quote it because it's the most striking number in the entire piece:

Beyond individual contextual files, we generated a cross-repo dependency index and data flow maps showing how changes propagate across repositories. This turns "What depends on X?" from a multi-file exploration (~6000 tokens) into a single graph lookup (~200 tokens).

That's a 30x reduction in token cost for one of the most common questions agents and engineers ask: if I change this thing, what else breaks?

Meta describes the dependency index almost as an aside, after the long sections on the agent swarm. But it's structurally different from everything else in their stack, and the difference matters.

The 59 context files are LLM-generated artifacts. They have to be quality-gated by critic agents, validated for hallucinations, and refreshed periodically because code drift makes them stale. That's why the self-refresh mechanism exists, and why it requires a platform team to run. Context that decays is worse than no context, by Meta's own admission.

The cross-repo dependency index is different. It's a structured graph derived from parsing actual source files. It doesn't need critic agents to validate quality because parsers are deterministic: the same input produces the same output. It doesn't decay between scans because it's not a snapshot of human-readable knowledge. It's a queryable index of what the code actually says. You re-scan on every push, and it's fresh by construction.

Two layers, two operating models. One is volatile and needs a maintenance team. The other is durable and maintains itself.

The paper Meta cited deserves a closer read

Meta acknowledges, briefly, a recent paper from ETH Zurich and LogicStar.ai (Gloaguen et al., February 2026) that found AI-generated context files reduced agent success rates on open-source Python repositories. Meta's response is reasonable: those repositories are already well-represented in model training data, so context files are redundant noise there. Their own codebase, with proprietary tribal knowledge, is the opposite case.

That's a fair distinction, but the paper's actual findings are richer than Meta's framing suggests, and worth engaging with directly.

Across four coding agents (Claude Code, Codex, Qwen Code, and a Codex variant) on 138 niche-repository tasks plus SWE-bench Lite, the paper found:

LLM-generated context files marginally hurt performance (-3% on average) while increasing inference cost by over 20%.
Developer-written context files marginally helped (+4% on average), still at +19% cost.
Context files do not provide effective overviews. This is a direct subsection title in the paper. Agents took the same number of steps to find relevant files whether a context file was present or not.
Context files lead to more exploration and testing, not less. Agents read more, search more, and test more when given a context file. They follow the instructions, but the instructions make tasks harder.
Stronger models don't generate better context files. The expected scaling story doesn't hold.

The paper's own conclusion: context files have only marginal effect on agent behaviour, and are likely only desirable when manually written.

The honest read of this is not "context files don't work." It's that even in the best case, they give a +4% improvement at +20% cost, and only when humans write them. For LLM-generated context files, which is what Meta's swarm produces, the average effect is negative.

A caveat in the paper's favour: the evaluation is Python-only. The authors note that niche languages with less training data representation might benefit more from context files. Meta's codebase includes Hack and C++ alongside Python. So Meta sits exactly at the edge of what the paper studies. Their case for context files is defensible, but it isn't cleanly contradicted by the paper either. The honest position is that the jury is still out on whether Meta's quality-gated, critic-validated context files clear the bar that naive /init commands don't.

A different decomposition of the same problem

Meta's five-question framework for module analysts is the most portable idea in their post. The questions are:

What does this module configure?
What are the common modification patterns?
What are the non-obvious patterns that cause build failures?
What are the cross-module dependencies?
What tribal knowledge is buried in code comments?

Look at these and you'll notice they decompose into two categories. Question 4 is a structural question. The answer exists in the source code itself, in import statements, configuration references, module declarations, and infrastructure-as-code definitions. Parsers can extract it deterministically. Questions 1, 2, 3, and 5 are semantic. They require interpretation: what is the intent behind this code, what patterns recur across changes, what isn't written down. These are LLM-shaped questions, and they're exactly the kind the ETH paper says context files struggle with.

This decomposition matters because it tells you where to invest first. The structural layer is cheap to build, deterministic, and stays fresh by construction. The semantic layer is expensive to build, requires quality gates, and decays without maintenance. If you have unlimited platform resources, you build both. If you have a small team, you build the structural layer first, because it gives you most of the leverage at a fraction of the cost, and because the semantic layer becomes more useful when it can anchor to verified structure.

There's a deeper architectural argument here too. When an LLM generates context about a codebase from scratch, it's discovering structure and writing prose about it. Hallucination lives in that gap. When an LLM generates context on top of a verified dependency graph, it's annotating known structure with semantic claims. The structural ground truth constrains what the LLM can plausibly say. That's a more reliable architecture, and it's only available to you if you've built the graph first.

What this means for teams without a platform team

If you have 50 to 500 repositories and a small platform team or no platform team at all, here's what I'd take from Meta's post.

You can't afford a self-refreshing critic swarm with 50+ specialised agents. You probably don't need one. The piece of Meta's stack with the highest leverage per dollar is the cross-repo dependency index — the structural layer the AI tooling community has started calling cross-repo context — and that's the piece you can have today without building any of Meta's orchestration layer. It's also the piece that gives you the freshness signal Meta argues is non-negotiable for trust ("context that decays is worse than no context"), because parsers run on every push and you can timestamp every edge in the graph.

The order matters. Build the structural layer first. Make "what depends on X" a 200-token graph lookup, not a 6,000-token exploration. Make blast-radius analysis a query, not an interview. Then, if you still want LLM-generated context on top, do it knowing the graph constrains what the LLM can say and the quality bar gets clearer.

Meta's post is genuinely useful evidence. It validates that tribal knowledge is the bottleneck for AI agents in proprietary codebases. It validates that cross-repo dependency mapping is the cheapest, most reusable primitive in any solution. It also, accidentally, makes a strong case that the rest of the stack is optional for everyone who can't afford to maintain it.

The graph is the substrate that doesn't lie. Everything else gets layered on top.

This is the architectural bet I made when I started building Riftmap: deterministic parsers first, graph as the durable layer, AI as a future enhancement that anchors to verified structure. If you're thinking about cross-repo dependency mapping in your own organisation, the glossary page is a good starting point.

Appendix: structured summary

Claim: Meta's tribal knowledge engine is two systems. A self-refreshing AI swarm that needs platform-team maintenance, and a cross-repo dependency graph mentioned almost as an aside. The graph is the durable substrate. The swarm is the volatile layer on top.

Evidence from Meta: Cross-repo dependency index reduces "what depends on X" from ~6,000 tokens to ~200 tokens, a 30x token efficiency gain. Self-refresh required for context files because "context that decays is worse than no context."

Evidence from Gloaguen et al. (arXiv:2602.11988, Feb 2026): LLM-generated context files reduce agent success rates by ~3% on average at +20% inference cost. Human-written context files improve success rates by ~4% at +19% cost. Context files do not provide effective overviews. Stronger models do not generate better context files. Evaluation is Python-only; niche languages may differ.

Architectural takeaway: Meta's five-question framework decomposes into structural (cross-module dependencies, deterministically extractable) and semantic (intent, patterns, undocumented knowledge, LLM-shaped). The structural layer is cheap to build and self-fresh. The semantic layer is expensive and decays. Build the structural layer first. The semantic layer becomes more useful when it anchors to verified structure.

Audience this is written for: Platform engineers, DevOps leads, and SRE teams at organisations with 50–500 repositories, polyrepo architectures, and mixed infrastructure-as-code. Especially those without a Meta-scale platform team.

The catalog maintenance trap: why service catalogs go stale

Daniel Westgaard — Thu, 07 May 2026 00:00:00 GMT

Backstage and the developer-portal category solve a real problem. The reason platform teams quietly abandon them is something different, and it points at the shape of what actually works.

Every few weeks I run into the same observation from someone in platform engineering: their team looked at Backstage, evaluated it seriously, maybe even ran a proof of concept, and walked away. The reason is rarely that it doesn't do what it advertises. The reason is that the work of keeping it running turned out to be bigger than the value it returned.

I've now heard this pattern in r/devops threads, in conversations with engineers who built their own internal alternatives, and most recently from a platform engineer who summarised his evaluation in a single sentence: the cost of maintaining it was bigger than what we got back.

That sentence has been bouncing around my head, because it names something I haven't seen named clearly. I'm calling it the catalog maintenance trap: the gap between what a service catalog promises and what it costs to keep it true.

What catalogs actually require

Backstage, Port, OpsLevel, and the rest of the developer-portal category are built around a simple model. Each service is described by a YAML file (in Backstage's case, catalog-info.yaml) that lists the service, its owner, its dependencies, links to runbooks, on-call rotations, and so on. The portal aggregates these files and gives the whole organisation a single pane of glass.

The model is clean. The trouble is the verb tense. The catalog describes the world as of the last time someone updated it. Every dependency added, removed, or renamed since then is invisible until a human notices and edits the YAML. Multiply that across a hundred repos and a few dozen engineers, and the catalog drifts faster than anyone wants to admit.

This isn't a Backstage flaw. It's a property of any system where the source of truth is a manually-maintained catalog. The same trap exists in any "register your dependencies in this file" approach.

Why teams stop maintaining it

The maintenance gradient is brutal. On day one, the catalog is shiny and motivating, and the platform team writes the first batch of YAML by hand. Over the next few weeks, two or three engineers add their services. Then onboarding starts to slow down. Then someone changes a dependency without updating the catalog. Then the dashboard shows an outdated graph. Then a new hire asks "is this accurate?" and the honest answer is "kind of, in places."

At that point the catalog has stopped being an authoritative graph and started being documentation that was supposed to be authoritative. Which is worse than not having it, because people make decisions on the assumption that it's accurate.

The platform team has three options at this stage:

Mandate catalog updates as part of every PR review. An organisational tax that nobody enforces consistently.
Build automation to keep the catalog current. Which is the actual problem, only now there's also a YAML schema in the loop.
Quietly let it rot and rely on tribal knowledge again.

Option three is what most teams converge on. Not because the platform engineers are lazy, but because the cost of options one and two exceeds the value of having a catalog that's accurate to within a week.

The two escape routes

When teams give up on the catalog, they tend to take one of two paths.

Path one: monorepo. Consolidate everything into one repository and let a build tool like Nx or Turborepo maintain the dependency graph implicitly. This works, but it isn't a tooling decision. It's an architecture decision that takes years to execute, often isn't feasible across business units, and doesn't help with the infrastructure dependency surface (Terraform, Docker, Helm, CI templates) the way it helps with application code.

Path two: do nothing. Accept that the dependency graph lives in the heads of the senior engineers. Ask around when you need to make a breaking change. Hope nobody on the relevant team is on holiday. This is what most organisations actually do, and it's also what creates the conditions for the three-hour Slack outage when a base image changes and six teams break in sequence.

Neither escape route is satisfying. The catalog promised to solve this problem, and the alternatives are either an architectural migration or institutional amnesia.

The thing the catalog model gets wrong

The catalog model assumes humans should be the source of truth about dependencies. They shouldn't be. The actual source of truth already exists, written down in machine-readable form, in the repositories themselves: Terraform source = "..." blocks, Dockerfile FROM statements, go.mod require directives, .gitlab-ci.yml include references, Helm Chart.yaml dependencies. The dependency graph is already declared. It's just declared across thousands of files in dozens of formats.

The work isn't getting humans to register a second copy in YAML. The work is parsing the declarations that already exist and stitching them into one queryable graph.

This is what auto-discovery means in practice. No catalog. No annotations. No PR template reminding people to update the manifest. The graph is read from the source files, and the source files are the ones engineers are already editing because they have to in order to ship code.

This is the difference between documentation that engineers are asked to maintain and a graph that maintains itself.

What this actually changes

Once discovery is automatic, the value proposition shifts. You stop selling "a place to write down what you have" and start selling "a query interface for the truth your repos already encode." The questions change too:

Not "is the catalog up to date?" but "what's the blast radius of changing this module?"
Not "did everyone fill in their YAML?" but "which repos still pin to the old major version?"
Not "who owns this service?" but "if I deprecate this artifact, which teams need to be in the room?"

These are the questions platform teams actually ask. The catalog model could only answer them if the catalog was perfect, which it never was. Auto-discovery answers them by skipping the catalog step entirely.

Where Backstage still fits

I want to be careful not to overclaim. Backstage genuinely solves problems that auto-discovery doesn't: service ownership across hundreds of services, documentation aggregation, templated scaffolding for new services, a unified frontend for on-call and runbooks. Those are real jobs, and a service catalog is a reasonable tool for them.

The mistake is using the catalog as the dependency graph. The catalog is good at things humans want to register on purpose (this service is owned by team X, on-call is via PagerDuty, the runbook is in Confluence). It is bad at things that change underneath every commit (the actual graph of what consumes what).

For dependency visibility specifically, the catalog model isn't the right shape. Something that reads the source and rebuilds the graph on every scan is.

What we built

I'm working on Riftmap because this is the gap I kept hitting at client engagements as a consultant, and it's the gap the engineers I talk to keep describing. Riftmap connects to a GitLab or GitHub org with a read-only token, parses the dependency declarations that already exist across Terraform, Docker, Helm, CI pipelines, Go, npm, Python, Ansible, Kubernetes, and Kustomize, and presents the graph with blast radius analysis. There is no catalog YAML to maintain. The graph rebuilds itself when repos change.

If your team has evaluated Backstage and walked away because the maintenance cost was bigger than the value, or if you're staring at that same trade-off right now, I'd be curious to hear about it. The pattern I described in this post is built from a small number of conversations and the consistent signal in r/devops and r/terraform threads. The more I hear from teams in this position, the better the tool gets.

If you're earlier in the decision and the question is still "is Backstage worth adopting at all?", the companion to this piece reframes that debate around adoption rather than cost — Spotify's own head of Backstage engineering puts external adoption at around 10% and explains why: is Backstage worth it?. And if you're actively evaluating alternatives, I wrote a separate triage of the "Backstage alternatives" question by the job that sent you looking — portals, managed Backstage, or a parsed dependency graph: Backstage alternatives in 2026.

You can try Riftmap free at app.riftmap.dev, or reach me directly at daniel@riftmap.dev.

If you've hit the catalog maintenance trap and want to compare notes, I'd genuinely like to hear how it went. Honest accounts of what worked and what didn't are the most valuable input I get.

What 56 Prometheus repos actually depend on

Daniel Westgaard — Sun, 26 Apr 2026 00:00:00 GMT

A scan of the Prometheus organisation, rendered as a graph: 56 repos, 197 cross-repo dependencies, and 25 repos that depend on client_golang.

Update (June 2026): The figures and screenshots below are from the original April 2026 scan (Riftmap v1.5). A fresh re-scan on 2026-06-25 (Riftmap v1.6.6) counts the org's coupling under a stricter, deduplicated canonical unit: 214 in-org cross-repo edges from 271 raw references, with client_golang resolving to 23 distinct in-org consumers. I broke down what that composition is actually made of — and why not one of those 214 edges is a code symbol — in I counted every cross-repo edge in two real orgs.

If you've worked with Prometheus, you have a rough mental model of how its 50-odd repos fit together: a core server, a client library, a constellation of exporters, some shared infrastructure. What you probably haven't seen is what that mental model looks like rendered as a graph, or what it tells you about the blast radius of changing any one repo.

I scanned the Prometheus org with Riftmap, the tool I built for mapping cross-repo dependencies. The point of starting here isn't to surface anything exotic. It's the opposite: Prometheus is well-known enough that you can check the scanner's output against your own intuition. If the shape doesn't match, the tool is broken.

The shape mostly matches. There are also a few specific things it doesn't see, which I'll get into below.

The shape of the org at a glance

The numbers from a single scan: 56 repositories, 197 cross-repo dependencies, 30 distinct artifacts being consumed somewhere in the org. The breakdown skews Go-heavy (122 Go module references, 35 Docker, 34 CI/CD includes, 3 npm, 3 Kubernetes), which is what you'd expect for a Go-native observability stack.

The top of the impact list reads about how a Prometheus contributor would predict it:

prometheus/common — 28 dependents
prometheus/client_golang — 25 dependents
prometheus/client_model — 23 dependents
prometheus/prometheus — 23 dependents
prometheus/exporter-toolkit — 22 dependents

If you'd guessed this ranking unprompted you'd have gotten most of it right. That's the calibration: the ranking confirms the mental model rather than challenging it. Where the graph starts paying for itself is one layer down, when you ask not just "what's central" but "what specifically depends on this, and through which file."

The graph view

The default graph view shows 35 nodes and 94 edges, after Riftmap's auto-clustering groups repos with similar dependency profiles. Eight clusters surface in this scan: a common cluster anchored on prometheus/common, a client_model cluster grouping the libraries that import the data model, a promci cluster for shared CI infrastructure, an exporter-toolkit cluster pulling in the exporters that depend on it, and a procfs cluster around the Linux process-level libraries. The remaining three are smaller groupings that the auto-clustering pulls out based on shared dependency profiles.

The bottom rows are the foundation: repos with no detected in-org edges. Some of those are intentional and I'll come back to them. The clustering is what makes 56 nodes legible at this zoom level. Without it you get the standard hairball graph that no one ever zooms into a second time.

The pattern at the center

This is the strongest single screenshot in the scan. Focus mode on client_golang strips the canvas down to that repo and its 25-repo neighborhood. Every Prometheus exporter you've heard of (alertmanager, node_exporter, blackbox_exporter, snmp_exporter, statsd_exporter, consul_exporter, memcached_exporter, mysql_exporter, haproxy_exporter, pushgateway) sits one edge away.

The pattern is exactly what the design intent says it should be: every exporter in the org imports the canonical Go client library. The graph captures it cleanly, and you can read the relationship from a single pane without grepping through 25 separate go.mod files.

This is also where the "external observer" framing earns its keep. You don't need a Prometheus maintainer to walk you through which repos depend on client_golang. A new engineer joining the org could open this graph on their first day and see the topology a senior engineer carries in their head.

Where the receipts live

Click any node and the side panel opens with the file-level evidence behind every edge. For client_golang: 4 in-org consumers, 58 external references resolved across go.mod, Dockerfile, and similar manifests.

The detail worth pausing on: client_golang shows up in the prometheus/prometheus repo three separate times, at exp/go.mod:6, go.mod:8, and tutorials/whatsup/go.mod:24. Three distinct go.mod files in one repo, each importing the same library, each tracked as its own reference with its own pinned version. If you've ever bumped a dependency in the root go.mod and forgotten the one buried in tutorials/whatsup/, this is the class of bug that hides in Go monorepos. Riftmap surfaces each manifest individually rather than collapsing them into a single repo-to-repo edge, specifically because "we updated the dependency" and "we updated every reference to the dependency" are not the same statement.

If I changed client_golang, what breaks?

Toggle Impact Mode on the same focus view from the previous section and the canvas lights up. Red cascade edges radiate outward from client_golang through every repo in the blast radius. 25 repos affected at maximum depth 2: 24 direct dependents and 1 transitive. Every exporter, the alertmanager, pushgateway, the test infrastructure repo, all visible in a single pane.

The side panel has the receipts. Each affected repo is listed with its depth label and the file:line of the import that would need to change. There's a Markdown export at the bottom of the panel. Click it and you get a copyable list of every affected repo with file references, ready to paste into a deprecation announcement, a migration RFC, or a release-notes block. That workflow, "show me the blast radius and let me hand the list to the team that owns each downstream repo," is the loop the tool is designed for.

What Riftmap didn't see (and why)

The "what we missed" section in a scan write-up matters more than any of the wins above. Two distinct things are happening in the bottom row of orphan repos in the graph, and the difference is worth being precise about.

Real parser gaps. Riftmap can't currently parse:

pom.xml and Maven coordinates, so client_java, client_java-benchmarks, and jmx_exporter come out unconnected
pyproject.toml and setup.py, so client_python shows no edges
Gemfile, so client_ruby and prometheus_api_client_ruby show no edges
Cargo.toml, so client_rust shows no edges

These are real, named gaps. The repos exist, they have published dependencies, and Riftmap's view of the org is missing their cross-repo relationships because the parsers don't exist yet. They are the next four ecosystems on the parser roadmap, in roughly that order. If you see something like this in your own org's scan, this is what it means. The current ecosystem coverage is documented in the auto-discovery write-up.

Correctly parsed, deliberately not drawn. Different category: lezer-promql shows up in the orphan row, but if you click into it the side panel reads "0 in-org repos · 5 external references" and lists every detected dependency: @lezer/generator ^0.15.2, @lezer/lr ^0.15.8, @rollup/plugin-node-resolve ^9.0.0, mocha ^8.1.3, rollup ^2.27.1. The npm parser ran. It read package.json. It extracted all five dependencies cleanly. They're just not in the Prometheus org, so they don't produce in-org edges, and the repo correctly appears as a leaf.

That distinction is the whole point of an in-org dependency graph: it tells you what your own changes cascade into, not what the entire npm registry contains. lezer-promql's dependencies all leave the org, so the graph faithfully reports zero in-org edges. That's a feature.

The polyglot client libraries are a parser gap. lezer-promql is correct silence. Both look the same in the graph at first glance. They are not the same thing.

This was the first org in the series, picked because its shape is easy to check against intuition. The scans since have found very different shapes on the same method: kubernetes-sigs came out a flat federation with no single load-bearing centre, and Cloud Posse a single keystone where one module holds up 61% of its 242 repos.

Methodology, briefly

Before Prometheus, Riftmap was validated against two private adversarial test groups designed to mimic production orgs. The first (27 repos, 83 expected edges) covers 20 intentional edge cases: diamond dependencies, dual-artifact repos, nested CI includes, ARG-based Docker FROM lines, Terraform subdirectory syntax, COPY --from cross-repo references, and version lag across pinned consumers. The second (55 repos, ~135 expected edges across 9 ecosystems) adds cross-language artifact reuse (one proto repo consumed by Python, Go, and npm), circular Go module deps, multi-artifact single repos, dependency chains five levels deep, and unsupported-ecosystem node rendering. Both groups have a hand-verified ground-truth edge list that every scanner change is tested against. The Prometheus scan completed in 2m37s across all 56 repos. None of the heuristics involved in artifact resolution are public; the scan output is.

Two asks

If you work on Prometheus and you spot something Riftmap got wrong about a repo you maintain, a missing edge, a misattributed version, a parser failure I should add to the roadmap, email me at daniel@riftmap.dev. I'll fix the parser and credit you in a follow-up.

If you're running something similar in your own org and want to see what your graph looks like, Riftmap is at riftmap.dev. The scan I ran on Prometheus took under three minutes. Yours probably takes about the same.

Change failure rate is up 30% — here's how to measure yours in an afternoon

Daniel Westgaard — Tue, 21 Apr 2026 00:00:00 GMT

A practitioner's guide to calculating your team's CFR without a vendor platform — the DORA formula, the SQL, and the AI-assisted vs human-authored split nobody is publishing yet.

Cortex's 2026 benchmark says change failure rate has risen about 30% industry-wide since AI coding adoption accelerated. The number has been quoted in every engineering newsletter I read. It keeps showing up in LinkedIn posts. I cited it myself in my last post.

Here's the uncomfortable follow-up question: what's yours?

Most platform teams I've worked with couldn't give me a number. They could estimate a direction — "it feels worse lately" — but the actual percentage wasn't anywhere. And without a number, the 30% headline is just other people's data. You can't improve what you haven't measured.

This post walks through how to compute your team's CFR in an afternoon using data you already have, and how to split it in a way nobody is doing yet: AI-assisted PRs vs. human-authored. You don't need a vendor platform for any of this.

What CFR actually measures

DORA's definition, lifted from the source:

The percentage of changes to production or releases to users that result in degraded service and subsequently require remediation — a hotfix, rollback, fix forward, or patch.

That's the whole thing. Three details matter and they're the ones most vendor posts get slightly wrong.

Only production counts. A test that fails in CI isn't a change failure. A canary that catches a bad deploy before it reaches real users isn't one either. If your release engineering is working, a lot of would-be failures never count — which is the point.

Remediation has to happen. A deployment that's merely suboptimal isn't a failure. The question is whether it needed a rollback, hotfix, fix-forward, or patch after the fact. "We wrote a Jira ticket" isn't remediation; "we pushed another deploy to fix the first one" is.

The denominator is changes, not deployments. If you push three deploys and two of them are fix-only remediations of the first, you made one change, not three. Fix-only deploys come out of both the numerator and the denominator — they are neither new changes nor new failures in the sense CFR measures.

So:

Number of changes   = Production deployments − Fix-only deployments
CFR                 = Failed changes ÷ Number of changes

DORA's 2025 report found that about 16.7% of teams maintain CFR at 4% or below — that's the elite band. Most teams sit well above it.

The 90-minute version

You need three things, all of which you already have somewhere.

1. A list of production deployments. From your CI (GitHub Actions, GitLab CI, Jenkins, CircleCI, Argo), filtered to production environment only, successful runs only. Most of these systems have an API or a database you can query. If you can get deployment_id, service, deployed_at, and commit_sha, you're set.

2. A list of production incidents. From PagerDuty, Opsgenie, Incident.io, your internal spreadsheet — wherever your on-call logs live. Filter to anything that required an engineering response. You want incident_id, service, started_at, and ideally the SHA or deployment that was identified as the root cause.

3. A rule for joining them. The simplest rule that works: an incident "belongs to" a deployment if the incident started within some window after the deployment, on the same service. A 24-hour window is standard; some teams use 48 hours for services with slow-burn failure modes. This isn't causal attribution — it's a proxy, and it's close enough.

Here's the shape of the query once both datasets are in the same place:

WITH changes AS (
  SELECT
    deployment_id,
    service,
    deployed_at,
    commit_sha
  FROM deployments
  WHERE environment = 'production'
    AND result = 'success'
    AND deployed_at >= '2026-01-01'
    AND NOT is_fix_only  -- exclude rollbacks/hotfixes
),
failed_changes AS (
  SELECT DISTINCT c.deployment_id
  FROM changes c
  JOIN incidents i
    ON i.service = c.service
    AND i.started_at BETWEEN c.deployed_at AND c.deployed_at + INTERVAL '24 hours'
)
SELECT
  COUNT(DISTINCT c.deployment_id)                       AS total_changes,
  COUNT(DISTINCT fc.deployment_id)                      AS failed_changes,
  COUNT(DISTINCT fc.deployment_id) * 1.0
    / COUNT(DISTINCT c.deployment_id)                   AS change_failure_rate
FROM changes c
LEFT JOIN failed_changes fc USING (deployment_id);

If your deployment tool doesn't track is_fix_only, the practical workaround is a convention — require engineers to prefix fix-only PRs with fix: or tag them with a fix-only label, and filter on that. The data gets better once you start asking for it.

Run the query over the last 90 days. That's your CFR. Longer windows are noisier; shorter ones are too volatile to trust.

The cut nobody is making yet

Here's where it gets interesting. The Cortex 30% number is an aggregate. It tells you the industry has gotten worse. It doesn't tell you which of your PRs are driving your team's number.

You can find out.

Tag your PRs. There are several reasonable ways:

PR label. Add an ai-assisted label manually at review time. Lowest overhead, most honest, relies on the author.
PR template checkbox. "Did you use AI coding tools in this PR?" as a checkbox that a small bot reads and labels accordingly. Works well for teams with a review culture that already uses templates.
Commit trailer. AI-Assisted: yes or a Co-authored-by: ... line pointing at a bot account. Survives rebases and is machine-readable.
Tool-reported attribution. Some tooling (Git AI's open standard on Git Notes is a good example) can record which ranges of a diff were model-authored at the source, before the PR is even opened. Heavier setup, higher fidelity.

Any of these is fine. The worst option is to defer tagging until you "find the right platform." Pick a convention, write it down, roll it out on Monday.

Once PRs are tagged, split the CFR query two ways:

-- AI-assisted PRs
SELECT ... FROM changes c
WHERE c.commit_sha IN (SELECT sha FROM ai_assisted_prs)
-- Human-authored PRs
SELECT ... FROM changes c
WHERE c.commit_sha NOT IN (SELECT sha FROM ai_assisted_prs)

Now you have two CFRs. Compare them.

If your AI-assisted CFR is meaningfully higher than your human-authored CFR — and, based on every public benchmark from the last six months, it probably is — you have your own version of the 30% number. Not an industry aggregate. Your team's aggregate, on your codebase, for your definition of failure. That number is the one that actually motivates change.

It's also a fair number in a way the industry stat isn't. If your AI-assisted CFR is lower than your human CFR, that tells you something real too — your team has figured out how to use these tools well, and the finding is worth internal publicity.

What to do with the number

I wrote most of this in the previous post, so I'll keep it brief.

The patterns that reduce CFR at teams I've seen up close are the boring ones. Smaller PRs. Trunk-based development with feature flags instead of long-lived branches. Canary deploys with automatic rollback. Strong ownership over shared infrastructure artifacts. And — the one most teams skip — visibility into the cross-repo blast radius of a change before it merges, so that the review can ask the right question rather than a generic one.

What doesn't work is adding process layers that slow every change without discriminating by risk. The goal isn't to slow the agents down; it's to route high-blast-radius changes through more scrutiny than low-blast-radius ones.

FAQ

How is change failure rate calculated?

CFR equals the number of failed changes divided by the number of changes, over a given time window. A failed change is a production deployment that required remediation — a rollback, hotfix, fix-forward, or patch. Fix-only deployments are excluded from both sides of the ratio because they aren't new changes.

What is a good change failure rate?

DORA's 2025 data suggests that about 16.7% of teams achieve a CFR of 4% or lower, which is the elite band. A CFR in the 0–15% range generally indicates a mature delivery process. Above 30% typically points at gaps in testing, release safety, or ownership clarity.

Should I include staging or pre-production failures in CFR?

No. CFR is a production-only metric by DORA's definition. A canary that catches a bad deploy before it reaches real users is a win, not a failure — counting it penalises the very controls you want teams to invest in.

How do I track AI-assisted code for CFR purposes?

The simplest approach is a PR label or commit trailer that engineers apply at authoring or review time. More sophisticated options include PR templates with a checkbox, bot-applied labels based on known AI-tool user accounts, and tools like the Git AI open standard that record AI-authored diff ranges in Git Notes. Perfect attribution is not required — a consistent convention used by the team is enough to split the metric meaningfully.

How long should my CFR measurement window be?

Ninety days is the usual default. Shorter windows (two to four weeks) are too noisy for most teams — a single rough week swings the number. Longer windows (six months or more) smooth out recent changes in your delivery practices and are slow to react to regressions.

Closing

A week of work, most of which is data plumbing you probably already have, gets you an honest CFR number and a split between AI-assisted and human-authored changes. That's a better starting point than any aggregate benchmark from any vendor report.

I'm building Riftmap to solve the other half of this — giving teams visibility into the cross-repo blast radius of a change before the CFR number moves. Auto-discovery across Terraform, Docker, CI templates, Helm, Go, npm, Python, Ansible, Kubernetes, and Kustomize. One read-only token. No YAML to maintain.

If this is familiar territory, reach me at daniel@riftmap.dev, or try a free scan at app.riftmap.dev.

Sources referenced

DORA, Software delivery performance metrics — dora.dev
Google Cloud / DORA, 2025 State of AI-assisted Software Development Report — dora.dev
Cortex, Engineering in the Age of AI: 2026 Benchmark Report — cortex.io
Swarmia, DORA change failure rate — what, why, and how — swarmia.com
Git AI open standard for AI authorship attribution via Git Notes — github.com/git-ai-project

AI Doesn't Understand Blast Radius: Why Change Failure Rates Are Up 30%

Daniel Westgaard — Sun, 19 Apr 2026 00:00:00 GMT

The data is in. Cortex 2026 puts change failure rates up ~30%. DORA 2025 found AI amplifies team weaknesses. Amazon's own memo called it "high blast radius." Here's why, and what to do about it.

In March 2026, Amazon's senior vice-president of eCommerce services sent a briefing note to engineers. The Financial Times got hold of it. The phrase that jumped off the page — and then onto every tech outlet over the next 48 hours — was "high blast radius."

The note described a pattern of production incidents at Amazon retail. Some were tied to AI coding tools. One contributing factor, per the internal document, was novel generative-AI usage for which best practices and safeguards were not yet fully established. A separately reported AWS incident from December involved Amazon's internal AI coding assistant, Kiro, deleting and recreating an entire environment when asked to apply a targeted fix. AWS spent roughly 13 hours getting the service back.

This is a big-tech company with world-class engineering culture, shipping outages that took customers offline — and the phrase their own leadership reached for was one every DevOps engineer recognises. Blast radius: the set of things downstream of a change that can fail when the change goes wrong.

The Amazon story isn't an outlier. It's what the data already predicted. The industry now has a name for the version of this that AI coding agents create: AI agent blast radius.

The numbers are in, and they're not good

Three reports published in the last six months agree on the pattern, even though they measure different things.

Cortex's 2026 Engineering in the Age of AI Benchmark. Pull requests per author up 20% year-over-year. Incidents per pull request up 23.5%. Change failure rates up roughly 30%. Nearly 90% of engineering leaders say their teams use AI coding tools, but only about a third have formal governance policies in place.

Google's 2025 DORA State of AI-assisted Software Development Report. Around 90% AI adoption across respondents, confirming the Cortex number. Roughly 30% of developers say they have little or no trust in AI-generated code. And Google's own framing of the central finding is blunt: AI is an amplifier, not a repair tool. Teams that already had strong testing and platform foundations saw AI make them faster and more stable. Teams that didn't saw the opposite. Across the board, AI adoption showed a negative relationship with delivery stability.

CodeRabbit's State of AI vs. Human Code Generation. Analysing production pull requests at scale, AI-generated code carried roughly 1.7x the issue rate of human code. Logic errors were worse. Security issues were worse. Performance issues — the kind that don't trip a test suite but degrade the system — were significantly worse.

A separate joint study from Sun Yat-sen University and Alibaba put 18 coding agents against 100 real-world codebases over 233 days. Passing tests once was easy. Maintaining a codebase for eight months without breaking it turned out to be the part AI agents fell apart on.

Stack Overflow's engineering blog noted in passing that 2025 saw more widespread outages and incident volume than any prior year on record. That's not solely an AI story — infrastructure keeps getting more complex — but the correlation is hard to ignore.

So, the top-line: teams are shipping more, faster, and breaking things in ways they don't always know how to fix. The velocity is real. The rework is also real. And the ratio has gotten worse.

What "blast radius" actually means

In software and infrastructure, the blast radius of a change is the set of everything downstream that depends on it, directly or transitively, and could break when that change lands. For the full treatment — what blast radius is, how to measure it, and how to contain it across the whole spectrum from one function to a cross-repo artifact edge — see the definitional guide to blast radius in software engineering. This post is the AI-agent case of it: why the agents in particular can't see the widest band.

If you edit a function inside a single repo and nothing else in the org imports it, the blast radius is one repo. If you rename a variable in a shared Terraform module, the blast radius is every repo that sources that module at any version where the rename takes effect. If you bump the base tag of a Docker image that's pulled by 40 Dockerfiles across the org, the blast radius is 40 services and whatever depends on them at runtime.

Blast radius isn't a property of the code you're editing. It's a property of the system around the code you're editing.

This is why the concept survives so well in post-mortems. When a change breaks production, the question is rarely "did the diff look correct?" It's almost always "who was consuming this, and did anyone tell them?"

Why AI coding tools can't see it

Here's the core structural problem: AI coding tools optimise for local correctness.

They read the file you're editing. They read files in the same repo, maybe the working set you have open. A capable agent will pull in repository search results, run tests, and iterate. A really capable agent might read the repository's README and infer some conventions. All of that happens inside a single repository's boundary.

The organisation-wide cross-repo dependency graph — which other repos import this module, which services pull this image, which pipelines include this template — lives outside that boundary. It isn't in the training data. It isn't in the agent's context window. It isn't in any of the tools the agent has available unless someone has explicitly built those tools and wired them up. This is not specific to one product: I measured Claude Code, Cursor, and GitHub Copilot against exactly this question, and none of the three resolves cross-repo blast radius on its own — the limit is structural, not a matter of which assistant you pick.

To the AI, the code is a text to transform. To the system, the code is a contract with unknown counterparties. Those two framings disagree often enough that Cortex can measure it in the aggregate — a 23.5% lift in incidents per PR — and Amazon can experience it in the specific, as a 13-hour AWS recovery and a mandatory engineering meeting.

This is why the gap widens as you ship more AI-assisted code. Each individual change looks fine locally. Each change is merged against the same tests it's always been reviewed against. But the blast radius of each change was never something the tests were measuring in the first place.

Why tests don't save you

There's a reasonable objection at this point: if the tests pass, surely that catches most of it?

No. And this is one of the more uncomfortable findings of the last year.

When the same model writes both the feature and the tests, the tests share the model's assumptions. They exercise the code the way the model already imagined the code would be exercised. Cases the model didn't anticipate are cases the tests don't cover. This isn't hypothetical — it's been observed empirically by teams measuring AI-authored test coverage against production incidents, and it's consistent with what the Alibaba long-horizon study found: agents that passed benchmarks on day one fell apart over eight months of real maintenance.

Tests also run inside a single repository's CI. They can't run consumer services that live in other repos. A Terraform module's unit tests can't tell you that a staging environment in another repo will fail to plan after your variable rename. A Docker base image's integration tests can't tell you that a worker service in another team's repo pins to the previous tag and will fail its next rebuild.

Your test suite is a local safety net. Blast radius is an organisational problem. These are different layers, and the industry has not been investing in the organisational one.

The three failure modes I see most often

I've been building Riftmap for about a year, which means I've spent a lot of time looking at real cross-repo dependency graphs in real orgs. When AI-assisted changes break things, the failure almost always lands in one of three modes.

1. The shared library refactor with unknown consumers

An engineer asks an AI agent to clean up an internal library — rename a function, tighten a type, remove a deprecated parameter. The agent does it cleanly. The repository's own tests pass. The PR gets merged.

Three hours later, two other services fail their next deploy because they were still calling the old signature. Nobody on the originating team knew those services existed. The agent certainly didn't.

This is the exact shape of most internal Go module, Python package, and npm package breakages I see. The library repo's test coverage was strong. The problem was that "strong test coverage" meant something different from "known consumer coverage."

2. The base image bump with silent pins

An engineer asks the agent to upgrade a shared Docker base image — new language runtime, new security patches. The Dockerfile in the base image repo builds fine. The CI goes green.

Meanwhile, 30 downstream Dockerfiles across the org pinned to the old tag explicitly, and nobody notified them. Or, worse, they pinned to :latest and started pulling the new base silently, and three of them have a binary incompatibility with the new glibc. The outages happen at random times over the next week as each service rebuilds.

3. The Terraform module rename that breaks plans across the org

An engineer refactors a shared VPC or IAM module. The agent renames subnet_ids to private_subnet_ids because it's clearer. The module's examples still work; its own tests still pass.

Fourteen other repos source that Terraform module and pass the old argument name. Their next terraform plan fails. If they were on autopilot pipelines, they might not notice until the next deployment window. If any of them were in the middle of incident response, they now have an extra incident to deal with.

These three patterns repeat across every ecosystem I've looked at — Helm chart value renames, GitHub Actions workflow input changes, reusable CI template variables, Kustomize patch paths, Ansible role parameters. The shape is always the same: the change is correct locally, and the consumers weren't in the room.

What to put between the AI and main

The honest answer is that you don't stop AI-assisted changes from landing in production — that ship has sailed in almost every org that has adopted these tools, and the Cortex and DORA data suggest forcing it into reverse isn't where the productivity math lands. The question is what you put between the agent and main so that blast-radius-class mistakes get caught before they cost you a weekend.

Four things actually help, based on what I see working and what the governance data says is missing at most orgs.

A current, queryable dependency graph across your orgs. Not a YAML catalog that humans maintain. Not a nightly grep script. A system that scans your repos and parses the actual manifests, resolves the consumer-producer relationships, and stays fresh. This is the thing most teams don't have, and it's the thing that makes everything else possible.

PR-time blast radius diffing. When an agent opens a pull request against a shared module, image, chart, or CI template, the review surface should include who consumes this, at which version, and which consumers are affected by this specific change. Not a generic "this module is used a lot" notice. A diff of the consumer impact. This is the single highest-leverage gate you can add.

Automatic downstream owner notification. The humans who own the services that depend on the changed artifact need to hear about the change at the moment it's proposed, not the moment it breaks. Every platform engineering team will tell you this is already their life; formalising it removes the step where the change slips past because the right person was on leave.

A policy split between low-risk and high-risk surface area. Amazon's post-incident response was to require senior sign-off on AI-assisted changes made by junior and mid-level engineers. That's one blunt answer. A better one, if you have the graph, is: automatic merge allowed for changes with a blast radius under some threshold (single repo, no external consumers), human senior review required for changes that touch shared artifacts with N+ downstream consumers or services tagged as customer-critical. The agent gets the speed where speed is safe. The humans get the attention where attention matters. This split is no longer a proposal — the CI recipe that implements it is about forty lines, on GitLab CI or GitHub Actions.

None of these are novel ideas. The reason most teams haven't implemented them is that the foundation — the cross-repo dependency graph — doesn't exist in their org yet. Without it, every other gate is a judgement call made by whoever's reviewing the PR, and judgement calls scale poorly when PR volume is up 20% year on year.

FAQ

What is "blast radius" in software engineering?

Blast radius is the set of downstream systems, services, or repos that depend on the thing you're changing and could fail when the change lands. It's a property of the dependency graph around your code, not of the code itself. A change to a function nobody else calls has a blast radius of one; a change to a shared Terraform module sourced by 40 repos has a blast radius of 40.

Does AI coding raise change failure rate?

Yes, in the aggregate, based on every major 2025–2026 report that has measured it. The Cortex 2026 Benchmark puts change failure rate up about 30% and incidents per PR up 23.5% since AI adoption accelerated. Google's 2025 DORA report found AI has a negative relationship with software delivery stability overall, with the worst effects in teams that lacked strong testing and platform foundations before adoption. CodeRabbit measured roughly 1.7x the defect rate in AI-generated code versus human-written code in production pull requests.

Why does AI-generated code break in production more often than human-written code?

Three structural reasons. First, AI tools optimise for local correctness within a single repository and can't see the organisation-wide dependency graph — which repos import this module, which services pull this image. Second, AI-authored tests share the same blind spots as AI-authored code, so passing tests doesn't mean the change is safe. Third, review processes haven't scaled to match PR volume, and larger PRs with less review time let more blast-radius-class defects through.

What's a "high blast radius" incident?

It's an incident whose effects reach far beyond the immediate change — taking out multiple services, customer-facing endpoints, or critical paths rather than a single component. The phrase entered mainstream tech press when Amazon used it in an internal March 2026 briefing note about a pattern of production incidents tied partly to AI-assisted changes. The contrast is with a low-blast-radius incident that affects one service and is contained quickly.

How do you stop AI-generated changes from breaking production?

You can't eliminate the risk, but you can gate it. The most effective controls are: maintain a current cross-repo dependency graph so you know who consumes what; surface consumer impact as part of the PR review for changes to shared artifacts; automatically notify downstream owners when upstream artifacts change; and apply stricter review requirements (human senior sign-off, staged rollouts, canaries) to changes whose blast radius exceeds a defined threshold.

Closing

A lot of the public conversation about AI coding has settled into two camps: evangelists who think the velocity gains speak for themselves, and sceptics who think the whole thing is a productivity mirage. The data is more interesting than either position. AI coding tools genuinely make individual engineers faster. They also increase the rate at which changes break things in production. Both are true at once, and the second effect is largest in exactly the area the tools are structurally unable to see — the cross-repo dependency graph.

The Cortex report frames this as a governance gap. The DORA report frames it as an amplification effect. Amazon's post-incident response framed it as a blast-radius problem and a review policy problem. They're all describing the same hole in the stack.

If you maintain shared infrastructure artifacts — Terraform modules, Docker base images, Helm charts, CI templates, Go modules, anything others consume — the single most useful thing you can do in 2026 is build the visibility layer that your AI coding tools and your CI pipelines don't have. Know who consumes what. Know what this change affects. Make it a PR-time artifact, not a tribal-knowledge artifact.

That's what I'm building Riftmap to do: auto-discover cross-repo dependencies across your GitLab or GitHub org — Terraform, Docker, CI templates, Helm, Go, npm, Python, Ansible, Kubernetes, Kustomize — and give you a queryable graph with visual blast radius analysis. One read-only token. No per-repo YAML to maintain.

If you're feeling this problem at your org, I'd genuinely like to hear how it shows up. Reach me at daniel@riftmap.dev, or try a free scan at app.riftmap.dev.

Sources referenced

Cortex, Engineering in the Age of AI: 2026 Benchmark Report — cortex.io
Google Cloud / DORA, 2025 State of AI-assisted Software Development Report — dora.dev
CodeRabbit, State of AI vs. Human Code Generation Report (2025)
Sun Yat-sen University & Alibaba, long-horizon benchmark of 18 AI coding agents on 100 codebases over 233 days (2026)
Financial Times reporting (March 2026) on Amazon's "high blast radius" internal memo, covered in CIO.com, Fortune, Tom's Hardware, and Business Insider
Stack Overflow engineering blog on 2025 outage volume

How to Find Every Consumer of Your Go Module

Daniel Westgaard — Fri, 17 Apr 2026 00:00:00 GMT

You maintain a shared Go module. A breaking API change is coming. Which repos across your org import it — and at which version?

You own github.com/company/platform-lib. Maybe it's your internal observability library that every service imports for structured logging and trace propagation. Maybe it's a shared HTTP middleware package that standardises authentication, rate limiting, and request IDs across all your APIs. Maybe it's a configuration loader that services use to pull settings from your config management system at startup.

It started as a few shared utilities to avoid copy-pasting. Twenty services adopted it. Then more. Some import it directly and call into it heavily. Some pull it in transitively because another shared library depends on it. Some are on the latest version. Some are three majors behind.

Now you need to change it. Maybe you're removing a deprecated function that's been generating noise in the godoc for two years. Maybe you're bumping to v2 because you need to restructure the package API in a backwards-incompatible way. Maybe you're changing the signature of a middleware constructor to accept an options struct instead of positional arguments.

The question is the same one that runs through every post in this series: which repos across the org import this module, and at which version?

The scenario

Here is what Go module consumption looks like in practice. Your platform team publishes a module, and other repos declare it in their go.mod:

// service-a/go.mod
module github.com/company/service-a

go 1.22

require (
    github.com/company/platform-lib v1.8.3
    github.com/company/auth-middleware v2.1.0
)

Some repos import the module directly and use it throughout their code. Others pull it in as an indirect dependency — because a library they depend on imports your module — and Go records it with an // indirect comment:

require (
    github.com/company/platform-lib v1.8.3
    github.com/company/some-other-lib v0.4.1 // indirect
)

Some repos are pinned to a specific release tag. Some reference a pseudo-version pointing to a specific commit:

github.com/company/platform-lib v0.0.0-20260301153042-a1b2c3d4e5f6

Some have overridden the module source entirely with a replace directive — pointing to a local checkout or a patched fork:

replace github.com/company/platform-lib => ../platform-lib

All of these represent consumption of your module. None of them look the same. And right now, they live in different repos, owned by different teams, that you probably can't enumerate off the top of your head.

What existing tools give you (and where they stop)

pkg.go.dev

pkg.go.dev is the official Go package documentation and discovery site. For public modules, it indexes which packages import a given package and shows an importer list. This is the closest existing tool to "who uses this?"

The limitation is sharp: pkg.go.dev only indexes public modules fetched through the public Go module proxy at proxy.golang.org. If your module is hosted on an internal GitLab or GitHub instance, protected by authentication, and routed through a private GOPROXY, it does not appear in pkg.go.dev at all. Every consumer in your org is invisible to it.

For most platform teams managing internal shared libraries, this makes pkg.go.dev entirely useless for the question at hand. Even for public modules, the importer list only covers packages that pkg.go.dev has itself indexed — not a comprehensive count of every organisation that imports the module.

`go mod graph`

The go mod graph command prints the full module dependency graph for the current module — a recursive list of every direct and transitive dependency. It's useful for understanding what a single module pulls in.

But it only works outward from the current module. There is no go mod reverse-graph. You'd have to clone every repo in the org, run go mod graph in each one, collect the output, and invert it yourself — which is exactly the manual trawl the question is trying to avoid. And the moment you finish, the results are stale.

Renovate and Dependabot

Both Renovate and Dependabot support Go modules as a first-class ecosystem. They detect require entries in go.mod and open pull requests when newer versions are published — which means they implicitly know which repos consume which modules.

But they don't expose that knowledge as a queryable view. You cannot ask Renovate or Dependabot "show me every repo in the org that imports platform-lib, and what version each is on." They react to new versions being published. The reverse — who's consuming the current version before you publish a breaking one — is not something they surface.

Both tools also only cover repos where they've been configured. A team that hasn't set up Go module support in their config, or doesn't use either tool at all, is invisible.

GitHub code search

You can search for your module path across all repos in an org:

org:my-org "github.com/company/platform-lib"

This finds go.mod files that contain the module path and gives you a list of repos. For a one-off audit, it's a workable starting point.

The familiar problems apply: results don't include version numbers without opening each file individually, the search index lags behind recent commits, and it doesn't account for replace directives. If a repo has replaced your module with a fork or local path, the require entry still appears — but what's actually being compiled is different. Code search can't tell you that.

Athens (GOPROXY)

Athens is a widely-used open-source Go module proxy that organisations run internally for private modules and caching. It serves module downloads and maintains a local cache.

Athens tracks which modules were fetched and at which version. What it doesn't track is which source repo triggered the download. A build server fetching platform-lib v1.8.3 is recorded as a download event, but not which team's CI pipeline it was, which service repo it was building, or which go.mod declared the dependency. Athens is a supply-chain cache, not a consumption graph. This is the same gap every private registry has — the npm version of it, where a download event is not the package.json that declared the dependency, gets its own post in this series.

Why this is harder than it looks

Major version suffixes create distinct module identities. Go's module system treats github.com/company/platform-lib and github.com/company/platform-lib/v2 as completely separate modules. A repo that imports platform-lib/v2 has a different dependency than one that imports platform-lib. Grepping for platform-lib finds both — but a tool that tracks module identities needs to recognise that these are different versions of the same thing, and that consumers may be on any combination of v1, v2, v3.

This also means publishing a new major version doesn't automatically affect v1 consumers. They continue importing the old module path until they explicitly update both the go.mod entry and all import paths in their source code. Understanding who's still on v1 requires knowing who's importing which module path — and treating those as a unified dependency family.

replace directives obscure the real source. A replace directive can substitute your module with a different source — a local path, a fork, or a different module entirely:

replace github.com/company/platform-lib => github.com/company/platform-lib-patched v1.8.3-hotfix

From the outside, the require entry still references github.com/company/platform-lib. A scanner that reads only require entries sees this as a consumer on v1.8.3. But the code being compiled is coming from a patched fork. The apparent consumer is not actually running your module — and a tool that reports it as one gives you a misleading picture of who's affected by a change to the canonical source.

Indirect dependencies inflate the consumer list. Go's go.mod includes both direct and indirect dependencies, with // indirect annotations on the latter. If your module is a transitive dependency — imported by a library that's imported by a service — it appears in that service's go.mod even though the service's code never directly calls into yours.

This matters when reasoning about impact. A service that directly imports your module and calls its functions will break if you change the API. A service that has it only as an indirect dependency may not be affected at all, depending on how much of your interface the intermediate library exposes. Treating all go.mod entries as equivalent overstates the blast radius; ignoring indirect entries understates it.

go.work workspaces cross module boundaries. Go 1.18 introduced workspace mode, where a go.work file at the root of a checkout declares multiple local modules as part of a unified workspace. When workspace mode is active, dependencies between modules in the go.work are resolved locally rather than through go.mod require declarations.

Some consumers of your module may be developing against it in a shared workspace, with no explicit require entry in their go.mod during development. A scanner that only reads go.mod files misses these entirely.

Vendor directories shadow the dependency graph. Repos that vendor their dependencies with go mod vendor keep a copy of all transitive dependencies under vendor/, with canonical version information in vendor/modules.txt. Some repos modify vendored code directly — technically discouraged, but not uncommon in practice. These modifications break the assumption that a version string in go.mod corresponds exactly to the canonical upstream source. A consumer may appear to be on v1.8.3 while actually running a locally modified version of it.

What the full answer requires

To reliably answer "who imports this module," you need a system that:

Scans every repo in the org, parsing go.mod files — without requiring opt-in or registration from each team
Handles all reference forms — tagged versions, pseudo-versions, and replace directives — and records what module source is actually being resolved, not just what appears in require
Tracks all major version suffixes as distinct but related module identities, so you see the full picture across v1, v2, v3
Distinguishes direct from indirect dependencies, so you know which consumers call into your module directly and which pull it in transitively through another library
Follows transitive edges to show second-order consumers: repos that depend on your module through an intermediate shared library
Keeps results current through regular rescans rather than a one-time snapshot

This is one of the specific problems Riftmap is built to solve. It connects to your GitHub or GitLab organisation, scans every repo, and parses go.mod files to extract module dependencies — including all require entries, replace directives, and version strings. It resolves module paths across major version suffixes and builds a cross-repo dependency graph you can query by module.

The result is the same kind of view described throughout this series: before you remove a function, bump a major version, or change a constructor signature, you open the graph, click the module, and see every repo that imports it — their version, whether they're a direct or indirect consumer, and which teams own them. You know who'll break. You know who to notify. You know who's still on v1 and will need a migration path before v2 ships.

No manual go mod graph inversions across dozens of repos. No org-wide code search with manual version lookups. No waiting to see whose CI goes red after you merge.

This is the fifth post in the Find Every Consumer series. Previous posts cover Docker base images, Terraform modules, GitHub Actions workflows, and Helm charts. Next up: GitLab CI templates.

If this is a problem your platform team deals with, I'd be interested to hear how you're solving it today. You can find more at riftmap.dev or reach me at daniel@riftmap.dev.

How to Find Every Consumer of Your Helm Chart

Daniel Westgaard — Thu, 16 Apr 2026 00:00:00 GMT

You maintain a shared Helm chart. A breaking change is coming. Which teams across the org are running it — and at which version?

You own a shared Helm chart. Maybe it's a platform-services chart that bundles your observability stack: Prometheus, Alertmanager, and a custom metrics exporter your platform team maintains. Maybe it's an ingress-gateway chart that every product team deploys at the edge of their namespace. Maybe it's a company-wide chart for spinning up a standard service with your logging sidecar, network policies, and PodDisruptionBudget pre-configured.

It started as a convenience. Teams stopped reinventing the same Kubernetes manifests. A dozen clusters adopted it. Then more. Some teams deploy it via ArgoCD. Some use Flux. Some have helm install calls baked into their CI pipelines. Some consume it as a subchart inside their own umbrella chart. Some use a plain Chart.yaml with a dependencies: block and run helm dependency update before deploy.

Now you need to change it. Maybe a value key is being renamed — replicaCount is becoming replicas to align with upstream conventions. Maybe you're dropping support for a Kubernetes API version that was removed in 1.32. Maybe you're restructuring the chart into subcharts to make individual components opt-in rather than all-or-nothing.

The question is the same one it always is: which repos across the org consume this chart, and at which version?

The scenario

Here is what Helm chart consumption looks like in practice. Your platform team publishes a chart to an internal chart repository or OCI registry. Consumers reference it in a few different ways:

As a standalone helm install:

helm install platform-services oci://registry.company.com/helm-charts/platform-services --version 3.2.1 -n monitoring

As a dependency in another chart's Chart.yaml:

# some-service/chart/Chart.yaml
dependencies:
  - name: platform-services
    version: "~3.2.0"
    repository: "https://charts.company.com"
    alias: monitoring

As an ArgoCD Application manifest:

# gitops/apps/some-team/monitoring.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
spec:
  source:
    chart: platform-services
    repoURL: https://charts.company.com
    targetRevision: 3.2.1

As a Flux HelmRelease CRD:

# gitops/releases/monitoring.yaml
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
spec:
  chart:
    spec:
      chart: platform-services
      version: ">=3.0.0 <4.0.0"
      sourceRef:
        kind: HelmRepository
        name: company-charts

All four patterns express the same dependency. None of them look the same in source code. And right now, they probably live in different repos, written by different teams, using different GitOps tooling.

What existing tools give you (and where they stop)

Helm itself

The helm CLI knows about releases deployed to a cluster. helm list -A shows every release across all namespaces in a given cluster, including which chart and version is installed. helm history <release> shows the version history for a specific release.

This is useful once you have access to the cluster. The limitation is that it's cluster-scoped and live-state-only. You can see what's running right now, but it tells you nothing about source repos — which repo contains the values.yaml driving the release, which team owns it, or whether the same chart is deployed to a different cluster you don't have access to. Most companies have at least three clusters (dev, staging, prod), and many have dozens. You'd need access to all of them, and even then you'd have a list of running releases, not a map of source-code consumers.

Artifact Hub and Chart Museums

Artifact Hub is the public index for Helm charts. It tracks download counts and shows chart metadata, but it's a discovery tool for chart users, not a graph of chart consumers. If your chart is published internally — to a private chart repository or an OCI registry — it doesn't appear in Artifact Hub at all. And even for public charts, neither Artifact Hub nor any chart museum stores information about which orgs or repos have installed a particular chart version.

ArgoCD and Flux

If your org has committed fully to GitOps and every Helm release is declared as an ArgoCD Application or a Flux HelmRelease manifest in a Git repo, then in theory all your consumers are visible in those manifests. The problem is "in theory." In practice:

Not every team has migrated to GitOps. Some still run helm upgrade in CI pipelines or from engineer laptops.
The GitOps manifests may live in many different repos — a central gitops repo, per-team repos, per-environment repos — rather than a single queryable location.
ArgoCD's UI shows you the apps it's managing, but querying "show me every app that references chart platform-services" is not a built-in view. You'd need to iterate through the Application CRDs or query the Argo CD API.
Flux doesn't have a central query surface for "which HelmRelease objects across all clusters reference chart X at version Y" — that information is spread across HelmRelease YAML files in whatever repos your GitOps setup uses.

Renovate

Renovate supports Helm chart version bumps as a first-class feature. Configured in a repo, it detects chart references in Chart.yaml dependencies, ArgoCD Application manifests, and Flux HelmRelease CRDs, and opens pull requests when new chart versions are published.

As with Terraform and GitHub Actions: Renovate must know who consumes what in order to open those PRs. But it doesn't expose that knowledge as a queryable view. You can't ask Renovate "which repos reference my chart and at which version?" It reacts after a new version is published. The consumer list before you publish a breaking change is not something it surfaces.

Renovate also only covers repos where it has been configured. A team that hasn't added Helm to their Renovate config — or doesn't use Renovate at all — is invisible.

Grep

Clone every repo. Search for the chart name:

grep -r "platform-services" --include="*.yaml" --include="*.yml" ~/repos/

This finds direct name references in YAML files. It doesn't distinguish between chart references and random YAML comments, doesn't extract version constraints, misses OCI-format references where the chart name is embedded in a registry URL, and ignores any helm install calls in shell scripts or Makefile targets. And as always: the results are stale by the next commit.

Why this is harder than it looks

Reference formats are highly inconsistent. A Helm chart can be referenced via a traditional HTTP chart repository, an OCI registry, or a local path. These look nothing alike:

# Traditional repository (in Chart.yaml dependencies)
repository: "https://charts.company.com"

# OCI registry (in Chart.yaml dependencies, Helm 3.8+)
repository: "oci://registry.company.com/helm-charts"

# OCI in a Flux HelmRepository
spec:
  type: oci
  url: oci://registry.company.com/helm-charts

# Inline OCI reference in a helm CLI call
helm install platform-services oci://registry.company.com/helm-charts/platform-services --version 3.2.1

Resolving all of these back to the same chart identity requires knowing how your registry namespaces charts and how your chart repositories map to OCI paths — out-of-band information that no grep can recover.

Version constraints vary widely. Unlike Docker image FROM statements (which usually pin to a specific tag) or Terraform module ref= pins, Helm consumers regularly use semver constraints:

version: "~3.2.0"      # patch-compatible only: >=3.2.0 <3.3.0
version: "^3.0.0"      # minor-compatible: >=3.0.0 <4.0.0
version: ">=3.0.0 <4"  # explicit range
version: "*"           # any version (dangerous)

A consumer pinned to ^3.0.0 will automatically receive your 3.3.0 release — they don't have to explicitly upgrade. A consumer on ~3.2.0 won't. Understanding who will be affected by a minor version bump versus a major bump requires evaluating constraints, not just comparing version strings.

Umbrella charts create transitive consumers. An umbrella chart is a Helm chart whose primary purpose is to bundle multiple subcharts together. If team-a publishes an umbrella chart team-a-stack that includes your platform-services chart as a dependency, and team-b deploys team-a-stack — then team-b is a transitive consumer of platform-services through team-a-stack. A breaking change to platform-services affects team-b, but a search for platform-services in their repos finds nothing.

GitOps and imperative installs coexist. In most organisations, some teams manage Helm releases declaratively (ArgoCD, Flux) and others do it imperatively (helm install or helm upgrade in CI pipelines, shell scripts, or Makefiles). The declarative installs leave traces in Git repos as YAML manifests. The imperative installs may leave no trace in source code at all — just a live release visible in helm list. A complete consumer map needs to combine both sources.

Chart aliases break name matching. A Chart.yaml dependency can declare an alias, which changes the name used to refer to the subchart in values overrides:

dependencies:
  - name: platform-services
    version: "~3.2.0"
    repository: "https://charts.company.com"
    alias: monitoring   # the chart is installed as "monitoring", not "platform-services"

A naive search for platform-services in values files will find nothing, because the values are nested under monitoring:. Tools that rely on name matching alone miss aliased consumers entirely.

What the full answer requires

To reliably answer "who consumes this chart," you need a system that:

Scans every repo in the org, including GitOps repos, service repos, and platform repos — without requiring registration or manual catalog entries
Parses all reference formats — Chart.yaml dependencies, ArgoCD Application manifests, Flux HelmRelease CRDs, and helm install calls in CI configs and shell scripts
Resolves OCI and HTTP registry references back to a canonical chart identity, so consumers using different registry URL formats for the same chart are recognised as the same dependency
Evaluates version constraints rather than just matching exact version strings, so you know which consumers are within range of your next release
Follows umbrella chart transitive dependencies, so second-order consumers are visible, not just direct chart references
Keeps results current through regular rescans, not a one-time manual trawl

This is one of the specific problems Riftmap is built to solve. It connects to your GitHub or GitLab organisation, scans every repo, and extracts chart references from Chart.yaml dependency blocks, ArgoCD Application and ApplicationSet manifests, Flux HelmRelease CRDs, and helm calls in CI configs. It resolves OCI and HTTP registry URLs to a unified chart identity and builds a cross-repo dependency graph you can query by chart name and version.

The result is the same kind of view described in the earlier posts in this series: before you rename a value key or drop a Kubernetes API version, you open the graph, click the chart, and see every consumer — their version constraint, the repo that owns the deployment declaration, and which constraint ranges include your next release. You know who'll automatically receive the change, who's pinned to an older range, and who you need to contact before shipping.

No cluster access required. No cross-org Slack ping. No grep marathon across forty repos.

This is the fourth post in the Find Every Consumer series. Previous posts cover Docker base images, Terraform modules, and GitHub Actions workflows. Next up: Go modules.

If this is a problem your platform team deals with, I'd be interested to hear how you're solving it today. You can find more at riftmap.dev or reach me at daniel@riftmap.dev.

How to Find Every Consumer of Your Reusable GitHub Actions Workflow

Daniel Westgaard — Wed, 15 Apr 2026 00:00:00 GMT

You maintain a shared GitHub Actions workflow. You need to rename an input, drop a step, or change a required secret. Which repos across your org call it? Here's why the answer is harder than it should be.

You maintain a reusable GitHub Actions workflow. Maybe it's deploy-to-eks.yml in your platform team's .github repo, or a ci-lint-test.yml that standardises how every service in the org runs its CI pipeline. It started as a way to stop every team from copy-pasting the same 80-line workflow file. It worked. Twenty repos adopted it. Then forty. Then you lost count.

Now you need to change it. Maybe you're replacing a deprecated action (actions/setup-node@v4 is being forced to Node 24 and you need to bump to v6). Maybe you're renaming an input from node-version to runtime-version because the workflow now supports Bun and Deno too. Maybe you're removing a step that uploaded artifacts to a bucket that no longer exists.

The question is the same one that comes up for every shared infrastructure artifact: which repos across our org call this workflow, and at which ref?

The scenario

Here's what a typical reusable workflow consumption looks like. Your platform team publishes a workflow in a central repository, and other repos call it:

# In some-service/.github/workflows/ci.yml
jobs:
  test:
    uses: my-org/platform-workflows/.github/workflows/ci-lint-test.yml@v2.1.0
    with:
      node-version: "20"
    secrets: inherit

Some repos pin to a tag. Some pin to a branch like main. Some pin to a full commit SHA for supply-chain security. Some don't pin at all and reference @main, which means they're calling whatever version is on HEAD right now.

You need to find all of them, understand which version each one uses, and figure out which will break when you rename that input. Right now, most teams do this by searching in GitHub, asking in Slack, or just pushing the change and waiting for workflows to fail. None of these are a real answer.

What existing tools give you (and where they stop)

GitHub code search

GitHub's code search is the most natural place to look. You can search across all repos in an org:

org:my-org "uses: my-org/platform-workflows/.github/workflows/ci-lint-test.yml"

This works for finding direct string matches. For a one-off audit, it's often good enough. But it has real limitations:

It doesn't extract the ref. You can see that a repo calls the workflow, but the @v2.1.0 or @main part requires manually opening each result and reading the YAML.
Results are point-in-time. If you're planning a breaking change, you need to know who's calling the workflow now — not when the search index was last updated.
The search index can lag. GitHub's code search is eventually consistent. Repos that were recently updated might not show current results immediately.
It doesn't handle indirection. If a repo has a "wrapper" workflow that calls your reusable workflow, and other workflows call the wrapper, GitHub code search only finds the direct callers.

Dependabot

Dependabot supports GitHub Actions as a first-class ecosystem. In a repo's dependabot.yml, you can configure it to watch for action version updates:

updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"

Dependabot will then open pull requests when actions referenced in the repo's workflows have new versions available. This includes reusable workflows referenced with uses:.

The same pattern as Renovate for Terraform: Dependabot implicitly knows who consumes what, because it's configured per-repo. But it doesn't expose this as a queryable view. You can't ask Dependabot "which repos in my org call platform-workflows/ci-lint-test.yml?" It's a version updater, not a dependency mapper.

There's an additional limitation: Dependabot only monitors repos where it's been explicitly enabled. If a team hasn't added github-actions to their dependabot.yml — or doesn't have a dependabot.yml at all — their workflow dependencies are invisible.

Renovate

Renovate also supports GitHub Actions workflows, including reusable workflow references. It can detect uses: directives in workflow files and open PRs when new versions are available.

Renovate has a slight edge over Dependabot here: it can be configured org-wide via a shared preset, so you don't need every repo to opt in individually. But the core limitation is identical — it's a dependency updater, not a dependency mapper. It reacts when a new version exists. It doesn't give you the blast radius before you publish the change.

GitHub API

The GitHub API lets you list workflows and workflow runs across repositories. You can enumerate all repos in an org, fetch their workflow files, and parse the YAML yourself.

This is essentially building a custom scanner. The API gives you the raw data, but assembling it into an answer requires:

Paginating through every repo in the org
Fetching the contents of every .github/workflows/*.yml file
Parsing YAML to extract uses: directives
Filtering for your specific reusable workflow
Extracting the ref from each reference
Handling rate limits (the GitHub API is aggressive about rate limiting for large orgs)

Teams that go this route end up building a script, running it periodically, and storing the results somewhere. It works. It's also a project you now have to maintain, and the results are stale between runs.

Grep

Clone everything, grep for the workflow reference:

grep -r "platform-workflows/.github/workflows/ci-lint-test.yml" --include="*.yml" ~/repos/

Same trade-offs as always: works once, stale immediately, doesn't extract versions, doesn't catch transitive calls, and at 100+ repos it's slow enough that nobody does it proactively.

Why this is harder than it looks

Reusable workflow references look simpler than Terraform module sources or Docker image references — there's really only one syntax. But the complexity is in what surrounds that syntax.

Ref types vary widely. The @ref portion of a workflow call can be a tag, a branch, or a full SHA:

# Tag — the common case
uses: my-org/platform-workflows/.github/workflows/deploy.yml@v2.1.0

# Branch — consuming HEAD, inherently unstable
uses: my-org/platform-workflows/.github/workflows/deploy.yml@main

# SHA — supply-chain hardened, but opaque
uses: my-org/platform-workflows/.github/workflows/deploy.yml@a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

A tag tells you the version. A branch tells you almost nothing — the consumer is on whatever commit main happened to point to when they last ran. A SHA is precise but requires resolving the commit to a tag or branch to understand which version the consumer is actually using. Answering "who's still on v1.x?" requires understanding all three forms.

Reusable workflows vs. composite actions. GitHub Actions has two mechanisms for sharing CI logic: reusable workflows (called with uses: at the job level) and composite actions (called with uses: at the step level). They look similar in YAML but behave differently:

# Reusable workflow — job level
jobs:
  deploy:
    uses: my-org/platform-workflows/.github/workflows/deploy.yml@v2

# Composite action — step level
jobs:
  build:
    steps:
      - uses: my-org/platform-actions/setup-toolchain@v3

Both are dependencies on shared code in other repos. Both break when the interface changes. A consumer tracking system needs to find both, because platform teams often maintain a mix of reusable workflows and composite actions — and the same "who's using this?" question applies to both.

The .github repository. GitHub has a special convention: a repo named .github in an org can contain workflow templates that appear in every repo's "Actions" tab. If your platform team publishes starter workflows through the .github repo, those templates get copied (not referenced) into consuming repos. Once copied, they're no longer linked to the source — there's no uses: directive pointing back, just a disconnected copy that may or may not have been modified since.

This means some of your "consumers" are invisible. They took the template, modified it, and now maintain their own fork. You can't find them by searching for uses: directives because there aren't any.

Inputs and secrets are the breaking surface. Unlike Terraform modules, where the interface is defined by variables and outputs with explicit types, reusable workflow inputs are loosely typed. A workflow declares its inputs:

on:
  workflow_call:
    inputs:
      node-version:
        required: true
        type: string
    secrets:
      DEPLOY_KEY:
        required: true

If you rename node-version to runtime-version, every caller that passes node-version will silently fail — the input just won't be received, and the workflow will use its default or break downstream. There's no compile-time error. The failure shows up at runtime, in the middle of a CI run, and the error message often doesn't clearly point to the renamed input.

Workflow call chains. Reusable workflows can call other reusable workflows, up to ten levels deep and fifty total workflow calls per run (GitHub increased these limits in late 2025). If workflow A calls workflow B, which calls workflow C, and you change C's interface, both A and B are affected — but only B directly references C. Finding A requires resolving the full call chain.

What the full answer requires

To reliably answer "who consumes this reusable workflow," you need a system that:

Scans every repo in the org, parsing all .github/workflows/*.yml files — not just repos that have opted into Dependabot or Renovate
Extracts uses: directives at both the job level (reusable workflows) and step level (composite actions), because platform teams typically maintain both
Resolves ref types — tags, branches, and SHAs — to a normalised version, so you can answer "who's still on v1.x?" regardless of how the ref was specified
Follows workflow call chains so you see transitive consumers, not just direct callers
Keeps the graph current through regular rescans, not one-off audits
Makes the result queryable: "show me every consumer of ci-lint-test.yml, grouped by ref, with the team that owns each calling repo"

This is one of the specific problems Riftmap is built to solve. It scans a GitHub (or GitLab) org, parses every workflow file in every repo, extracts all uses: directives — including reusable workflow calls, composite action references, and standard action pins — and builds a cross-repo dependency graph that you can query by artifact.

The result: before you rename that input or remove that step, you open the graph, click the workflow, and see exactly which repos call it and which ref each one pins to. You know who'll break. You know who to notify. You know who's pinned to main and will see the change immediately versus who's on a tagged release and has time to migrate.

No org-wide grep. No stale GitHub code search. No "let's push it and see whose CI goes red."

For the cross-platform treatment of the change moment itself — why editing a shared reusable workflow is two deployments at once, instant to the @main callers and silent to the ones pinned to a tag, and why CI has no deprecation signal to warn either group — see You changed the shared CI template. Half the org got it instantly. The other half will never see it.

This is the third post in the Find Every Consumer series. Previous posts cover Docker base images and Terraform modules. Next up: Helm charts.

If this is a problem your platform team deals with, I'd be interested to hear how you're solving it today. You can find more at riftmap.dev or reach me at daniel@riftmap.dev.

How to Find Every Consumer of Your Terraform Module

Daniel Westgaard — Tue, 14 Apr 2026 00:00:00 GMT

You maintain a shared Terraform module. A breaking change is coming. Which repos will it hit?

You own terraform-modules/networking. Or infra/modules/vpc. Or a module published to your internal Terraform registry. Dozens of teams call it. Some pin to a specific version. Some track a branch. Some you haven't heard from in months.

Now you need to remove a variable, rename an output, or restructure the resource hierarchy. The question is the same one it always is: which repos across the org depend on this module, and at which version?

This should be a five-second lookup. It isn't.

The scenario

Your platform team publishes a shared Terraform module. Across the org, other repos call it in their root modules or in other shared modules:

module "vpc" {
  source  = "git::https://gitlab.company.com/infra/terraform-modules.git//networking?ref=v3.2.0"
  cidr    = "10.0.0.0/16"
  regions = ["eu-west-1"]
}

Some teams pin to a tag like v3.2.0. Some track main. Some reference a specific commit SHA for reproducibility. Some pull the module from your internal Terraform registry. Some use Terragrunt, where the source is declared in a terragrunt.hcl file rather than a .tf file at all.

You need to find all of them before you merge that breaking change — not after.

What existing tools give you (and where they stop)

HCP Terraform Explorer

HashiCorp Cloud Platform's Module Explorer is the closest thing to a native solution. It builds a graph of module relationships across your HCP Terraform workspaces, showing which workspaces call which modules and at which version.

The limitation is the boundary: it only knows about workspaces registered in HCP Terraform. If your org runs Atlantis, the open-source Terraform runner, or manages state in S3 without using HCP Terraform at all, Module Explorer has no visibility into those workspaces. It also maps workspace-to-module relationships, not source-repo-to-module relationships — which means you know which HCP workspace is affected, but not which engineering team owns it or which Git repo to open a PR against.

Renovate

Renovate can detect module source blocks in .tf files and open pull requests when a newer version is published to a registry. In that sense, it implicitly knows which repos use which modules — it has to, in order to know where to open PRs.

But Renovate doesn't surface this as a queryable view. You can't ask it: "before I publish this breaking version, show me every repo that will receive a PR." It reacts after a new version appears. The blast radius before you publish is not something it answers.

Atlantis

Atlantis tracks which repos it manages and which Terraform workspaces they contain, but it operates per pull request. It applies plans and shows you the output for a given PR, not a cross-repo dependency graph. There's no built-in way to query "which repos across all projects call this module."

Grep

The fallback. Clone every repo, run grep -r "terraform-modules.git//networking", collect results. It works once, the results are stale by the next commit, and it misses the cases described below.

Why this is harder than it looks

Terraform modules can be referenced in at least four structurally different ways, each of which requires a different parsing strategy.

Git sources with subpaths and refs:

source = "git::https://gitlab.company.com/infra/terraform-modules.git//networking/vpc?ref=v3.2.0"

The // separates the repo from the subpath. The ?ref= is the version pin. Grepping for the module name finds this. Grepping for the version doesn't, if someone parameterises it with a local variable.

Internal Terraform registry sources:

source  = "registry.company.com/infra/networking/aws"
version = "~> 3.0"

This looks nothing like a Git URL. It's a registry source with a semver constraint. Connecting this back to a Git repo requires knowing how your registry resolves module sources — which is out-of-band information no grep can recover.

Relative paths between modules:

source = "../../modules/networking"

Common in monorepos or when a module calls a sub-module. Resolving this dependency requires knowing the directory structure of the calling repo and normalising the path. A cross-repo grep for the module name won't find this at all.

Terragrunt:

Terragrunt wraps Terraform and declares module sources in terragrunt.hcl instead of .tf files:

terraform {
  source = "git::https://gitlab.company.com/infra/terraform-modules.git//networking?ref=v3.2.0"
}

This is syntactically similar to HCL but lives in a different file entirely. Any tool that only scans .tf files misses every Terragrunt-based consumer.

Beyond source formats, there's the transitive dependency problem. If Module A depends on your networking module, and Module B depends on Module A, a breaking change to your module cascades through two layers. A list of direct consumers isn't enough if you need to know the full blast radius before shipping.

There's a subtler trap hiding in the version attribute itself. A pin like >= 0.3.0, or a git::...?ref=main source with no version line at all, isn't a fact about what's running — it's a permission, and treating it as a fact is how an automated change lands on a repo nobody pointed it at. I pulled apart what version constraints actually look like across real Terraform estates — measured per corpus — in a companion post.

What the full answer requires

To reliably answer "who consumes this module," you need a system that:

Scans every repo in the org without requiring registration or manual catalog entries
Parses .tf and terragrunt.hcl files so consumers of either style are captured
Resolves all source formats — Git URLs, registry sources, and relative paths — back to an identifiable module identity
Tracks version pins and constraints so you know which consumers are already on the new version and which still need updating
Follows transitive edges so you can see second- and third-order dependents, not just direct callers
Keeps results current through scheduled rescans rather than a one-time snapshot

This is one of the specific problems Riftmap is built to solve. It connects to your GitLab or GitHub organisation, clones every repo, and runs static analysis across .tf files, terragrunt.hcl files, and CI configs. It resolves module sources against your org's internal registry, your Git hosting, and public registries, then builds a cross-repo dependency graph you can query by module.

The result is the same kind of view described in the Docker base image post in this series: click on the module in the graph, see every repo that depends on it, what version each one uses, and who owns it. Direct consumers and transitive dependents, not just a grepped list.

If you're making a change to a shared Terraform module and want to know the blast radius before you merge, that's the answer the tooling currently lacks — and what this graph makes available without a manual trawl through hundreds of repos.

You can try it at riftmap.dev, or reach me at hello@riftmap.dev if you want to talk through your setup.

This is the second post in the Find Every Consumer series. Previous post covers Docker base images. Next up: GitHub Actions workflows.

How to Find Every Consumer of Your Docker Base Image

Daniel Westgaard — Mon, 13 Apr 2026 00:00:00 GMT

You maintain a shared base image. A CVE drops. Which repos are affected? Here's why the answer is harder than it should be.

You maintain an internal Docker base image. Maybe it's platform/node-base or company/python-runtime. A dozen repos use it. Or thirty. Or you're not sure how many, because nobody's counted since the last team reorganisation.

Then a critical CVE hits the base OS layer, and you need to push a patched version. The question that matters is simple: which repos across our org pull this image, and at which version?

This should be easy to answer. It isn't.

The scenario

Here's what this looks like in practice. Your platform team builds and publishes registry.company.com/platform/base-image. Across the org, Dockerfiles reference it:

FROM registry.company.com/platform/base-image:v2.1

Some repos pin to a specific tag. Some use latest. Some have ARG-parameterized FROM statements where the tag is injected at build time. Some reference the image not in a Dockerfile but in a docker-compose.yml or a CI pipeline config.

You need to find all of them, check which version each one uses, and coordinate the update. Right now, most teams do this by grepping, asking on Slack, or checking CI logs. None of these give you a complete, current answer.

What existing tools give you (and where they stop)

Several tools address parts of the Docker base image problem. Each one is useful. None of them answer the full question.

Docker Scout

Docker Scout analyzes a built image and tells you what base image it uses, whether that base is outdated, and what vulnerabilities it contains. docker scout recommendations will suggest updated base images with fewer CVEs.

This is valuable, but it works per-image, not per-org. It answers "what base image does this image use?" It doesn't answer "which of my 200 repos use this base image?" You'd need to run Scout against every image in your registry and correlate the results back to source repos, which is a project in itself.

Renovate

Renovate detects FROM statements in Dockerfiles and can open pull requests when a newer tag is available. It implicitly knows who consumes what, because it's configured per-repo and parses the Dockerfiles.

But Renovate doesn't expose this as a queryable view. You can't ask Renovate "show me every repo that references platform/base-image." It reacts when a new version appears. It doesn't give you the pre-release blast radius: before you push the patched image, which repos and teams will need to update?

Backstage / Roadie Tech Insights

Roadie (a managed Backstage provider) has a Tech Insights feature that can parse Dockerfiles via regex, extract base image versions, and create scorecards tracking migration progress. This is the closest existing solution to the consumer-tracking problem.

The limitation is that it requires Backstage to be set up with catalog-info.yaml per repo. You're tracking Docker base images through a service catalog that depends on manual registration. If a repo isn't in the catalog, its Dockerfile is invisible.

Container registries

Your registry (Docker Hub, Harbor, ACR, ECR) knows which images have been pulled and how often. Some provide pull statistics by tag. But pull logs don't tell you which source repo initiated the pull. A CI pipeline pulling base-image:v2.1 shows up as a pull event, not as "repo frontend-api depends on this image via its Dockerfile on line 3."

Grep

The fallback everyone uses. Clone all the repos, run grep -r "platform/base-image", assemble the results. It works once. The results are stale immediately. It misses parameterized FROM statements, compose files, and CI configs. And at a hundred repos, it takes long enough that nobody does it proactively.

Why this is harder than it looks

The core difficulty is that Docker base image dependencies live in multiple places and multiple formats.

Dockerfiles are the obvious source, but FROM statements can use ARG substitution:

ARG BASE_TAG=v2.1
FROM registry.company.com/platform/base-image:${BASE_TAG}

A simple grep for the image name finds this. A simple grep for the version doesn't, because the version is in a variable.

Docker Compose files reference images differently:

services:
  api:
    image: registry.company.com/platform/base-image:v2.1

This is a dependency on the same image, declared in a completely different file format.

CI pipeline configs often pull images directly:

build:
  image: registry.company.com/platform/base-image:v2.1
  script:
    - make build

A GitLab CI image: directive or a GitHub Actions container: field is another consumption point for the same base image, and it's in yet another file.

Then there's the producer-side problem. Knowing which repos consume the image is half the story. You also need to know which repo builds it. That's usually a CI pipeline with docker build and docker push commands, not something declared in a manifest. Connecting the consumer graph to the producer requires cross-referencing multiple file types within and across repos.

No single tool today connects all of these surfaces into one view.

What the full answer requires

To reliably answer "who consumes this base image," you need a system that:

Scans every repo in the org, not just the ones registered in a catalog
Parses Dockerfiles, Compose files, and CI configs, because the same image can be referenced in all three
Handles variable substitution in FROM statements by resolving ARG defaults
Detects which repos produce which images by scanning CI configs for build and push commands
Keeps the results current through scheduled or event-triggered rescans
Makes the graph queryable: "show me every consumer of platform/base-image, grouped by version"

This is one of the specific problems Riftmap is built to solve. It scans a GitLab or GitHub org, parses Dockerfiles (including multi-stage builds, ARG defaults, and Compose files), detects which repos produce which images via CI config analysis, and builds a cross-repo dependency graph that you can query by artifact.

The result: when that CVE drops, you click on the base image in the graph and immediately see every repo that depends on it, which version each one uses, and who owns them. No grepping. No Slack archaeology. No stale spreadsheet from last quarter.

If this is a problem your platform team deals with, I'd be interested to hear how you're solving it today. You can find more at riftmap.dev or reach me at hello@riftmap.dev.

This is the first post in the Find Every Consumer series. Next up: Terraform modules.

The State of Infrastructure Dependency Tooling in 2026

Daniel Westgaard — Thu, 09 Apr 2026 00:00:00 GMT

An honest survey of what exists, what each tool actually solves, and where the gap is widest.

When I started researching cross-repo infrastructure dependency management, first as a practitioner hitting the problem at client sites, then as someone building a tool to solve it, I expected to find a crowded space. Dependency management is a well-understood problem in software engineering. Package managers have solved it for application code. Surely someone had solved it for infrastructure.

They hadn't. Not because nobody tried, but because the tools that exist were built to solve adjacent problems. Each one is good at what it does. None of them answer the specific question that platform teams keep asking: if I change this shared module, image, or template, which repos break and who do I need to notify?

This post is a genuine attempt to map the landscape: what exists today, where each tool shines, and where it stops. I've used or evaluated most of these tools, talked with engineers who rely on them daily, and spent time in community discussions where people describe what's working and what isn't. I've tried to be fair. Every tool here solves a real problem for real teams. The point is not that they're bad. It's that the specific problem of cross-repo infrastructure dependency visibility sits in a gap between them.

How to think about the landscape

The tools people reach for when they encounter the dependency visibility problem fall into six categories. Understanding the categories matters more than evaluating individual tools, because the gap isn't a missing feature in any one product. It's a missing category.

Service catalogs and developer portals — "what exists and who owns it"
Dependency update automation — "keep everything on the latest version"
Platform-specific dependency explorers — "see relationships within one ecosystem"
Monorepo build tools — "solve the problem by putting everything in one repo"
Security and compliance scanners — "find vulnerabilities and license issues across repos"
DIY scripts and manual approaches — "build exactly what you need, maintain it forever"

Each category addresses a real need. Each one gets mistaken for a solution to the visibility problem. Let's look at why.

Service catalogs: Backstage, Port, OpsLevel

What they do well

Service catalogs, with Backstage being the most prominent and Port and OpsLevel as managed alternatives, give engineering organisations a central place to answer "what services do we run, who owns them, and where do they live?" Backstage in particular has become the standard for developer portals at larger companies. It integrates with CI/CD, on-call systems, documentation, and cloud resources. It gives teams a single pane of glass for service ownership.

Port and OpsLevel take a similar approach with less self-hosting overhead. They provide scorecards, maturity tracking, and integrations with cloud providers. For organisations that need a developer portal, especially those with hundreds of services and unclear ownership, these tools are genuinely valuable.

Where they stop

The dependency model in service catalogs is registered, not discovered. In Backstage, you define a catalog-info.yaml per repo that describes the service, its owner, and its dependencies. This information is exactly as accurate as the last time someone updated that file.

In practice, catalog YAML goes stale quickly. Engineers update code. They don't update the catalog. The dependency that got added three months ago isn't in the YAML. The one that got removed six months ago is still listed. As one engineer described it to me, it's "documentation with extra steps."

This isn't a flaw in Backstage; it's a design choice. Service catalogs are built for service metadata (ownership, documentation links, runbook URLs), not for dependency graph accuracy. They're excellent at answering "who owns this service?" They're not designed to answer "which 40 repos consume this Terraform module at which version?" If you're weighing the catalog category against the alternatives for this specific job, I triage that decision in Backstage alternatives in 2026.

Port has invested in auto-discovery features that pull some metadata from cloud resources and Git, which narrows the gap. But the cross-repo infrastructure dependency graph (Terraform modules sourcing other modules, Docker base images consumed by dozens of repos, CI templates included across the org) still requires either manual registration or a separate discovery mechanism.

Who should use them

Any organisation over ~50 services that needs a central developer portal with ownership tracking, documentation, and service maturity scoring. They're complementary to dependency visibility tooling, not a replacement for it.

Dependency update automation: Renovate and Dependabot

What they do well

Renovate and Dependabot solve a specific, well-defined problem: when a dependency has a new version available, automatically open a pull request to update it. Renovate in particular is remarkably flexible. It supports dozens of package ecosystems, custom versioning schemes, grouping strategies, and scheduling controls. For teams that want to stay current on their dependencies, Renovate is close to best-in-class.

Dependabot, integrated directly into GitHub, offers a lower-configuration path to the same outcome. It's particularly strong for npm, pip, Go modules, and GitHub Actions workflows.

Both tools are excellent at what they do, and many teams should be using one of them regardless of what else they adopt for dependency visibility.

Where they stop

The core distinction is between prevention and visibility. Renovate and Dependabot solve prevention: they keep consumers updated so that version drift doesn't accumulate. They react after a new version is published by opening PRs across consuming repos.

What they don't provide is the pre-release view. Before you publish version 2.0 of your shared Terraform module, before you even cut the release, you want to know: who is consuming the current version? How many repos will be affected? Which teams own them? Are any of them pinned to a version that's already three releases behind?

Renovate can tell you that a new version is available. It cannot tell you the blast radius of a change you haven't published yet. These are different problems, and confusing them leads teams to believe they have dependency visibility when they actually have dependency automation. This is the same gap that bites when you go to deprecate an internal library: the automation can perform the bump in every repo it's been pointed at, but it presupposes the list of consumers, and the repos pinned to the old version that fell out of the automation are exactly the ones that break on removal — I've written up that angle separately.

There's a subtler gap too: Renovate and Dependabot work at the package level, not the repo level. They know that package.json depends on @company/utils@1.2.0. They don't know that the repo containing that package.json also has a Dockerfile that pulls an internal base image, a CI config that includes a shared template, and a Terraform module that sources three other internal modules. The cross-ecosystem picture is outside their scope.

Who should use them

Every team that consumes shared dependencies and wants to avoid version drift. Use them alongside dependency visibility tooling, not instead of it.

Platform-specific explorers: HCP Terraform, Artifactory, GitHub Dependency Graph

HCP Terraform Explorer

HashiCorp Cloud Platform (HCP Terraform, formerly Terraform Cloud) includes a module explorer that shows which workspaces use which modules. If your entire Terraform workflow runs through HCP Terraform (plan, apply, state management, all of it) this gives you a reasonable view of Terraform-specific module relationships.

The limitation is scope. It only works for Terraform. It only works for workspaces managed by HCP Terraform. If your org has a mix of HCP Terraform, self-hosted Terraform runners, CI-driven applies, and Atlantis (and many do) you get a partial view. The Docker images, CI templates, Helm charts, and Ansible roles that are part of the same dependency graph are invisible.

For teams that are fully committed to HCP Terraform and only need Terraform module visibility, this is a solid native solution. For everyone else, it's a slice of the picture.

JFrog Artifactory

Artifactory is a universal artifact repository. For Terraform, it can serve as a private module registry with metadata about published modules: versions, download counts, and some dependency information.

The gap is on the consumer side. Artifactory knows what modules have been published. It doesn't reliably tell you which repos are consuming a given module at which version right now. The publishing-side view and the consuming-side view are different, and Artifactory was built for the former.

GitHub Dependency Graph and Dependabot Alerts

GitHub's built-in dependency graph parses lock files and manifests to show what each repo depends on. It's tightly integrated with Dependabot alerts for security vulnerabilities.

It's good for application dependencies: npm, pip, Go modules, Ruby gems. It's limited for infrastructure dependencies. Terraform module sources, Docker base image relationships, CI template includes, Helm chart dependencies. These aren't part of GitHub's dependency graph model. And the view is per-repo, not org-wide: you can see what one repo depends on, but you can't easily ask "who across my org depends on this artifact?"

Who should use them

Teams that operate primarily within a single ecosystem and a single platform. If you're a pure Terraform Cloud shop, HCP Explorer gives you module visibility. If you're managing artifact publishing, Artifactory is the right tool for that. If you need per-repo application dependency visibility on GitHub, the built-in graph works. None of them provide the cross-ecosystem, org-wide view.

Monorepo build tools: Nx, Turborepo, Bazel

What they do well

This is the category that genuinely solves the dependency visibility problem, within its context. Monorepo build tools like Nx, Turborepo, and Bazel are built around a dependency graph. They know which packages depend on which. They can tell you exactly what's affected by a change. They run only the tests and builds that are actually impacted.

Nx in particular is impressive here. Its nx affected command does precisely what platform teams wish they could do across a polyrepo: given a set of changed files, determine which projects in the repo are affected and need to be rebuilt or retested. It has a visual graph explorer, dependency analysis, and caching that skips unaffected work. Turborepo provides similar affected-project detection with a focus on speed and simplicity. Bazel takes it further with hermetic builds and fine-grained dependency tracking at the file level.

If your organisation operates as a monorepo, these tools give you dependency visibility almost for free. The graph is implicit in the repo structure, and the build tool maintains it automatically.

Where they stop

The limitation is the prerequisite: you have to be in a monorepo.

Most infrastructure teams dealing with the cross-repo dependency problem are not in a monorepo, and migrating to one is not a realistic option. An organisation with three hundred existing repos, multiple teams with separate access controls, compliance boundaries between business units, and repos inherited through acquisitions cannot consolidate into a single repository as a quarter-long project. It's a multi-year architectural migration with significant operational risk.

Even organisations that want to move toward a monorepo often can't do it all at once. They might consolidate application code but keep infrastructure repos separate. Or they might run a monorepo for one team while other teams stay on polyrepo. The dependency graph still crosses that boundary, and monorepo build tools only see what's inside the monorepo.

There's also a scope question. Nx and Turborepo are primarily designed for application code (TypeScript/JavaScript, with growing support for other languages). The infrastructure dependency graph, which includes Terraform modules, Docker base images, CI templates, Helm charts, and Ansible roles, doesn't map cleanly onto a monorepo build tool's model. Bazel is more general-purpose, but the overhead of Bazel adoption is substantial and rarely justified purely for dependency visibility.

One more nuance worth noting: even inside a monorepo, the build tool's dependency graph tracks build-time relationships. It knows that package A imports package B. It doesn't necessarily know that a Dockerfile in one directory pulls a base image that's built by a CI job defined in another directory, or that a Terraform module sources another module via a git URL pointing at a subdirectory. The infrastructure dependency surface is different from the application dependency surface, even within a single repo.

Who should use them

Any team already operating in a monorepo, or actively planning a migration to one. Nx and Turborepo are excellent tools. The point is not that monorepos are wrong. It's that "switch to a monorepo" is not actionable advice for the organisations that feel the cross-repo dependency problem most acutely.

Security and compliance scanners: Wiz, Snyk, SBoM tools

What they do well

Security scanners like Wiz and Snyk, along with the broader SBoM (Software Bill of Materials) ecosystem, solve an important and well-funded problem: finding known vulnerabilities (CVEs) and license compliance issues across an organisation's software supply chain.

Wiz in particular has an attractive deployment model for this discussion: org-level installation via webhook or cloud connector, with no per-repo configuration needed. It scans broadly and automatically. The install pattern is exactly right for dependency discovery.

Snyk provides deep analysis of application dependencies, container images, and infrastructure-as-code configurations. It's strong on identifying security risks within dependency trees.

Where they stop

These tools are built around a security and compliance model, not a dependency visibility model. The question they answer is "do any of my dependencies have known vulnerabilities?", not "which repos depend on this internal module and what's the blast radius if I change it?"

The distinction matters in practice. Wiz can tell you that a container image has a CVE. It doesn't tell you that 30 repos across your org use that image as a base, that 12 of them are pinned to an outdated version, and that updating the image will require coordinated changes across four teams. Snyk can tell you that a Python package has a license issue. It doesn't show you the cross-repo dependency graph between your internal Terraform modules, CI templates, and Helm charts.

There's also a scope gap: most security scanners focus on application dependencies (npm packages, Python libraries, container images) and cloud configuration. Terraform module-to-module relationships, CI template includes, and Ansible role dependencies are generally outside their scanning model.

The pricing model is also relevant. Enterprise security platforms are priced for security budgets, not platform engineering budgets. Using a security scanner as a general-purpose dependency mapping tool would be expensive overkill for the dependency visibility problem specifically.

Who should use them

Any organisation that takes software supply chain security seriously, which should be everyone. These tools are essential for what they do. They just don't do dependency visibility, and shouldn't be expected to.

DIY approaches: grep, scripts, and custom crawlers

What they do well

This is the category that tells you the most about the problem. When multiple independent engineers, with no coordination between them, build nearly identical tools, you're looking at a genuine unmet need.

The common pattern: a scheduled job that shallow-clones every repo in the org (or uses the GitLab/GitHub API), greps or parses Dockerfiles, Terraform source blocks, and CI include directives, dumps the results to SQLite or a spreadsheet, and maybe renders a graph with something like Observable Framework or a simple web page.

These solutions work. They prove the approach is sound. Some of them are impressively capable, handling hundreds or even thousands of repos, tracking multiple file types, producing usable output. The engineers who build them solve their team's immediate problem, often in a day or two of effort.

Where they stop

Bespoke solutions have a consistent set of failure modes:

They go stale. A nightly cron job means the graph is up to 24 hours out of date. A manually-triggered script means it's as fresh as whoever last remembered to run it.

They're fragile. When a repo is renamed, archived, or changes its structure, the script breaks. Handling these edge cases, and the dozens of others that emerge over time, requires ongoing maintenance that nobody budgeted for.

They're not generalised. Each one handles the specific file types and repo structures of one org. Moving to a new org, or adding support for a new ecosystem, means rewriting.

They don't survive their creator. The engineer who built the script in a weekend moves to another team or another company. Nobody else understands how it works. Six months later, it's running but nobody trusts the output. Or it's silently broken. Or it's been turned off.

They lack a query interface. Most DIY solutions produce a static output. Asking "what's the blast radius of changing module X?" means writing a new query or script, not clicking a button.

The meta-point: the fact that people keep building these, and that the solutions converge on the same architecture, validates both the problem and the general approach. What's missing is a product that does it well, keeps doing it, and handles the long tail of edge cases that a weekend hack can't.

Who should use them

Teams with a specific, narrow need (maybe just Terraform modules across 30 repos) and an engineer willing to maintain a custom script. For anything broader or longer-lived, the maintenance cost exceeds the build cost within months.

The gap in the landscape

Line up the categories side by side and the gap becomes clear:

Service catalogs know what exists and who owns it, but dependencies are registered, not discovered, and go stale.

Dependency update tools keep consumers current, but only react after a version is published and don't show blast radius beforehand.

Platform-specific explorers show relationships within one ecosystem, but are blind to everything outside it.

Monorepo build tools solve the problem structurally, but only if you're already in a monorepo. Most infrastructure teams aren't.

Security scanners find vulnerabilities across repos, but don't map infrastructure dependency graphs.

DIY scripts prove the approach works, but are bespoke, brittle, and don't survive their creator.

The missing category is cross-ecosystem infrastructure dependency visibility: a tool that automatically discovers how repos depend on each other across all the ecosystems a platform team uses (Terraform, Docker, CI templates, Helm, Ansible, Python, Go, npm, Kubernetes), keeps that graph current without manual maintenance, and makes it queryable.

Specifically, the gap has these characteristics:

Auto-discovered, not registered. The dependency graph must be built from what's actually in the repos: the Terraform source blocks, the Dockerfile FROM statements, the CI include directives. Any approach that requires humans to maintain a catalog will go stale. The community has been clear and consistent on this point.

Cross-ecosystem. Real infrastructure dependency graphs cross tool boundaries. A Terraform module change affects Docker builds which affect CI pipelines which affect Helm deployments. Single-ecosystem tools miss exactly the connections where surprise breakage happens.

Consumer-side visibility. Most existing tools show the producer side: what modules exist, what images are published, what templates are available. The question platform teams actually need answered is the consumer side: who is pulling this artifact, at which version, right now?

Org-level installation. At a hundred or more repos, anything that requires per-repo setup is a non-starter. The installation model should be a single read-only access token at the org level, similar to how security scanners deploy.

Freshness without manual effort. The graph must stay current through scheduled or event-driven rescans. Staleness is the number one reason DIY solutions get abandoned. Any productised solution that doesn't solve freshness will follow the same path.

Blast radius before you push. The highest-value query is prospective, not retrospective: before I publish a breaking change, show me every repo and team that will be affected. This requires the full transitive graph, not just direct dependencies.

Where I think this is heading

The dependency visibility gap isn't going to close on its own. If anything, it's widening. Organisations are adopting more infrastructure tools, not fewer. The shift toward platform engineering means more shared components consumed across more repos. AI-assisted development is accelerating code output without any corresponding improvement in dependency awareness.

I expect we'll see this category emerge properly over the next couple of years. The building blocks exist: Git platform APIs for repo enumeration, well-understood file formats for parsing, graph databases and recursive queries for traversal, and a clear community demand validated by the fact that people keep building their own versions.

Some existing tools may expand into this space. Backstage's plugin ecosystem could support auto-discovery. Renovate's deep parser library could be extended for visibility queries. Security platforms like Wiz, which already have the org-level deployment model, could add infrastructure dependency graphs alongside their vulnerability scanning.

What I think is more likely is that purpose-built tools will emerge. Tools designed specifically for cross-repo infrastructure dependency visibility, with auto-discovery, cross-ecosystem support, and blast radius analysis as core capabilities rather than bolted-on features.

That's what I'm building with Riftmap. It scans a GitLab or GitHub org, auto-discovers cross-repo dependencies across Terraform, Docker, CI pipelines, Python, Go, npm, Ansible, Helm, Kubernetes, and Kustomize, and presents the graph with interactive blast radius analysis. Org-level install, no per-repo config, no YAML to maintain.

It's currently in early access, and it's far from finished. But the foundation is live: twelve ecosystem parsers, a resolver that matches consumers to producers across the org, incremental scanning to keep the graph fresh, and a visual graph with impact mode that shows exactly which repos are affected by a given change.

If you're working in this space, whether as an engineer dealing with the problem, someone building tooling, or someone evaluating solutions, I'd welcome the conversation. The more perspectives I hear, the better the tooling gets for everyone.

You can see more at riftmap.dev, or reach me at hello@riftmap.dev.

If you're interested in following along as Riftmap develops, sign up for early access at riftmap.dev.

Auto-Discovering Infrastructure Dependencies Across 10 Ecosystems

Daniel Westgaard — Sat, 04 Apr 2026 00:00:00 GMT

It sounds simple: clone every repo, parse the files, build a graph. Here's why each ecosystem fights back, and what it actually takes to map cross-repo dependencies automatically.

In the last post, I wrote about the infrastructure dependency visibility gap. The fact that most platform teams have no way to answer "if I change this, what else breaks?" across their repos. The community response confirmed what I'd seen at every client: people are building brittle grep scripts, maintaining stale spreadsheets, or just relying on whoever has been around the longest.

The obvious next question is: why doesn't anyone just parse the repos and build a graph?

The answer is that people do. Multiple engineers I've spoken with have built their own versions; a nightly cron job, some shell scripts, a SQLite database. And those solutions work, for a while, for one org, for the file types they remembered to handle. Then they hit an edge case, go stale, or the person who built it moves on.

The core approach is right: scan every repo, parse the files that declare dependencies, resolve them to actual repos, build a directed graph. But the devil is in the details, and each ecosystem has its own set of devils. This post walks through what it actually takes to auto-discover cross-repo dependencies across Terraform, Docker, CI pipelines, Python, Go, npm, Ansible, Helm, and Kubernetes, and why the cross-ecosystem problem is harder than any individual one.

The approach: parse what's already there

The principle behind auto-discovery is simple: the dependencies are already declared in the source files. A Terraform module has a source attribute pointing at a git URL. A Dockerfile has a FROM statement naming a base image. A GitLab CI config has include: directives referencing templates in other repos.

You don't need humans to fill in a catalog. You don't need a YAML manifest per repo. The dependency information exists. It's just scattered across a dozen file formats in hundreds of repos, with no unified view.

So the pipeline looks like this:

Enumerate — list every repo in the GitLab group or GitHub org via API
Clone — shallow-clone each repo (depth 1, just the default branch)
Parse — walk the file tree, dispatch each file to the right parser based on filename and path
Detect artifacts — identify what each repo produces (a Terraform module, a Docker image, a Python package, a Helm chart)
Resolve — match parsed dependency references to known repos or artifacts in the org
Store — persist the graph as queryable relationships

Steps 1 and 2 are straightforward. Steps 3 through 5 are where every ecosystem has opinions about how to make your life difficult.

Terraform: where version refs hide in query strings

Terraform is usually the first ecosystem people think of for cross-repo dependencies, and on the surface it looks easy. A module block has a source attribute:

module "vpc" {
  source = "git::https://gitlab.com/infra/modules/vpc.git?ref=v2.1.0"
}

You parse the source string, extract the git URL and the ref, normalize the path to infra/modules/vpc, match it against known repos in the org — done.

Except it's never that clean. Here's what you actually encounter in the wild:

Multiple URL formats. The same module might be sourced as git::https://..., git@gitlab.com:... (SSH), a bare HTTPS URL without the git:: prefix, or a Terraform registry address like app.terraform.io/org/module/provider. Each format needs different parsing logic to extract the same canonical repo path.

Subdirectory references. Terraform supports the double-slash convention: git::https://gitlab.com/infra/modules.git//networking/vpc?ref=v1.0. The repo is infra/modules, but the module is in a subdirectory. This means one repo can produce multiple distinct modules, and your parser needs to handle that relationship.

Variable interpolation. You'll find modules like:

module "service" {
  source = "git::https://gitlab.com/${var.infra_group}/modules/service.git"
}

You can't resolve ${var.infra_group} without running Terraform, and the whole point of static analysis is that you don't run Terraform. The practical choice is to flag these as lower-confidence dependencies and extract what you can from the static portion of the string.

Public registry vs. internal modules. A source like hashicorp/consul/aws points to the public Terraform Registry — it's not an internal dependency and should be skipped. But app.terraform.io/your-org/vpc/aws is internal. The parser needs to distinguish between public and private registries.

The modules.json trap. Some people suggest parsing .terraform/modules/modules.json, which contains the resolved module tree. The problem: this file only exists if someone has run terraform init, it's usually in .gitignore, and it reflects one person's local state — not the repo's declared dependencies. It's not a reliable source for org-wide discovery.

The meta-lesson from Terraform: even within a single ecosystem, the same logical relationship ("repo A depends on repo B") can be expressed in half a dozen syntactically different ways, and your parser needs to normalize all of them to the same canonical form.

Docker: the base image puzzle

Dockerfiles look deceptively simple:

FROM node:18-alpine

That's a public image — skip it. But:

FROM registry.company.com/platform/base-image:v2.1

That's an internal base image, and it means this repo depends on whatever repo builds and publishes platform/base-image. Tracking these relationships across an org is one of the highest-value things a dependency graph can do. Docker base image updates are a constant source of surprise breakage.

Here's where it gets complicated:

Build arguments and variable substitution. Real-world Dockerfiles frequently use ARG to parameterize the base image:

ARG REGISTRY=registry.company.com
ARG BASE_VERSION=latest
FROM ${REGISTRY}/platform/base-image:${BASE_VERSION}

You can resolve ARG defaults by parsing the Dockerfile top-to-bottom, substituting the default values into the FROM statement. But if the ARG is overridden at build time via --build-arg, the static default might be wrong. Again: lower confidence, but still useful signal.

Multi-stage builds. A modern Dockerfile might have several FROM statements:

FROM node:18 AS builder
RUN npm ci && npm run build

FROM registry.company.com/platform/nginx:1.25
COPY --from=builder /app/dist /usr/share/nginx/html

The first FROM is a public image. The second is an internal dependency. The COPY --from=builder is a reference to an earlier stage, not an external image — the parser needs to track named stages and skip internal references. If you naively treat every FROM and COPY --from as a dependency, you'll generate false edges in the graph.

Docker Compose adds another layer. A docker-compose.yml might reference images directly:

services:
  api:
    image: registry.company.com/backend/api-service:latest

This is a dependency declaration in a completely different file format (YAML vs. Dockerfile syntax), but it represents the same kind of relationship.

The consumer-side problem. Knowing that repo X uses a Docker image is only half the story. You also need to know which repo builds that image. This isn't declared in the Dockerfile. It's usually in the CI pipeline config (docker build -t and docker push commands). Connecting the consumer side ("this repo uses image Y") to the producer side ("this repo builds image Y") requires cross-referencing information from different file types within the same repo.

CI templates: the invisible dependency layer

CI pipeline configs are arguably the most important dependency surface to track, and the most neglected.

GitLab CI

GitLab CI supports several forms of cross-repo inclusion:

include:
  - project: 'platform/ci-templates'
    ref: 'v2.0'
    file: '/terraform-plan.yml'

  - remote: 'https://gitlab.com/platform/ci-templates/-/raw/main/deploy.yml'

The project: form gives you a clean repo reference and an optional version ref. The remote: form gives you a URL that needs to be parsed back into a repo path.

There's also trigger:, where one pipeline triggers another project's pipeline, and image:, where a job specifies a Docker image. Another dependency surface hiding in the CI config.

A subtle gotcha: GitLab CI supports !reference tags for reusing configuration fragments. These are valid YAML tags but not standard YAML. A naive YAML parser will choke on them. Your parser needs to handle this gracefully, either by pre-processing the file or by configuring the YAML loader to ignore unknown tags.

GitHub Actions

GitHub Actions reusable workflows have their own syntax:

jobs:
  deploy:
    uses: org/shared-workflows/.github/workflows/deploy.yml@v1.2.0

And composite or JavaScript actions:

steps:
  - uses: org/custom-action@main

The uses: string encodes the org, repo, path, and ref in a single string. You need to parse it, separate the org/repo from the workflow path, handle the @ref suffix, and skip public actions (anything under actions/*).

The real challenge with CI templates is that they're often pinned to a branch rather than a tag — @main instead of @v2.0. This means version tracking is inherently fuzzy. You can tell that repo A depends on repo B's CI template, but "which version" is just "whatever's on main right now." This is exactly the kind of implicit, hard-to-track dependency that causes surprise breakage.

Python, Go, and npm: package ecosystems with their own quirks

These three share a common pattern — they have declared dependency manifests — but each has its own flavour of complexity.

Python

Python dependencies can be declared in at least four places: requirements.txt, pyproject.toml, setup.cfg, and setup.py. Each has a different syntax. And only some of those declarations point at internal packages — most are public PyPI packages that you should skip.

The interesting ones for cross-repo tracking are editable git installs:

-e git+https://gitlab.com/org/internal-utils.git@v1.2#egg=internal-utils

And pyproject.toml dependencies pointing at internal packages published to a private PyPI registry. Matching "package name in a requirements file" to "the repo that builds that package" requires knowing what each repo produces — which is why the artifact detection step (identifying that a given repo is the source of a Python package, based on its pyproject.toml or setup.py) is essential.

Go

Go modules are cleaner than most. The go.mod file is authoritative:

require (
    gitlab.com/org/shared-lib v1.3.0
    github.com/org/internal-sdk v0.9.2
)

The module path is the repo path (more or less). The version is explicit. The main challenge is filtering: most require entries are public modules (github.com/stretchr/testify, golang.org/x/net). You need a way to identify which entries point to repos within your org and skip the rest.

replace directives add a wrinkle — they can redirect a module path to a local directory or a different remote path, which changes the effective dependency.

npm

package.json is the source of truth. For internal cross-repo dependencies, you're looking for scoped packages or git URL references:

{
  "dependencies": {
    "@company/ui-components": "^2.1.0",
    "@company/shared-utils": "git+https://github.com/org/shared-utils.git#v1.0"
  }
}

Scoped packages (@company/...) from a private registry need to be matched to the repo that publishes them. Git URL references can be parsed directly. Public npm packages are filtered out.

One thing all three ecosystems share: the link between "this repo consumes package X" and "this repo produces package X" is not always obvious from a single file. You need to first discover what each repo publishes (by reading its pyproject.toml, go.mod module declaration, or package.json name field), then match consumers to producers across the org.

Ansible and Helm: infrastructure-specific dependency patterns

Ansible

Ansible dependencies appear in requirements.yml (roles and collections), galaxy.yml (collection metadata and dependencies), and meta/main.yml (role dependencies).

# requirements.yml
roles:
  - src: git+https://gitlab.com/org/ansible-roles/nginx.git
    version: v2.0

collections:
  - name: company.shared_collection
    version: ">=1.0"

The complexity here is similar to Python: matching a Galaxy-style name (company.shared_collection) to the repo that publishes it requires artifact detection. Git URL sources are more straightforward but still need normalisation.

Helm

Helm chart dependencies are declared in Chart.yaml:

dependencies:
  - name: redis
    version: "17.x"
    repository: "https://charts.bitnami.com/bitnami"
  - name: auth-service
    version: "1.2.0"
    repository: "https://helm.internal.company.com"

Public chart repositories (Bitnami, stable, etc.) are filtered out. Internal repository references need to be matched to the repos that build those charts. And file:// references to local charts in the same repo are internal — not cross-repo dependencies.

Kubernetes and Kustomize: the deployment layer

Kubernetes manifests and Kustomize configurations add another dependency surface — one that's often overlooked because it's at the "deployment" end of the pipeline rather than the "build" end.

Kustomize's kustomization.yaml can reference resources and bases from other repos:

resources:
  - https://github.com/org/k8s-base//manifests/monitoring?ref=v1.0

bases:
  - github.com/org/shared-platform//overlays/production

These are cross-repo references with the same double-slash subdirectory convention as Terraform. They need the same kind of URL normalisation and repo matching.

Kubernetes manifests themselves reference Docker images in container specs, Helm charts in HelmRelease custom resources, and ConfigMaps or Secrets by name. The image references connect back to the Docker dependency surface — another example of how the graph crosses ecosystem boundaries.

The real challenge: resolution

Parsing is the visible work. But the step that makes or breaks the dependency graph is resolution. Taking a parsed reference and matching it to an actual repo or artifact in your org.

A Dockerfile says FROM registry.company.com/platform/base-image:v2. Which repo builds that image? The registry path might not match the repo path. The image might be built by a CI pipeline in a repo named docker-base-images, pushed to a registry path of platform/base-image. Connecting those requires understanding the producing side, not just the consuming side.

This is why artifact detection matters so much. Before you can resolve "this repo uses artifact X," you need to know "that repo produces artifact X." For Docker images, this means scanning CI configs for docker push commands. For Python packages, it means reading pyproject.toml to find the package name. For Helm charts, it means reading Chart.yaml. Each ecosystem has a different way of declaring what a repo produces, and the resolver needs to cross-reference all of it.

Resolution also has to deal with ambiguity. A Docker image reference like base-image:v2, without a full registry prefix, could match multiple repos. A Python package name might be normalised differently (my_package vs. my-package). Terraform module paths might use SSH vs. HTTPS URLs for the same repo. The resolver needs normalisation rules, fuzzy matching strategies, and a confidence model — because some matches are certain and others are best-effort.

Getting this right is the difference between a dependency graph that people trust and one they abandon after finding three false edges.

Why cross-ecosystem matters

Any individual ecosystem's parsing problem is tractable. The Python community could build a Python dependency tracker. The Terraform community could build a module graph tool. And some have.

But the actual dependency graph in a real organisation doesn't respect ecosystem boundaries. A Terraform module produces infrastructure that a Docker image is built on, which a CI pipeline deploys, which references a Helm chart, which pulls a shared Ansible role.

If you only see the Terraform slice, you miss the Docker dependency that's about to break your deployment pipeline. If you only see Docker, you miss the Terraform module change that will change the infrastructure your image runs on.

The value of cross-ecosystem discovery isn't additive — it's multiplicative. Each new ecosystem you add doesn't just give you more nodes in the graph. It reveals connections between ecosystems that were previously invisible. Those connections are exactly where surprise breakage lives.

What I learned building this

I've been building Riftmap to solve this problem — auto-discovering cross-repo dependencies across all the ecosystems described above and presenting them as a queryable, visual graph with blast radius analysis.

A few things I've learned along the way:

The parser is the easy part. Extracting source = "..." from a Terraform file is straightforward. The hard parts are resolution (matching references to actual repos), freshness (keeping the graph current as repos change), and staleness detection (knowing when a previously-discovered dependency no longer exists because a repo was renamed or archived).

Confidence matters. Not all discovered dependencies are equally certain. A Terraform source with a full git URL and a pinned ref is high confidence. A Docker FROM with variable substitution and no default value is low confidence. Exposing this confidence to users — rather than pretending everything is equally certain — is critical for trust.

The graph is the product, not the report. Every DIY solution I've seen generates a static output — a CSV, a SQLite dump, a rendered image. The real value comes when the graph is interactive, queryable, and always current. "Show me every repo affected if I change this module" should be a click, not a pipeline run.

If you're building infrastructure for a platform team and this problem resonates, I'd love to hear how it shows up in your stack. The edge cases are different for every org, and understanding them is how the tooling gets better.

You can see more at riftmap.dev, or reach me at hello@riftmap.dev.

The Infrastructure Dependency Problem No One Has Solved

Daniel Westgaard — Mon, 30 Mar 2026 00:00:00 GMT

I've worked as an infrastructure consultant in Norway for about two and a half years. That's not long. But in that time, every single client I've worked with has had a version of the same problem.

Someone pushes a change to a shared Terraform module. An hour later, Slack lights up. Three teams are broken. Nobody knew they depended on that module. Or rather, one person knew. And they left six months ago.

The dependency chain was always there. It just wasn't visible to anyone.

This post is about that problem: the complete absence of cross-repo dependency visibility in modern infrastructure teams. It's a problem I kept running into, kept hearing about, and eventually decided to build something to fix. But before I talk about the fix, I want to talk about why the problem exists, why it's getting worse, and why the "obvious" solutions don't actually work.

What is cross-repo dependency visibility?

Most engineering teams today operate in a polyrepo setup. Not because they chose it carefully — usually because the org grew, teams split, acquisitions happened, and now there are a hundred or more repos across GitLab or GitHub.

Inside those repos, there are dependencies everywhere. A Terraform module in one repo is sourced by twelve others. A Docker base image built in one pipeline is pulled by thirty Dockerfiles across the org. A GitLab CI template is included by eighty pipelines. A Helm chart references another internal chart. An Ansible role depends on a shared collection.

Cross-repo dependency visibility means being able to answer one question: if I change this thing, what else is affected?

Not "what might be affected." Not "let me grep around and hope I find everything." But a clear, always-current, automatically maintained answer.

Almost nobody has this.

Why this problem shows up at every growing org

The pattern is remarkably consistent. Here's how it plays out:

At 10–30 repos, you probably don't need tooling. A senior engineer holds the dependency map in their head. They can tell you "oh, if you touch the VPC module, repos A, B, and C use it." This works fine. It's fast. It's accurate. It requires zero infrastructure.

At 50–100 repos, the mental model starts cracking. Nobody can hold all the relationships in their head anymore. People start grepping across repos; cloning everything locally, running ripgrep, building a picture manually. It takes hours. The results are point-in-time snapshots that are stale by the next morning.

At 100–500+ repos, grep breaks down entirely. The dependency graph is too large, too dynamic, and spans too many ecosystems to track manually. The "right" answer to "who uses this module?" becomes "ask in the #platform channel and wait for replies."

The breaking point is almost always the same: someone pushes a breaking change and multiple downstream consumers fail. Nobody knew who to notify. Or a senior engineer leaves and their mental map of the org leaves with them. Or a new hire joins the platform team and literally cannot understand what depends on what.

It's not a Terraform problem — it's an org-wide visibility problem

When I first encountered this, I thought it was a Terraform thing. Terraform modules get sourced across repos, and there's no built-in way to know who's consuming a given module at which version.

But it's much bigger than Terraform.

The real-world dependency graph for a platform team includes Terraform module sources (via git URL or registry), Docker base images (often pinned to :latest everywhere), GitLab CI templates included by dozens of pipelines, GitHub Actions reusable workflows, Helm charts referencing other internal charts, Ansible roles and collections, Python packages installed from internal git URLs, Go modules, and npm packages published to internal registries.

These dependencies cross ecosystem boundaries. A Terraform module might reference a Docker image that's built by a CI pipeline that uses a shared template. The graph doesn't respect neat tool categories, and no tool today shows you the full picture across all of them.

The tribal knowledge problem

The part of this that resonates most with people — I've seen it in conversations, in Reddit threads, in every team I've worked with — isn't the technical complexity. It's the human cost.

Infrastructure dependency knowledge is tribal knowledge. It lives in the heads of whoever has been around the longest. There's no shared, always-current view. There's no way for a new engineer to sit down and understand the full dependency picture without weeks of archaeology.

When that senior engineer goes on holiday, decisions slow down. When they leave the company, that knowledge is gone permanently. The team doesn't even know what they've lost until something breaks and nobody can explain why.

This is the real cost: not that the dependency graph is complex, but that the only copy of it exists in human memory, and human memory doesn't scale, doesn't transfer, and doesn't survive attrition.

What people try — and where each approach falls short

I've seen teams try every reasonable approach. Each one solves part of the problem and fails at the rest.

Grep / ripgrep across repos

The first tool everyone reaches for. Clone the repos, run a search, assemble the picture manually.

It works, for a while. The results are a point-in-time snapshot with no history, no dashboard, and no way to handle transitive dependencies. At a hundred repos, it takes hours. It doesn't catch renamed references or implicit dependencies. And the results are stale the moment you close the terminal.

Backstage or a service catalog

Backstage looks like the right answer on paper. It's a developer portal with a service catalog. You define your dependencies in a catalog-info.yaml file per repo, and Backstage renders a graph.

The problem: it requires humans to register and maintain those YAML files. In practice, the catalog goes stale within weeks. As one engineer put it to me, it's "documentation with extra steps." If the dependency is registered in a YAML file that nobody updates, it's just a different kind of tribal knowledge.

Renovate or Dependabot

These tools are excellent at what they do: they automatically open pull requests when a dependency has a new version available. They solve the upgrade lag problem.

But they don't solve the visibility problem. Renovate doesn't tell you "who is consuming module X at which version right now." It reacts after a new version is published. It can't answer the question you need before you make a breaking change: "if I push v2.0 of this module, which 40 repos need to coordinate?"

HCP Terraform Explorer

HashiCorp's cloud platform has a module explorer that shows workspace-to-module relationships. It's the closest native solution.

But it only works for Terraform. It only works if your plan and apply runs through HCP Terraform. If your org has a mix of Terraform Cloud, self-hosted runners, Docker, CI templates, and Helm — and most do — you get a partial view with large blind spots.

"Just use a monorepo"

This is the most commonly suggested solution, and it's the least helpful for the teams who actually have this problem.

Monorepos are a valid architecture. But suggesting a monorepo to an org with three hundred existing repos, multiple teams with separate access controls, compliance boundaries, and maybe some repos inherited through an acquisition — that's like suggesting "just rewrite it in Rust." Technically valid. Not actionable.

And a monorepo still doesn't give you blast radius analysis. It just makes the grep slightly easier.

Building it yourself

This is the one that surprised me. Multiple teams I've talked to — and many more on Reddit — have independently built their own bespoke solutions. Nightly cron jobs that shallow-clone every repo, grep Dockerfiles and Terraform source blocks, dump the results to SQLite or a spreadsheet.

These solutions work. They prove the approach is sound. But they're brittle, org-specific, hard to maintain, and they go stale between runs. Nobody has the bandwidth to turn their weekend hack into a real product. They want a product to exist. It just doesn't.

Why the problem is getting worse, not better

Two trends are making this more painful every year.

Tool diversity is increasing. Five years ago, a platform team might have only been dealing with Terraform. Today the same team manages Terraform modules, Docker images, CI pipelines, Helm charts, Kubernetes manifests, and maybe Ansible. Every new tool in the stack adds a new class of cross-repo dependency that no existing tool tracks.

AI-assisted development is accelerating the sprawl. Teams ship code faster than ever with AI coding tools. But the AI writes the module — it doesn't know that three repos in another part of the org reference the interface it just changed. AI accelerates the creation of infrastructure code without any awareness of the existing dependency graph. That gap compounds every sprint.

The irony is that the tools keep getting better at everything except showing you how it all connects.

The pattern that works: auto-discovery from code

Across every DIY solution I've seen — and across the engineering community discussions I've been part of — the approach that works is always the same:

Scan the org — enumerate every repo via the GitLab or GitHub API.
Parse the actual files — Terraform source blocks, Dockerfile FROM statements, CI include directives, Helm chart dependencies, Python requirements, Go module files, npm manifests. Not metadata. Not YAML someone fills in. The real source files.
Build a directed graph — repo A depends on artifact X, which is produced by repo B. Store this as a queryable graph.
Keep it fresh — webhook-triggered or scheduled rescans so the graph is never stale.
Make it queryable — "show me everyone who consumes this Docker base image" should be a one-click answer, not a two-day grep expedition.

The fact that independent practitioners keep arriving at this same architecture tells you something important: the approach is sound. What's missing is a product that does it well, keeps it current, and works across every ecosystem a team actually uses.

What I'm building

This is the problem that led me to build Riftmap. It scans a GitLab or GitHub organisation, automatically discovers cross-repo dependencies across Terraform, Docker, CI templates, Python, Go, npm, Ansible, Helm, Kubernetes, Kustomize (and more coming) — and builds a queryable dependency graph with visual blast radius analysis.

No per-repo configuration. No YAML to maintain. One read-only token at the org level, and it discovers everything from the actual code.

It's currently in early access. If this problem sounds familiar, I'd genuinely like to hear how it shows up at your org — whether or not Riftmap is the right solution for you. The more I understand how different teams experience this, the better the tooling gets for everyone.

You can see more at riftmap.dev, or reach me directly at hello@riftmap.dev.

Riftmap Blog

Cross-repo blast radius in nine public platform orgs: the most depended-on repo at Grafana isn't Grafana

What I scanned, and what counts as an edge

The most depended-on repo at Grafana isn't Grafana

The hub is never the repo you would nominate

The ninth organisation, and the check I ran on my own parser

One in four repos is load-bearing, and that is a floor

Two false positives I had to throw out

Why I report direct dependents and not transitive

A repository declares what it depends on, never what depends on it

What this is not

Where this leaves you

Frequently asked

Which AI coding assistants can see blast radius before they change code?

The question hides a conflation

What each assistant can actually see today

Claude Code: access, by design

Cursor: the agent can chase the chain, not resolve it

GitHub Copilot: a context set you assemble by hand

The comparison, in one table

Why none of them can resolve it

What changes the answer: hand it the graph

The assistant was never the limitation

Questions I get asked

Blast radius in software engineering: what it is, how to measure it, how to contain it

The word is doing two jobs at once

What blast radius actually is

How to measure it

Dependency-graph BFS

Impact-based test selection

Change-failure-rate, the lagging outcome

The radius you can't see from one repo

How to contain it

The cloud sense: cell-based architecture and breach containment

The change-impact sense: flags and canaries

Structural containment: know the graph before the change ships

Questions engineers actually ask

What 242 Cloud Posse repos actually depend on

The shape of the org at a glance

The graph view: a star with two different centres

The pattern at the centre: one module, 147 consumers

Where the receipts live: context.tf, line 24

If I bump terraform-null-label, what breaks?

What Riftmap didn't see, and why

Methodology, briefly

Two asks

Where this sits in both series

Scan your own org

Common questions

Declared, inferred, registered: the three ways a tool knows a cross-repo dependency exists

"Parsed, not inferred" stages a two-horse race and quietly drops a third runner

Declared: the edge the machine already executes

What counts as declared

Why grep only half-sees it

Why a symbol graph misses it

Inferred: the edge guessed from statistical signal

Registered: the edge a human wrote in a catalog

A fourth mode: discovered at runtime, and why it is unavailable before merge

Does a parsed dependency edge need a confidence score?

The three regimes differ in what keeps each edge honest

Where Riftmap sits

Common questions

How to add a blast-radius gate to your merge pipeline

The gate is two GET requests

The GitLab CI recipe

The same gate in GitHub Actions

The self-updating version of CODEOWNERS

Where this gate stops

The pull requests nobody looks at twice

Questions engineers actually ask

Can AI check the blast radius of a PR before you merge?

One phrase, three graphs

The symbol layer: what code calls this code

The live-state layer: what running resources the plan touches

The artifact layer: which repos build on what you changed

Where the catalogs sit

The blast radius the AI reports is the blast radius of the graph

Common questions

You can index every repo in Cursor. It still can't tell you what breaks.

What Cursor's index actually is

Where the receipts live: `context.tf`, line 24

If I bump `terraform-null-label`, what breaks?