GitLab CI Templates
A CI template is a reusable piece of pipeline configuration. Teams write the logic once and share it across many projects. A fix in one template reaches every project that uses it.
Think of a recipe book in a restaurant chain. Every branch follows the same recipe for pasta, and the head chef updates the recipe in one place.
Why Templates Matter
WITHOUT TEMPLATES Project A: 80 lines of build and test setup Project B: 80 lines, copied and slightly changed Project C: 80 lines, copied and slightly changed → A bug fix needs three edits WITH TEMPLATES Shared template: 80 lines, written once Project A: include template (2 lines) Project B: include template (2 lines) Project C: include template (2 lines) → A bug fix needs one edit
The include Keyword
The include keyword pulls configuration from another location into your .gitlab-ci.yml file.
| Type | Source | Sample |
|---|---|---|
| local | Another file in the same repository | /ci/build.yml |
| project | A file in a different project | my-group/ci-templates |
| template | A template shipped with GitLab | Security/SAST.gitlab-ci.yml |
| remote | A public web address | https://example.com/ci.yml |
Include a Local File
include: - local: '/ci/build.yml' - local: '/ci/test.yml' stages: - build - test
Splitting a long file into smaller files keeps each part readable.
Include from a Shared Project
include:
- project: 'my-group/ci-templates'
ref: v1.2.0
file: '/templates/node-build.yml'
The ref value pins a tag or branch. A tag keeps pipelines stable until the team chooses to upgrade.
Include a GitLab Template
include: - template: Security/SAST.gitlab-ci.yml
This single line adds a complete security scanning job to the pipeline.
Hidden Jobs
A job name that starts with a dot never runs by itself. Hidden jobs act as blueprints for real jobs.
.node-base:
image: node:20
before_script:
- npm ci
cache:
key:
files:
- package-lock.json
paths:
- node_modules/
The extends Keyword
A real job borrows every setting from a blueprint with extends. The job adds or overrides what it needs.
unit-tests:
extends: .node-base
stage: test
script:
- npm test
build-app:
extends: .node-base
stage: build
script:
- npm run build
artifacts:
paths:
- dist/
.node-base (image, install step, cache)
├── unit-tests adds: stage test, npm test
└── build-app adds: stage build, npm run build, artifacts
The default Keyword
The default block sets values for every job at once.
default: image: node:20 retry: 1 interruptible: true
A job that sets its own image overrides the default.
The !reference Tag
The !reference tag copies one piece of another job, such as a script list.
.setup:
script:
- echo "Preparing environment"
run-tests:
script:
- !reference [.setup, script]
- npm test
The final job runs both commands in order.
Build a Shared Template Project
- Create a project named ci-templates inside your group.
- Add template files under a templates folder.
- Tag the first stable version as v1.0.0.
- Include the files from other projects with the project keyword and the tag.
- Release new tags for every change and announce breaking changes in the release notes.
CI/CD Components
Components are versioned building blocks published in the CI/CD Catalog. A component accepts inputs, so one block adapts to many projects. Teams browse the catalog, pick a component, and include it with a version number. Components suit organizations that share pipelines across dozens of projects.
Check the Final Result
Open Build → Pipeline editor and select the Full configuration tab. The tab shows the merged file after every include and extends step. Use it to find out why a job behaves in a surprising way.
Template Best Practices
- Pin templates to a tag, never to a moving branch.
- Name hidden jobs after their purpose, such as .node-base or .deploy-base.
- Document required variables at the top of each template file.
- Test template changes in a sandbox project first.
- Keep each template focused on one task.
