Commit ebd747d4 authored by Michael Friedrich's avatar Michael Friedrich Committed by Russell Dickenson

Docs: Improve the why and how for the include keyword for CI/CD

parent 5c1256a3
...@@ -311,10 +311,30 @@ workflow: ...@@ -311,10 +311,30 @@ workflow:
> - Available for Starter, Premium and Ultimate since 10.6. > - Available for Starter, Premium and Ultimate since 10.6.
> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/21603) to GitLab Core in 11.4. > - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/21603) to GitLab Core in 11.4.
Using the `include` keyword, you can allow the inclusion of external YAML files. Using the `include` keyword allows the inclusion of external YAML files. This helps
to break down the CI/CD configuration into multiple files and increases readability for long configuration files.
It is also possible to have template files stored in a central repository and projects include their
configuration files. This helps avoid duplicated configuration, for example, global default variables for all projects.
`include` requires the external YAML file to have the extensions `.yml` or `.yaml`, `include` requires the external YAML file to have the extensions `.yml` or `.yaml`,
otherwise the external file will not be included. otherwise the external file will not be included.
`include` supports the following inclusion methods:
| Method | Description |
|:--------------------------------|:------------------------------------------------------------------|
| [`local`](#includelocal) | Include a file from the local project repository. |
| [`file`](#includefile) | Include a file from a different project repository. |
| [`remote`](#includeremote) | Include a file from a remote URL. Must be publicly accessible. |
| [`template`](#includetemplate) | Include templates which are provided by GitLab. |
See [usage examples](#include-examples).
NOTE: **Note:**
`.gitlab-ci.yml` configuration included by all methods is evaluated at pipeline creation.
The configuration is a snapshot in time and persisted in the database. Any changes to
referenced `.gitlab-ci.yml` configuration will not be reflected in GitLab until the next pipeline is created.
The files defined in `include` are: The files defined in `include` are:
- Deep merged with those in `.gitlab-ci.yml`. - Deep merged with those in `.gitlab-ci.yml`.
...@@ -330,20 +350,6 @@ Using YAML aliases across different YAML files sourced by `include` is not ...@@ -330,20 +350,6 @@ Using YAML aliases across different YAML files sourced by `include` is not
supported. You must only refer to aliases in the same file. Instead supported. You must only refer to aliases in the same file. Instead
of using YAML anchors, you can use the [`extends` keyword](#extends). of using YAML anchors, you can use the [`extends` keyword](#extends).
`include` supports four include methods:
- [`local`](#includelocal)
- [`file`](#includefile)
- [`template`](#includetemplate)
- [`remote`](#includeremote)
See [usage examples](#include-examples).
NOTE: **Note:**
`.gitlab-ci.yml` configuration included by all methods is evaluated at pipeline creation.
The configuration is a snapshot in time and persisted in the database. Any changes to
referenced `.gitlab-ci.yml` configuration will not be reflected in GitLab until the next pipeline is created.
#### `include:local` #### `include:local`
`include:local` includes a file from the same repository as `.gitlab-ci.yml`. `include:local` includes a file from the same repository as `.gitlab-ci.yml`.
...@@ -401,6 +407,21 @@ All [nested includes](#nested-includes) will be executed in the scope of the tar ...@@ -401,6 +407,21 @@ All [nested includes](#nested-includes) will be executed in the scope of the tar
so it is possible to use local (relative to target project), project, remote so it is possible to use local (relative to target project), project, remote
or template includes. or template includes.
#### `include:remote`
`include:remote` can be used to include a file from a different location,
using HTTP/HTTPS, referenced by using the full URL. The remote file must be
publicly accessible through a simple GET request as authentication schemas
in the remote URL are not supported. For example:
```yaml
include:
- remote: 'https://gitlab.com/awesome-project/raw/master/.gitlab-ci-template.yml'
```
All [nested includes](#nested-includes) will be executed without context as public user, so only another remote
or public project, or template, is allowed.
#### `include:template` #### `include:template`
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/53445) in GitLab 11.7. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/53445) in GitLab 11.7.
...@@ -427,21 +448,6 @@ include: ...@@ -427,21 +448,6 @@ include:
All [nested includes](#nested-includes) will be executed only with the permission of the user, All [nested includes](#nested-includes) will be executed only with the permission of the user,
so it is possible to use project, remote or template includes. so it is possible to use project, remote or template includes.
#### `include:remote`
`include:remote` can be used to include a file from a different location,
using HTTP/HTTPS, referenced by using the full URL. The remote file must be
publicly accessible through a simple GET request as authentication schemas
in the remote URL is not supported. For example:
```yaml
include:
- remote: 'https://gitlab.com/awesome-project/raw/master/.gitlab-ci-template.yml'
```
All nested includes will be executed without context as public user, so only another remote,
or public project, or template is allowed.
#### Nested includes #### Nested includes
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/56836) in GitLab 11.9. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/56836) in GitLab 11.9.
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment