Skip to main content
Mapagam

Working with Include and Templates

1. Including Local Files

Property Description Example
include Specifies local files to include in the pipeline configuration include: 'path/to/config.yml'
include.local Path to local file to include (relative to project root) include.local: 'ci/templates.yml'
include.file File name to include from a local directory include.file: 'build-template.yml'

Example: Including a local template file

include:
  local: '.gitlab/ci/templates.yml'

variables:
  IMAGE: "alpine:latest"
Note: The include.local path is relative to the project root and must be a valid file path.

2. Including Remote Files

Property Value Description
include remote: 'https://gitlab.com/example/project/-/raw/main/.gitlab-ci.yml' Includes a remote file using the remote keyword

Example: Including a remote CI configuration

include:
  remote: 'https://gitlab.com/example/project/-/raw/main/.gitlab-ci.yml'
Note: The remote file must be accessible via a public URL or have proper authentication set up in GitLab.

3. Using Project Templates

Property Description Example
include Specifies the path to a template file or a project template include: 'path/to/template.yml'
extends Allows extending a template from another project or group extends: 'group/template'
local Defines a local template within the current project local: 'local-template.yml'

Example: Using a Project Template

include:
  project: 'my-group/my-project'
  file: 'templates/ci-template.yml'
  ref: 'v1.0'

Example: Extending a Template

extends:
  project: 'my-group/my-project'
  file: 'templates/base-template.yml'
  ref: 'main'
Note: Templates must be defined in a YAML file and can include variables, jobs, and stages.

4. Including GitLab Templates

Template Type Description Usage Notes
project_template Predefined templates from GitLab's template library include: with project_template Available in GitLab Premium and Ultimate
file Custom templates defined in a project's files include: with file Can be local or from a remote repository
remote Templates from a remote Git repository include: with remote Requires a valid Git URL and token if private

Example: Using a project template

include:
  project_template: "GitLab CI Templates/Node.js"

Example: Including a local template file

include:
  file: "templates/ci-template.yml"

Example: Including a remote template

include:
  remote: "https://gitlab.example.com/group/template.git"
Note: Templates can be used to define shared CI/CD configurations across multiple projects.
Warning: When using remote templates, ensure the source is secure and trusted to prevent code injection.

5. Using Component-Based Includes

Component-based includes in GitLab CI/CD allow you to modularize your CI configuration by reusing predefined components across multiple projects or pipelines. These components can encapsulate common jobs, stages, or even entire pipeline structures.

Property Description Example
include Specifies the component to include in the pipeline configuration. include: "component.yml"
component.name Name of the component to be included. name: "build"
component.source Source of the component, can be a local file or a remote URL. source: "https://example.com/component.yml"

Example: Including a Component

include:
  component: "build.yml"

job:
  script:
    - echo "Running build job"
Note: Components must be valid YAML files and should define jobs or stages that can be merged into the main pipeline configuration.

6. Extending Job Configurations

Property Description Values
extends Specifies the configuration to extend from job_name or template_name
variables Variables to override or add to the extended job Object with key-value pairs
needs Jobs that must complete before this job runs Array of job names or job_name

Example: Extending a Job Configuration

job_template:
  script:
    - echo "Running job template"
  variables:
    ENV: "test"

extended_job:
  extends: job_template
  script:
    - echo "Extended script"
  variables:
    ENV: "production"

7. Using Hidden Jobs

Example: Define a hidden job

job_template:
  <span class="highlight">hidden</span>: true
  script:
    - echo "This job is hidden from the UI"
Property Description Default
hidden When set to true, the job is not displayed in the UI false
Note: Hidden jobs are still executed and can be used for configuration or as templates.

8. Creating Reusable Job Templates (!reference)

Property Description Example
!reference Allows reusing job definitions from templates or other parts of the configuration 
job_template:
  script:
    - echo "Hello World"
  artifacts:
    paths:
      - build/

build_job:
  !reference [*job_template]
  script:
    - echo "Building..."

Example: Using !reference to extend a template

job_template:
  script:
    - echo "Running tests"
  artifacts:
    paths:
      - coverage/

test_job:
  !reference [*job_template]
  script:
    - echo "Running integration tests"
Note: The !reference tag merges the referenced configuration with the current job, allowing for overrides and extensions.
Warning: Nested references may not work as expected in some GitLab versions. Always test in your environment.

9. Overriding Included Jobs (job redefinition)

Property Description Values
extends Specifies the template or include to extend from template-name
variables Variables to override or add in the included job { VAR1: "value1" }
script Script to override or append to the included job's script ["echo 'overridden script'"]
only/except Conditions to override or append to the included job's rules { only: ["main"] }

Example: Overriding a job script

include:
  - local: "templates/job-template.yml"

job_name:
  extends: job_template
  script:
    - echo "Overridden script"
    - npm test
Note: When overriding a job, all properties not explicitly overridden will retain their values from the included template.

10. Using Template Variables (TEMPLATE_*)

Variable Description Example Value
TEMPLATE_NAME Name of the template being used gitlab-ci-template-v1
TEMPLATE_VERSION Version of the template being used v1.2.0
TEMPLATE_SOURCE Source of the template (e.g., project, group, or global) project

Example: Using Template Variables in a Job

job_with_template_vars:
  script:
    - echo "Template Name: $TEMPLATE_NAME"
    - echo "Template Version: $TEMPLATE_VERSION"
    - echo "Template Source: $TEMPLATE_SOURCE"

Was this article helpful?

Related Cheat Sheets