Components are easier to control than loose templates because they can be released and pinned to a version, and their inputs are validated. They are not automatically safe. GitLab says it cannot guarantee the security of third-party components, so pin to a commit SHA or release tag, and review changes before you move the pin.
What a component is
A CI/CD component is a reusable pipeline configuration unit. You include it with include: component, naming the instance host, project path, component name and a version after an @. Components can only come from projects on the same GitLab instance. They can be published to the CI/CD Catalog, though they work without being listed.
Version choices, strongest first
| Reference | Meaning | Risk |
|---|---|---|
| Commit SHA | The exact commit | Lowest, nothing moves |
| Tag such as 1.0.0 | A release | Low if tags are protected |
| Branch name | Whatever is on that branch | Higher, content changes |
~latest or partial like 1 | Newest matching release | Highest, may break or change |
GitLab's own wording on ~latest is to use it only if you want the absolute latest version at all times, which could include breaking changes.
Components versus templates
Templates and components both reuse configuration. The differences GitLab lists: components can be listed in the catalog, can be released and used at a specific version, and several can live in one project versioned together. They favor inputs over variables. Inputs are declared in a spec section and validated, so a missing required input produces a pipeline error, while an undefined variable is silently empty.
Steps to adopt one safely
- Read the component source. It runs with your job's access.
- Check what credentials and tokens the job will hold, and limit them.
- Pin to a commit SHA in production pipelines.
- Set up a review step when you move the pin, and read the diff.
- Protect the branches and tags of your own component projects, require merge request approvals, and use two-factor authentication.
- Avoid secrets in configuration files.
include:
- component: gitlab.example.com/platform/ci/scan@3f9a1c2d4e5b6a7c8d9e0f1a2b3c4d5e6f7a8b9c
inputs:
stage: test
The host, path and SHA above are examples.
Common mistakes
Teams often start with ~latest for convenience and forget to change it. Others pin a component but let its own includes float. A third mistake is giving a component job broad variables because it was easier than working out which ones it needs. Read the component's inputs and the variables it reads, then give it only what it must have. Keep a short record of which version each pipeline uses so an advisory about a component is easy to act on.
Try it yourself
Click through it at your own pace, or open it full screen. Notice that a pinned version is something you can list and compare, which is the same idea as an inventory.
For remote includes the trade is different, covered in project versus remote includes. Safeguard's dependency scanning and policies can help track what your pipelines pull in. A free scan is at https://gold.safeguard.sh/scan.
Quick check
Is the catalog a safety check?
No. GitLab says anyone can publish, so review components before use.
Do rules inside an included component trigger merge request pipelines?
GitLab says rules pulled in through include do not count for merge request pipeline matching, so define them in the main file.
Sources
- GitLab Docs: CI/CD components, fetched 19 October 2026.
- GitLab Docs: Merge request pipelines, fetched 19 October 2026.
Last reviewed: 19 October 2026.
