In a GitLab CI .gitlab-ci.yml, what does the include: keyword pull in, and how do its local, project, remote and template forms differ?

## The problem `include` solves A platform team that owns build, test and deploy conventions does not want fifty repositories each carrying its own hand-edited copy of the same pipeline. `include:` is GitLab CI's answer: your `.gitlab-ci.yml` names other YAML files, GitLab fetches them while it is creating the pipeline, and the result is one merged configuration that the pipeline actually runs. The merge happens **once, at pipeline creation**. By the time jobs start, there is no trace of which file a job came from — GitLab has already flattened everything. That single fact explains most of the behaviour below. ## The four classic forms ### `include:local` ```yaml include: - local: '/ci/build.yml' ``` A path inside the same repository, always read from the **same commit that triggered the pipeline**. A merge request that edits `/ci/build.yml` therefore tests its own edited version — which is exactly what you want for reviewing pipeline changes. The path is absolute from the repository root; a leading slash is conventional. ### `include:project` ```yaml include: - project: 'platform/ci-templates' ref: 'v2.3.0' file: - '/build.yml' - '/deploy.yml' ``` A file from a **different project on the same GitLab instance**. `file:` accepts a list, so one entry can pull several files. `ref:` is the important one: omit it and GitLab uses the default branch's current HEAD, so someone merging to that template repository's default branch silently changes every consumer's next pipeline. Pin `ref:` to a tag when you want reproducibility, and leave it floating only when you deliberately want fleet-wide rollout. Access is checked against the user running the pipeline, so this form works for private projects — no extra credential to manage. ### `include:remote` ```yaml include: - remote: 'https://example.com/ci/build.yml' ``` A full URL fetched over HTTP(S) with a plain GET at pipeline creation. GitLab sends no credentials, so the file must be publicly readable, and whatever is served at that instant becomes part of your configuration. That is a supply-chain surface, and it is why most teams prefer `project` on their own instance. ### `include:template` ```yaml include: - template: 'Jobs/SAST.gitlab-ci.yml' ``` One of the templates shipped with the GitLab instance itself — the SAST, dependency-scanning and Auto DevOps building blocks. You do not host these; they come with the version of GitLab you are running, so an upgrade can change them. ### The fifth form: `include:component` Recent GitLab versions add `include:component`, which references a versioned CI/CD component published to the catalog and passes it typed `inputs:`. It is the modern replacement for pointing `include:project` at a template file and configuring it through global variables. ## Merge semantics you must know Included files are merged **in the order listed**, and your own `.gitlab-ci.yml` is applied last. If an included file defines a job named `build` and you also define `build`, the two are merged key by key and your local keys win — so overriding just the `image:` of a shared job is a three-line local block, not a fork of the template. ```yaml include: - project: 'platform/ci-templates' ref: 'v2.3.0' file: '/build.yml' build: # same job name as in the template image: node:22 # overrides only this key ``` Includes can nest — an included file may itself include others — and GitLab enforces a documented limit on how many files one pipeline may pull in, so deep template chains eventually fail at pipeline creation rather than at runtime. Duplicate includes of the same file are de-duplicated. ## Where it goes wrong The two classic failures are both about *when* things are read. First, an unpinned `include:project` means your pipeline configuration changed because someone else merged something — the commit that "broke the build" is not in your repository at all. Second, people expect `include` to be a runtime import and try to make the included file depend on job output; it cannot, because the merge is finished before the first job starts. Anything dynamic has to be expressed as `rules:` on the merged jobs, or as a child pipeline generated from an artifact. A third, quieter failure: an `include:` error is a **pipeline creation** error. The pipeline does not run at all and there are no red jobs to look at — you get a configuration error on the pipeline page, which is why `Validate` / the CI lint tool (with "include" expansion) is the right debugging tool.