DEV Community: Daniel Westgaard

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

Daniel Westgaard — Sat, 04 Jul 2026 13:37:47 +0000

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 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 08:56:40 +0000

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.

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 14:22:46 +0000

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-02 with one read-only token: 242 repositories in about thirteen and a half minutes, zero errors, no per-repo configuration. The PR we will pretend to open is against 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.

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 Claude Code, Cursor, and the graph neither sees.

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 11:44:12 +0000

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 09:19:21 +0000

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.

What 208 kubernetes-sigs repos actually depend on

Daniel Westgaard — Mon, 29 Jun 2026 12:20:16 +0000

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

See it live

Try the same Impact Mode yourself

The kubernetes-sigs scan isn't published as a live demo yet — but the Prometheus org is, with the exact interactive Impact Mode described above. Click any repo and watch its blast radius cascade across the graph.

Explore the live graph →

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.

Change failure rate is up 30% — here's how to measure yours in an afternoon

Daniel Westgaard — Mon, 29 Jun 2026 12:18:58 +0000

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.

See it live

Cut the failures you can see coming

Most change failures are blast-radius surprises — a downstream consumer nobody flagged in review. Open the live Prometheus graph, click any repo, and toggle Impact Mode to see exactly who breaks before the change merges.

Explore the live graph →

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

How to Find Every Consumer of Your Internal Python Package

Daniel Westgaard — Mon, 29 Jun 2026 12:18:12 +0000

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.

Backstage alternatives in 2026: first ask why you wanted Backstage

Daniel Westgaard — Mon, 29 Jun 2026 12:16:23 +0000

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.

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 covers 15 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.

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

Auto-Discovering Infrastructure Dependencies Across 10 Ecosystems

Daniel Westgaard — Mon, 29 Jun 2026 12:16:17 +0000

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 State of Infrastructure Dependency Tooling in 2026

Daniel Westgaard — Mon, 29 Jun 2026 12:08:46 +0000

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.

The catalog maintenance trap: why service catalogs go stale

Daniel Westgaard — Mon, 29 Jun 2026 12:08:38 +0000

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.

DEV Community: Daniel Westgaard

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

Tuning the index for a large or multi-repo codebase

Scope the index: open the package, not the root

The two ignore files, and which one you actually want

Multiple repositories: the multi-root workspace

Project rules and hierarchical ignore

The freshness you're actually working with

The question a tuned index still can't answer

The graph that answers it is parsed, not tuned

Questions teams ask

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

What each agent can actually see today

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

Widen the window with /add-dir

Write the map in CLAUDE.md

Add the graph as an MCP tool

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

The wall both share, and the graph that clears it

Wiring the graph into Claude Code and Cursor

Tier one: let the agent call the API

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

Tier three: make it a gate, not a hint

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

Questions teams ask

What 208 kubernetes-sigs repos actually depend on

The shape of the org at a glance

The graph view

The pattern at the centre

Where the receipts live

If I changed cluster-api, what breaks?

What Riftmap didn't see (and why)

Methodology, briefly

Two asks

Change failure rate is up 30% — here's how to measure yours in an afternoon

What CFR actually measures

The 90-minute version

The cut nobody is making yet

What to do with the number

FAQ

Closing

Sources referenced

Related reading

How to Find Every Consumer of Your Internal Python Package

The scenario

The change you ship without shipping it

What existing tools give you (and where they stop)

PyPI, deps.dev, libraries.io, GitHub dependents

pip show, pipdeptree, and the reverse-dependency tools

The private index itself

`pip show`, `pipdeptree`, and the reverse-dependency tools