Gitlab – Complete Details of .gitlab-ci.yml

By default, GitLab only uses one primary .gitlab-ci.yml file located at the root of your repository. However, you can modularize and use multiple CI/CD YAML files by including them from other locations. Here’s how it works:

✅ Ways to Use Multiple .gitlab-ci.yml Files

You can split your CI/CD logic into multiple files and include them in the main .gitlab-ci.yml using the include keyword:

1. Include Local Files

include:
  - local: 'ci-templates/build.yml'
  - local: 'ci-templates/deploy.yml'
Code language: PHP (php)

2. Include from Other Projects

include:
  - project: 'mygroup/ci-templates'
    file: '/templates/test.yml'
    ref: main
Code language: PHP (php)

3. Include from Remote URLs

include:
  - remote: 'https://example.com/gitlab-ci-templates/security.yml'
Code language: PHP (php)

4. Include Templates Provided by GitLab

include:
  - template: 'Security/SAST.gitlab-ci.yml'
Code language: PHP (php)

🔁 Merge Strategy

When GitLab reads your .gitlab-ci.yml, it merges the included files before executing the pipeline. All the jobs across all included files are considered part of the same pipeline.

🛠️ Use Case Example

# .gitlab-ci.yml at the root
include:
  - local: 'ci/build.yml'
  - local: 'ci/test.yml'
  - local: 'ci/deploy.yml'

stages:
  - build
  - test
  - deploy
Code language: PHP (php)

Each of the build.yml, test.yml, and deploy.yml would define jobs related to their stage.

🧠 Important Notes

• Only one .gitlab-ci.yml at the root is processed directly.
• You must use include to leverage other YAMLs.
• GitLab 12.3+ supports multiple includes.

Rajesh Kumar

I’m Rajesh Kumar, a DevOps, SRE, DevSecOps, Cloud, and Platform Engineering expert passionate about sharing practical knowledge, real-world experiences, and industry best practices. I have worked at Cotocus and regularly write about technology, travel, investing, health, product reviews, and digital marketing through my various platforms.

I publish technical articles at DevOps School, travel stories at Holiday Landmark, stock market insights at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow, and SEO and digital marketing strategies at Wizbrand.