{"id":49535,"date":"2025-05-28T05:39:49","date_gmt":"2025-05-28T05:39:49","guid":{"rendered":"https:\/\/www.devopsschool.com\/blog\/?p=49535"},"modified":"2025-05-28T05:39:49","modified_gmt":"2025-05-28T05:39:49","slug":"gitlab-complete-details-of-gitlab-ci-yml","status":"publish","type":"post","link":"https:\/\/www.devopsschool.com\/blog\/gitlab-complete-details-of-gitlab-ci-yml\/","title":{"rendered":"Gitlab &#8211; Complete Details of .gitlab-ci.yml"},"content":{"rendered":"\n<p>By default, GitLab only uses <strong>one primary <code>.gitlab-ci.yml<\/code> file<\/strong> located at the root of your repository. However, <strong>you <em>can<\/em> modularize and use multiple CI\/CD YAML files<\/strong> by including them from other locations. Here&#8217;s how it works:<\/p>\n\n\n\n<hr class=\"wp-block-separator has-alpha-channel-opacity\"\/>\n\n\n\n<h3 class=\"wp-block-heading\">\u2705 Ways to Use Multiple <code>.gitlab-ci.yml<\/code> Files<\/h3>\n\n\n\n<p>You can split your CI\/CD logic into multiple files and include them in the main <code>.gitlab-ci.yml<\/code> using the <code>include<\/code> keyword:<\/p>\n\n\n\n<h4 class=\"wp-block-heading\">1. <strong>Include Local Files<\/strong><\/h4>\n\n\n<pre class=\"wp-block-code\" aria-describedby=\"shcb-language-1\" data-shcb-language-name=\"PHP\" data-shcb-language-slug=\"php\"><span><code class=\"hljs language-php\"><span class=\"hljs-keyword\">include<\/span>:\n  - local: <span class=\"hljs-string\">'ci-templates\/build.yml'<\/span>\n  - local: <span class=\"hljs-string\">'ci-templates\/deploy.yml'<\/span>\n<\/code><\/span><small class=\"shcb-language\" id=\"shcb-language-1\"><span class=\"shcb-language__label\">Code language:<\/span> <span class=\"shcb-language__name\">PHP<\/span> <span class=\"shcb-language__paren\">(<\/span><span class=\"shcb-language__slug\">php<\/span><span class=\"shcb-language__paren\">)<\/span><\/small><\/pre>\n\n\n<h4 class=\"wp-block-heading\">2. <strong>Include from Other Projects<\/strong><\/h4>\n\n\n<pre class=\"wp-block-code\" aria-describedby=\"shcb-language-2\" data-shcb-language-name=\"PHP\" data-shcb-language-slug=\"php\"><span><code class=\"hljs language-php\"><span class=\"hljs-keyword\">include<\/span>:\n  - project: <span class=\"hljs-string\">'mygroup\/ci-templates'<\/span>\n    file: <span class=\"hljs-string\">'\/templates\/test.yml'<\/span>\n    ref: main\n<\/code><\/span><small class=\"shcb-language\" id=\"shcb-language-2\"><span class=\"shcb-language__label\">Code language:<\/span> <span class=\"shcb-language__name\">PHP<\/span> <span class=\"shcb-language__paren\">(<\/span><span class=\"shcb-language__slug\">php<\/span><span class=\"shcb-language__paren\">)<\/span><\/small><\/pre>\n\n\n<h4 class=\"wp-block-heading\">3. <strong>Include from Remote URLs<\/strong><\/h4>\n\n\n<pre class=\"wp-block-code\" aria-describedby=\"shcb-language-3\" data-shcb-language-name=\"PHP\" data-shcb-language-slug=\"php\"><span><code class=\"hljs language-php\"><span class=\"hljs-keyword\">include<\/span>:\n  - remote: <span class=\"hljs-string\">'https:\/\/example.com\/gitlab-ci-templates\/security.yml'<\/span>\n<\/code><\/span><small class=\"shcb-language\" id=\"shcb-language-3\"><span class=\"shcb-language__label\">Code language:<\/span> <span class=\"shcb-language__name\">PHP<\/span> <span class=\"shcb-language__paren\">(<\/span><span class=\"shcb-language__slug\">php<\/span><span class=\"shcb-language__paren\">)<\/span><\/small><\/pre>\n\n\n<h4 class=\"wp-block-heading\">4. <strong>Include Templates Provided by GitLab<\/strong><\/h4>\n\n\n<pre class=\"wp-block-code\" aria-describedby=\"shcb-language-4\" data-shcb-language-name=\"PHP\" data-shcb-language-slug=\"php\"><span><code class=\"hljs language-php\"><span class=\"hljs-keyword\">include<\/span>:\n  - template: <span class=\"hljs-string\">'Security\/SAST.gitlab-ci.yml'<\/span>\n<\/code><\/span><small class=\"shcb-language\" id=\"shcb-language-4\"><span class=\"shcb-language__label\">Code language:<\/span> <span class=\"shcb-language__name\">PHP<\/span> <span class=\"shcb-language__paren\">(<\/span><span class=\"shcb-language__slug\">php<\/span><span class=\"shcb-language__paren\">)<\/span><\/small><\/pre>\n\n\n<hr class=\"wp-block-separator has-alpha-channel-opacity\"\/>\n\n\n\n<h3 class=\"wp-block-heading\">\ud83d\udd01 Merge Strategy<\/h3>\n\n\n\n<p>When GitLab reads your <code>.gitlab-ci.yml<\/code>, it merges the included files <em>before<\/em> executing the pipeline. All the jobs across all included files are considered part of the same pipeline.<\/p>\n\n\n\n<hr class=\"wp-block-separator has-alpha-channel-opacity\"\/>\n\n\n\n<h3 class=\"wp-block-heading\">\ud83d\udee0\ufe0f Use Case Example<\/h3>\n\n\n<pre class=\"wp-block-code\" aria-describedby=\"shcb-language-5\" data-shcb-language-name=\"PHP\" data-shcb-language-slug=\"php\"><span><code class=\"hljs language-php\"><span class=\"hljs-comment\"># .gitlab-ci.yml at the root<\/span>\n<span class=\"hljs-keyword\">include<\/span>:\n  - local: <span class=\"hljs-string\">'ci\/build.yml'<\/span>\n  - local: <span class=\"hljs-string\">'ci\/test.yml'<\/span>\n  - local: <span class=\"hljs-string\">'ci\/deploy.yml'<\/span>\n\nstages:\n  - build\n  - test\n  - deploy\n<\/code><\/span><small class=\"shcb-language\" id=\"shcb-language-5\"><span class=\"shcb-language__label\">Code language:<\/span> <span class=\"shcb-language__name\">PHP<\/span> <span class=\"shcb-language__paren\">(<\/span><span class=\"shcb-language__slug\">php<\/span><span class=\"shcb-language__paren\">)<\/span><\/small><\/pre>\n\n\n<p>Each of the <code>build.yml<\/code>, <code>test.yml<\/code>, and <code>deploy.yml<\/code> would define jobs related to their stage.<\/p>\n\n\n\n<hr class=\"wp-block-separator has-alpha-channel-opacity\"\/>\n\n\n\n<h3 class=\"wp-block-heading\">\ud83e\udde0 Important Notes<\/h3>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Only <strong>one <code>.gitlab-ci.yml<\/code> at the root<\/strong> is processed directly.<\/li>\n\n\n\n<li>You must <strong>use <code>include<\/code><\/strong> to leverage other YAMLs.<\/li>\n\n\n\n<li>GitLab 12.3+ supports multiple includes.<\/li>\n<\/ul>\n\n\n\n<hr class=\"wp-block-separator has-alpha-channel-opacity\"\/>\n\n\n\n<p><\/p>\n","protected":false},"excerpt":{"rendered":"<p>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&#8230; <\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"","sticky":false,"template":"","format":"standard","meta":{"_joinchat":[],"footnotes":""},"categories":[2],"tags":[],"class_list":["post-49535","post","type-post","status-publish","format-standard","hentry","category-uncategorised"],"_links":{"self":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/49535","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/comments?post=49535"}],"version-history":[{"count":1,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/49535\/revisions"}],"predecessor-version":[{"id":49536,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/49535\/revisions\/49536"}],"wp:attachment":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/media?parent=49535"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/categories?post=49535"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/tags?post=49535"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}