YAML files are parsed before the pipeline is created, so the following pipeline predefined variables
are **not** available:
-`CI_PIPELINE_ID`
-`CI_PIPELINE_URL`
-`CI_PIPELINE_IID`
-`CI_PIPELINE_CREATED_AT`
For example:
```yaml
include:
project:'$CI_PROJECT_PATH'
file:'.compliance-gitlab-ci.yml'
```
-[`include:local`](#includelocal)
-[`include:file`](#includefile)
-[`include:remote`](#includeremote)
-[`include:template`](#includetemplate)
For an example of how you can include these predefined variables, and the variables' impact on CI/CD jobs,
see this [CI/CD variable demo](https://youtu.be/4XR8gw3Pkos).
**Additional details**:
#### `rules` with `include`
- Use merging to customize and override included CI/CD configurations with local
- You can override included configuration by having the same job name or global keyword
in the `.gitlab-ci.yml` file. The two configurations are merged together, and the
configuration in the `.gitlab-ci.yml` file takes precedence over the included configuration.
> - Introduced in GitLab 14.2 [with a flag](../../administration/feature_flags.md) named `ci_include_rules`. Disabled by default.
> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/337507) in GitLab 14.3.
> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/337507) GitLab 14.3.
> - [Feature flag `ci_include_rules` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/337507) in GitLab 14.4.
> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/337507) in GitLab 14.4.
**Related topics**:
You can use [`rules`](#rules) with `include` to conditionally include other configuration files.
You can only use [`if` rules](#rulesif) in `include`, and only with [certain variables](#variables-with-include).
`rules` keywords such as `changes` and `exists` are not supported.
```yaml
include:
-local:builds.yml
rules:
-if:'$INCLUDE_BUILDS=="true"'
-local:deploys.yml
rules:
-if:$CI_COMMIT_BRANCH == "main"
test:
stage:test
script:exit 0
```
-[Use variables with `include`](includes.md#use-variables-with-include).
-[Use `rules` with `include`](includes.md#use-rules-with-include).
#### `include:local`
Use `include:local` to include a file that is in the same repository as the `.gitlab-ci.yml` file.
Use a full path relative to the root directory (`/`).
Use `include:local` instead of symbolic links.
If you use `include:local`, make sure that both the `.gitlab-ci.yml` file and the local file
are on the same branch.
**Keyword type**: Global keyword.
You can't include local files through Git submodules paths.
**Possible inputs**: A full path relative to the root directory (`/`).
The YAML file must have the extension `.yml` or `.yaml`. Wildcard paths (`*` and `**`) are supported.
All [nested includes](#nested-includes) are executed in the scope of the same project,
so it's possible to use local, project, remote, or template includes.
Example:
**Example of `include:local`**:
```yaml
include:
...
...
@@ -514,44 +440,31 @@ You can also use shorter syntax to define the path:
include:'.gitlab-ci-production.yml'
```
Use local includes instead of symbolic links.
##### `include:local` with wildcard file paths
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25921) in GitLab 13.11.
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/327315) in GitLab 14.2.
You can use wildcard paths (`*` and `**`) with `include:local`.
Example:
```yaml
include:'configs/*.yml'
```
When the pipeline runs, GitLab:
**Additional details**:
- Adds all `.yml` files in the `configs` directory into the pipeline configuration.
- Does not add `.yml` files in subfolders of the `configs` directory. To allow this,
add the following configuration:
- The `.gitlab-ci.yml` file and the local file must be on the same branch.
- You can't include local files through Git submodules paths.
- All [nested includes](includes.md#use-nested-includes) are executed in the scope of the same project,
so you can use local, project, remote, or template includes.
```yaml
# This matches all `.yml` files in `configs` and any subfolder in it.
include:'configs/**.yml'
**Related topics**:
# This matches all `.yml` files only in subfolders of `configs`.
include:'configs/**/*.yml'
```
-[Use `include:local` with wildcard file paths](includes.md#use-includelocal-with-wildcard-file-paths).
#### `include:file`
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53903) in GitLab 11.7.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53903) in GitLab 11.7.
> - Including multiple files from the same project [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26793) in GitLab 13.6. [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/271560) in GitLab 13.8.
To include files from another private project on the same GitLab instance,
use `include:file`. You can use `include:file` in combination with `include:project` only.
Use a full path, relative to the root directory (`/`).
For example:
**Keyword type**: Global keyword.
**Possible inputs**: A full path, relative to the root directory (`/`).
The YAML file must have the extension `.yml` or `.yaml`.
**Example of `include:file`**:
```yaml
include:
...
...
@@ -576,17 +489,6 @@ include:
file:'/templates/.gitlab-ci-template.yml'
```
All [nested includes](#nested-includes) are executed in the scope of the target project.
You can use local (relative to target project), project, remote, or template includes.
NOTE:
When including a YAML file from another private project, the user running the pipeline must be a member of both projects and have the appropriate permissions to run pipelines. A `not found or access denied` error may be shown if the user does not have access to any of the included files.
##### Multiple files from a project
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26793) in GitLab 13.6.
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/271560) in GitLab 13.8.
You can include multiple files from the same project:
```yaml
...
...
@@ -598,33 +500,54 @@ include:
-'/templates/.tests.yml'
```
**Additional details**:
- All [nested includes](includes.md#use-nested-includes) are executed in the scope of the target project.
You can use `local` (relative to the target project), `project`, `remote`, or `template` includes.
- When the pipeline starts, the `.gitlab-ci.yml` file configuration included by all methods is evaluated.
The configuration is a snapshot in time and persists in the database. GitLab does not reflect any changes to
the referenced `.gitlab-ci.yml` file configuration until the next pipeline starts.
- When you include a YAML file from another private project, the user running the pipeline
must be a member of both projects and have the appropriate permissions to run pipelines.
A `not found or access denied` error may be displayed if the user does not have access to any of the included files.
#### `include:remote`
Use `include:remote` with a full URL to include a file from a different location.
The remote file must be publicly accessible by an HTTP/HTTPS `GET` request, because
authentication in the remote URL is not supported. For example:
**Keyword type**: Global keyword.
**Possible inputs**: A public URL accessible by an HTTP/HTTPS `GET` request.
Authentication with the remote URL is not supported.
The YAML file must have the extension `.yml` or `.yaml`.
