How to Use includes and Templates in GitLab CI

The include: keyword pulls in YAML from local files, other projects, or GitLab-maintained templates so you do not repeat pipeline config.

Use include: to compose a pipeline from reusable fragments. Combine it with extends: to inherit and override job definitions across files.

Include and extend

Pull in a shared template, then extend a hidden base job to add specifics.

include:
  - local: '/ci/templates/test.yml'
  - project: 'my-group/ci-shared'
    file: '/jobs/deploy.yml'
    ref: main

.base_test:
  image: node:20
  before_script: [npm ci]

unit:
  extends: .base_test
  script: [npm run test:unit]

Gotchas

• Included files are merged before the pipeline runs; later definitions override earlier same-name keys.
• Hidden jobs starting with a dot (.base_test) are templates only and never run on their own.
• Pin project: includes with ref: so an upstream change does not silently alter your pipeline.

Key takeaways

• include: composes pipelines from local, project, or remote YAML.
• extends: plus hidden .jobs enables DRY job inheritance.
• Pin remote includes with ref: for reproducibility.

Related guides