Mastering GitLab CI/CD: Using include:template, local, project, and remote

Introduction

In modern software development, CI/CD pipelines are essential for fast and reliable delivery. As projects grow, a monolithic .gitlab-ci.yml becomes hard to maintain. GitLab’s include keyword allows you to split pipeline configuration into reusable modules.

The Power of include:template

When you write include: - template: Auto-DevOps.gitlab-ci.yml (or similar) in .gitlab-ci.yml, you are referencing a set of CI/CD templates that are built into GitLab’s core codebase. These templates are not stored in your repository; they live in a public GitLab project and cover common scenarios such as building, testing, code quality scanning, and deployment. Exploring that repository reveals the source of the templates and advanced CI/CD techniques.

How to Add Custom Templates

Custom templates are supported via three other include methods: local, project, and remote. These give you flexibility to meet different organizational needs.

include: local : Project‑internal templates If a template is only reused within the same project, extract the reusable CI configuration (e.g., a generic build job) into a separate YAML file and reference it with the local keyword.

# .gitlab-ci.yml
include:
  - local: '/ci-templates/go-build.yml'  # import file from same repo
stages:
  - build
  - test
# ... other jobs

include: project : Shared templates across projects When multiple projects need the same CI logic, create a dedicated “CI/CD template” repository. Other projects can include a file from that repository by specifying the project path, reference (branch, tag, or commit SHA), and file name.

# .gitlab-ci.yml
include:
  - project: 'my-org/cicd-templates'
    ref: main
    file: '/go/go-build-template.yml'

include: remote : Templates from any URL This method lets you pull a template from any publicly accessible URL, such as a static site or another code‑hosting platform. Use it cautiously, as it introduces security risks if the URL is untrusted.

# .gitlab-ci.yml
include:
  - remote: 'https://gitlab.com/awesome-project/raw/main/.gitlab-ci-template.yml'

Visualization of Include Strategies

The following UML activity diagram illustrates how the main .gitlab-ci.yml acts as a “master conductor,” pulling configurations from different sources to assemble a complete pipeline.

Conclusion: Building Your Template System

The include:template shortcut is convenient for quickly adopting GitLab’s official best‑practice pipelines. However, to create a reusable, team‑specific CI/CD asset library, you should rely on local, project, and remote includes.

Prefer include: project Establish a central CI/CD template repository for your organization. This ensures consistency, simplifies maintenance, and speeds up onboarding of new projects.

Use include: local as a supplement For logic that is highly reused within a single project but not shared organization‑wide, split it into a local file to keep the main .gitlab-ci.yml clean.

Apply include: remote cautiously Only adopt remote templates when you have a clear, secure external hosting requirement.

By thoughtfully combining these include strategies, you can build a powerful yet maintainable automation pipeline that boosts development efficiency instead of becoming a burden.