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.

TypeSourceSample
localAnother file in the same repository/ci/build.yml
projectA file in a different projectmy-group/ci-templates
templateA template shipped with GitLabSecurity/SAST.gitlab-ci.yml
remoteA public web addresshttps://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

  1. Create a project named ci-templates inside your group.
  2. Add template files under a templates folder.
  3. Tag the first stable version as v1.0.0.
  4. Include the files from other projects with the project keyword and the tag.
  5. 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.