GitLab Well Architected
Cookbook navigation
Agents / blast-radius-explorer

Find the projects affected by a library change

On this page
Human in the loopArchitectureCode reviewCross-projectImpact analysisOrbit

Use GitLab Duo with Orbit to find callers, check what a library change means for them, and choose a useful regression test.

AgentGitLab Duo
UsesOrbit
WhereGitLab web UI
ScopeCross project
AvailabilityGitLab.com · BetaOfficial guide
StartOpen GitLab Duo Chat on the merge request

A one-line change to a shared library can affect several projects. Before merging it, you'd like to know who calls the changed function, what those callers receive, and which tests would catch a problem.

GitLab Duo can use Orbit to find imports and callers, then read their source alongside your merge request. You review the result in a conversation. There's no custom Flow to install, and the prompts below ask for an explanation without posting comments or creating follow-up work.

This is useful when callers live in other projects. You're probably not going to need it for a private helper, a refactor that doesn't change behavior, or a change whose callers are already being validated in the same pipeline.

Before you begin

You'll need Premium or Ultimate, access to GitLab Duo Agent Platform, and a merge request that changes a library used by other projects. Orbit Remote is currently a GitLab.com beta with feature-controlled availability; check that it's available to your group before starting. GitLab's Orbit setup guide explains its availability and access requirements.

If you'd like to follow a known example first, try the library-change exercise. It supplies a shared package, two callers, and a documentation-only project. Those files are for following along; you can use the same approach with your own code.

Enable Orbit for your conversation

  1. Have a top-level group Owner open Your Work > Orbit > Configuration, find the group in Indexes, and toggle Enable. Subgroups inherit indexing. Wait for the projects you want to inspect to be indexed.
  2. In the top-level group's Settings > GitLab Duo > Change configuration, enable Allow external MCP tools and save. In GitLab 19.4, Orbit tools reach the conversation through a GitLab-managed MCP connection, so Duo needs this group permission even though you don't register a separate Orbit server. See GitLab's MCP setup instructions.
  3. In your personal Preferences, find Orbit in GitLab Duo, enable Use Orbit in GitLab Duo and Agentic Chat, then save. This preference applies to your account, not just the project you're viewing.
  4. Open your merge request, start a new GitLab Duo conversation, and check that Orbit is on. Choose GitLab Duo from the agent menu; the separate agent named Orbit isn't required.

You need at least the Reporter role to query an indexed group, and access to the projects you're asking about. Orbit searches indexed code; the merge request supplies the proposed change that isn't on the default branch yet.

1. Ask about the change and its callers

Name the merge request, the function, and a small subgroup that contains the projects you want checked. Replace the example names in this prompt:

Before I merge shared-client!1, which projects in my-group/library-check need to check their use of normalizeAccountId?

Use Orbit to find imports and callers, then read the MR diff and the caller source. Keep every query within that subgroup: list its projects first and use their project IDs to restrict the graph queries. If a query fails, explain the problem rather than searching outside that group.

Show me what changes for each caller, using one example input and a source link. Read the package manifests too, so we can tell how the changed library would reach each project. A README mention alone isn't a caller.

Use current code and graph results, not earlier reports or discussions on the MR. Keep the answer short, with project names rather than numeric IDs. Keep this read-only: don't post comments, create issues, or change files.

You'll want a report that points to actual calls and explains the changed result. A list of projects mentioning the package isn't enough to decide who needs to test it.

Pick one reported caller and open its source link. Check the arguments it passes and whether an explicit option avoids the changed default. In the supplied example, both callers omit trimEdges, so changing that default changes the account identifier they receive.

Then check how the project gets the library. Merging a library change doesn't necessarily update its consumers: a project may stay on its current package version until someone upgrades it. Ask Duo to distinguish those two steps if its answer treats them as the same event.

Separate what the source shows from what we still need to check. When would this project actually use the proposed library version? Don't assume an installation or deployment process that isn't in the files you read.

Expand an actions taken group to see whether Duo used Orbit and which projects it queried. If it starts searching outside your subgroup, stop the response and check the scope before continuing. If the search failed or a project wasn't indexed, ask for that missing check before treating the result as complete.

3. Turn the finding into a test

Ask for a small check of the behavior the caller cares about:

Suggest a regression test for each caller using the same input before and after the library change. Explain which result the project currently expects. Keep suggested tests separate from anything you've actually run.

For the example's billing worker, the useful question is whether the lookup key still matches the identifier the application expects. It isn't enough to update a test to the library's new output without deciding whether that output is right for the caller.

You can then choose to change the library, update a caller, or coordinate an upgrade with its owner. The conversation hasn't created issues or changed repositories; you decide what happens next.

Try a change that shouldn't need coordination

A private-helper rename makes a useful comparison. Ask Duo to read that MR's diff and explain whether callers receive anything different. The evaluation walkthrough includes this case, runnable checks, and examples of what to look for in the answer.

Use the same approach on your own projects by changing the MR and search subgroup. You'll want to check generated clients, runtime-loaded code, and consumers outside that subgroup separately when they matter to the change.

Guide files

Preview a file here, or download the example to follow along.

Download example
Files21
  • evals21
    • fixtures17
      • changes4
        • changed-default3
          • src1
          • test1
        • private-helper1
          • src1
      • projects13
        • billing-worker4
          • src1
          • test1
        • checkout-service4
          • src1
          • test1
        • integration-notes1
        • shared-client4
          • src1
          • test1
    • images2
    • scripts2
evals/fixtures/changes/changed-default/README.mdmarkdown · 6 lines
# Shared account client

`normalizeAccountId` collapses runs of whitespace and now trims the edges by default. Callers can pass `{ trimEdges: false }` to preserve one space at either edge.

Run `npm test` to check the exported function. The two consumer projects declare a `file:../shared-client` dependency so adjacent local clones can test an unmerged version. Merging or publishing this repository doesn't automatically upgrade another project.

Source file

File