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 a DevOps/SRE/DevSecOps/Cloud Expert passionate about sharing knowledge and experiences. I have worked at Cotocus. I share tech blog at DevOps School, travel stories at Holiday Landmark, stock market tips at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow , and SEO strategies at Wizbrand.

Do you want to learn Quantum Computing?

Please find my social handles as below;

Rajesh Kumar Personal Website
Rajesh Kumar at YOUTUBE
Rajesh Kumar at INSTAGRAM
Rajesh Kumar at X
Rajesh Kumar at FACEBOOK
Rajesh Kumar at LINKEDIN
Rajesh Kumar at WIZBRAND