Mastering GitLab CI’s include:local Path Resolution Rules

Path resolution for include: local in GitLab CI

All paths in include: local are resolved relative to the project root, regardless of the location of the .gitlab-ci.yml file or any nested includes. This is a “project‑internal absolute path”.

Supported path syntax

Leading slash

include:
  - local: '/ci-templates/build.yml'

Starts from the repository root and points to ci-templates/build.yml . Recommended for clarity.

Without leading slash

include:
  - local: 'ci-templates/build.yml'

GitLab treats this identically to the leading‑slash form; the resolver still begins at the root.

Unsupported syntax

Using ../ to climb directories is invalid because all includes must stay within the project sandbox.

# Invalid example (file located in src/app/.gitlab-ci-part.yml)
include:
  - local: '../../ci-templates/build.yml'

Correct form:

include:
  - local: '/ci-templates/build.yml'

Visual reference

An example repository layout:

Best practices

Use a leading slash Write includes as local: '/ci/common.yml' to make the root‑based nature explicit.

Store templates in a dedicated folder Place reusable CI files in a top‑level directory such as .ci/ or ci-templates/ to keep paths short and consistent.

Avoid ../ Never use parent‑directory navigation with include: local ; it will cause pipeline failures.