You maintain a shared GitLab CI template. You need to rename a job, change an input, or restructure the file. Which projects across your org include it? GitLab has been asked this question for nearly six years. Here's the paper trail, and the actual answer.
In October 2020, a platform engineer posted a question on the GitLab forum: ." "." " of this series, you know reusable workflows have the same visibility problem. GitLab's version has a structural twist that makes it sharper.
In GitHub Actions, uses: requires a ref. Every caller pins to something, even if that something is @main. In GitLab CI, ref: on a project include is optional, and when it's omitted, the include resolves to the HEAD of the template project's default branch. Per the . Read that second clause again. The dependency is real, and it is silent. GitLab's own . In a more recent puts it plainly: an include pointing at main means every consumer inherits template changes immediately with no opt-in, manually pinning SHAs or tags across dozens of repos is labour nobody actually does, so teams ride main and hope. does it better and faster, but it's a Premium/Ultimate feature, and on self-managed it requires you to stand up and operate the search infrastructure behind it, which a lot of instances simply haven't done.
Even where it works well, code search gives you matches, not answers. It doesn't extract the ref. It doesn't distinguish include: project: from a comment that happens to mention the path. It doesn't see the second hop: if your template is included by a wrapper template in another shared project, code search finds the wrapper, not the forty projects behind it. For a one-off audit it's a reasonable start. It is not a system.
The CI lint API
GitLab can show you the fully merged configuration for a single project, includes resolved, via the can detect project includes and open MRs to bump the ref. As with , Renovate implicitly knows who consumes what, because it's configured per consumer. But it's an updater, not a mapper. There's no org-level "show me every project that includes this template" view, and it has nothing to say about the unpinned includes, which are the majority and the most dangerous.
CI/CD Catalog analytics
This one deserves real credit, because GitLab has started answering the question. With GitLab 19.0, the CI/CD Catalog gained a is almost word-for-word the premise of this series: component maintainers previously had no way to identify which projects used their component or which versions, making breaking changes and deprecations hard to coordinate.
So the gap is closing. But look at what the closure covers. It covers include:component, resources published to the CI/CD Catalog. It is usage-event-based, derived from pipelines that actually ran recently, rather than parsed from what repos declare. And the per-project answer is Ultimate-only. The include:project template fleets, which is what nearly every self-managed enterprise estate actually runs on, including the devops/ci-templates repo in the scenario above, are not in scope. If you migrated your entire template library to Catalog components and bought Ultimate, GitLab now answers a 30-day usage version of the question. For everyone else, the 2020 forum thread is still the state of the art.
(GitLab also announced , with the added wrinkle that nested includes execute without context as a public user. If you change ci-base, the projects that break include projects that have never heard of ci-base. They included a template that included you. Finding the direct consumers is a string search. Finding the transitive ones requires a graph.
Includes are not the only cross-project CI edge. Multi-project pipelines via trigger: project: create a dependency on another project's pipeline. Parent-child pipelines via trigger: include: can pull child pipeline definitions from other projects. Cross-project needs: [{project, job, ref}] creates a dependency on another project's job artifacts. None of these are includes, all of them break when the upstream project changes, and a consumer map that only parses include: misses them.
The breaking surface is loosely typed. With is built to solve. It scans a GitLab (or GitHub) org and parses every project's CI configuration, emitting distinct edge types for project includes, remote includes, catalog components, multi-project triggers and cross-project needs, while deliberately skipping local and GitLab-shipped template includes. Template repos' own templates/*.yml and .gitlab/ci/*.yml files are parsed too, so when a template includes another template, that edge is in the graph, and the transitive chain from a base template to its end consumers is reconstructed across the org. Each edge carries the declared ref as a version constraint, or its absence, plus file and line provenance. Parsed from what the repos declare, not inferred from what recently ran.
The result: before you merge that job rename into devops/ci-templates, you open the graph, click the template repo, and read the consumer list. You know who breaks. You know who's pinned to a tag and has time, and who's riding an unpinned include and gets your change at merge time. You know who to notify, instead of finding out who you should have notified.
The dependency GitLab told you about
Here's the closing thought. GitLab's own documentation says that including another project's CI configuration is like pulling a third-party dependency. Take that sentence seriously and follow it to its conclusion. We have norms for third-party dependencies. We pin them. We track who uses them. We check the blast radius before publishing a breaking change. Somewhere along the way, shared CI templates became the one class of dependency where the ecosystem's answer to "who depends on this?" was grep your web server logs, and we collectively decided that was fine.
It was never fine. It was just invisible. The template that fifty projects include without a ref is the highest-leverage, least-observed dependency in your org. Treat it like one.
This is the sixth post in the , , .
If this is a problem your platform team deals with, I'd be interested to hear how you're solving it today. You can find more at riftmap.dev or reach me at [email protected].
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.
SOCIAL SHARE CARD GENERATOR