When several projects copy the same build or test jobs, a small improvement can become a round of nearly identical merge requests. Some copies get updated; others quietly diverge. Shared pipeline configuration helps when teams need the same behavior and someone can maintain it for them.
Start by sharing a job that several projects repeat, such as running a language-specific test suite and collecting its reports. Give consumers a reviewed version, a small set of meaningful choices, and an understandable upgrade path. You don't need every project to adopt one pipeline, and you don't need to replace a working versioned include with a component just to make it reusable.
Start with work that really repeats
Choose a few projects with similar jobs and compare what happens when a change moves through them. Read the configuration alongside recent pipelines: which commands run, which reports and artifacts are produced, which jobs wait for them, and where failures need human attention. Ask the application maintainers which parts they repeatedly repair or copy.
For example, several Maven projects might use the same tool image, dependency-cache approach, test command, and JUnit report collection. Those are promising candidates for a shared test job. Their deployment environments, release approvals, and database migrations might differ enough to stay in each application project.
Compare the differences before turning them into options. A repository directory and a supported toolchain version are settings consumers often need to choose. A switch for every line of the job can leave consumers maintaining the same complexity through a different interface. If two groups need different build behavior, two smaller shared jobs may be easier to understand than one job with many interacting switches.
Prefer a first candidate that has several willing consumers and a visible maintenance problem. Keep an unusual job local until you understand whether its differences recur elsewhere. Reuse should reduce repeated work, not make teams wait for a central change whenever their application needs something different.
Choose includes or components for the way you'll maintain them
These choices can coexist in the same organization:
| Approach | When to use it | What you'll maintain |
|---|---|---|
include:local |
Breaking one project's configuration into readable files that change together | The files and their consumers in the same repository |
include:project with a chosen ref |
Sharing configuration from another project without introducing Catalog publishing | The shared files, release references, access, and consumer upgrade guidance |
include:component |
Packaging named reusable jobs for consumers, with optional CI/CD Catalog discovery | Component documentation, tests, releases, and supported versions |
Both included configuration files and components can use spec:inputs. Choosing inputs doesn't require moving to components. Keep a versioned project include if teams already understand it and can find its documentation and releases. Consider components when people need to discover reusable jobs, compare versions, and adopt them beyond the original group of maintainers.
Consider the release unit as well as the file layout. Components in one project share a version and release together. Put related components together when that helps consumers upgrade them together; use separate projects when their owners or release schedules genuinely differ.
Project includes and component references resolve within the same GitLab instance. For a component hosted on GitLab.com that you'll use on GitLab Self-Managed, arrange a local mirror and decide who keeps it current. For private shared projects, check that the identities creating consumer pipelines have the required access. A successful pipeline run by the shared project's maintainer doesn't prove that every application contributor can use it. include:remote doesn't support authentication, so it isn't a substitute for access to a private project.
Make the first adoption easy to understand
Give consumers a short example using an actual supported release. Explain what the job does, what the application must provide, and what later jobs can use. Keep the example small enough that a maintainer can distinguish the choices they need to make from the defaults they can accept.
For a shared test job, explain these choices:
| Consumer choice | Example guidance |
|---|---|
| Where the application lives | project-directory defaults to .; a monorepo consumer can choose services/orders |
| Which toolchain to use | java-version accepts the versions the maintainer tests and supports |
| Where the job fits | stage defaults to test; explain any jobs or artifacts it needs first |
| How to include it more than once | A job-prefix distinguishes the orders and payments jobs |
| What the job produces | Describe the test report location, retained artifacts, and failure behavior |
Define the file's choices with spec:inputs, and pass consumer values with include:inputs. Use descriptions, types, defaults, and allowed values to catch mistakes before jobs start. An input without a default is required, so introduce new required inputs as a consumer-facing change. These configuration inputs are evaluated during pipeline creation and stay fixed for that run; they aren't a mechanism for passing values produced by an earlier job. Keep secrets out of inputs and obtain them through the job's appropriate credential mechanism.
Explain the less visible expectations too. Which pipeline events should create the job? Does it require a particular runner capability, network destination, or registry permission? Does a failed test fail the job, or only produce a report? A reusable job that changes these behaviors can surprise consumers even when its command still succeeds.
Included configuration merges into the consumer's configuration. Components aren't isolated execution units: matching job names can merge, and global configuration can affect unrelated jobs. Prefer distinctive names and job-level settings. Let the consumer choose a stage or prefix where that solves a real integration need, and avoid taking over the project's workflow unless supplying a whole pipeline is the agreed purpose.
Including a component also doesn't copy neighboring scripts from its repository into the consumer checkout. If the shared job needs a helper script, provide it through a maintained tool image or another reviewed, versioned delivery method. An example that only works because the component repository contains the helper will mislead an application team trying to adopt it.
Review shared code with the access its jobs will have
Treat a reusable job as a software dependency. Read the commands it runs and follow its nested includes, images, downloaded scripts, and package dependencies far enough to understand what executes. Choose reviewers who understand both the toolchain and the consumer's use of it. A trusted project name or Catalog entry doesn't replace that review.
Pay particular attention when a change adds network access, requests credentials, publishes an artifact, or changes the image running a job. The same shared configuration may be harmless in a test project and consequential in a release project. Consumers still need suitable runner separation by workload trust, narrow credentials, and control over where publication or deployment can happen.
A shared file is a way to distribute configuration, not a way to ensure that every project runs a required control. Consumers can override included configuration. If an organization needs enforcement, choose the relevant policy and permission controls separately; don't infer enforcement from an include being present.
Use a full commit SHA when consumers need an exact configuration revision. A named release such as 1.4.2 is easier to discuss, but the maintainers must protect its tag from being moved or deleted. Pin important nested dependencies too: an unchanged YAML revision can still run different code if it pulls a moving image tag or downloads a script from a branch. Balance that stability with scheduled dependency updates, so pinning doesn't become indefinite neglect.
Test where consumers will use it
Keep tests with the shared configuration, using the candidate revision rather than the last release. Include small sample applications where they help exercise the behavior. Check results, not just successful pipeline creation: a test job should fail for a failing test and publish the expected report; a packaging job should produce the expected package.
Then try the candidate in representative consumer projects. Include an ordinary application and a meaningful variation, such as a monorepo, a project with a different stage layout, or one that uses the same shared job twice. Agree with their maintainers on safe test destinations before exercising publication or deployment. You don't need every project in the first trial, but testing only the shared repository misses the interactions you're trying to support.
Use CI Lint and the pipeline editor's full configuration view to inspect what GitLab will assemble. These help find syntax, dependency, and merge problems, but they don't execute jobs. The editor's full configuration evaluates conditional rules using a default-branch push assumption, and CI Lint's pipeline simulation is a push simulation. Neither substitutes for trying the merge request, tag, or scheduled paths your consumers use.
Pay attention to overrides during these trials. Included mappings can merge, while arrays such as script and rules are replaced rather than extended item by item. A consumer replacing a script to add one command can accidentally remove the shared job's setup. Inspect the assembled configuration and decide whether that consumer needs a supported input, a separate local job, or a different shared job.
Test the paths that should do nothing as well. A merge request shouldn't publish a release merely because a new default changed its rules. Try missing required inputs, unsupported option values, and the contributor permissions used in normal work. These checks make the adoption example more credible than a green pipeline run with unusually broad access.
Roll out a release that consumers can choose
Release after the representative trials succeed. Describe behavior changes, any consumer edits, and how to return to the previous version. A change to job names, artifacts, defaults, permissions, or pipeline events can break consumers even if no input was removed. Include those changes in release notes and version decisions.
Begin adoption with a small group of willing teams. Update the shared reference in a merge request, inspect the resulting configuration, and run the pipeline paths that matter to that project. Compare its reports, artifacts, access needs, and execution time with the previous job. Remove the old copied configuration after the replacement works; leaving both paths indefinitely makes failures and ownership harder to understand.
Choose how much update movement consumers will accept. An exact reference lets each team review when it upgrades. Published Catalog components also support partial semantic versions: 1.2 selects the latest published 1.2.* release, while ~latest can cross major versions. Those selectors don't apply to ordinary project-include references. Automatic patch selection may suit low-risk jobs with dependable compatibility tests; an exact revision is a better fit when a release path needs tighter change control. A semantic version is a maintainer's compatibility promise, not proof that the change is safe for every consumer.
Remember when configuration is fetched. Retrying an existing job uses the configuration captured for its pipeline; creating a new pipeline fetches includes again. A shared-project change doesn't automatically start pipelines in all its consumers. To evaluate an update or correction, use a new consumer pipeline with the intended reference rather than assuming a retry will pick it up.
Keep the previous working reference available during rollout. Reverting to it can restore the earlier configuration for a new pipeline, but it doesn't undo a package publication, a changed environment, or another external action already performed. Handle those effects through the affected system's recovery process.
Maintain the upgrade path, not just the shared file
Name a maintainer and a backup, and give consumers one place to ask questions or report a failing upgrade. Make that support path part of the adoption example. Application teams should know whether to change their local configuration, propose an improvement to the shared job, or report a regression.
Keep enough visibility into consumers and their chosen versions to plan changes. For a small set of projects, repository searches and a few upgrade merge requests may be sufficient. A larger user base may justify automation that proposes reference updates. Use the simplest approach that lets you reach affected teams when an upgrade matters.
When retiring a version or replacing a shared job, explain the replacement, the required consumer changes, and how long you'll maintain the old path. Offer a migration example and try it with an affected application team. Stop recommending the old version before removing it, and check for remaining consumers before deleting a referenced file or release. If a version has a security problem, explain the urgency and the safe replacement instead of silently moving its tag.
Judge the approach by a recent change that consumers actually received. Could the maintainer fix a defect once, test it with representative applications, and help teams upgrade without reconstructing their pipelines? Are teams using the supported options, or repeatedly replacing most of the shared job? Frequent overrides can mean the shared job is trying to do too much or serves the wrong group of applications.
Also compare the operational result: test reports still give teams the information they need, artifacts remain usable, unexpected publishing hasn't appeared, and queue or execution time hasn't worsened without a reason. Fewer lines of application YAML are a convenience. Less repeated repair work, understandable failures, and manageable upgrades are the stronger evidence that reuse is helping.
Further Reading
- Use CI/CD configuration from other files helps you choose include patterns and understand how consumer overrides merge.
- CI/CD inputs explains how to define, validate, and pass the choices your shared jobs accept.
- CI/CD components covers component packaging, testing, version selection, and publication to the CI/CD Catalog when that distribution model fits.
- Pipeline editor and CI Lint help you inspect assembled configuration and check pipeline creation before running consumer trials.
- Pipeline security helps you review included code and the credentials and dependencies available to its jobs.