Port 'include' in CI yaml docs from EE
This commit is contained in:
parent
1d76e5311f
commit
9677e53efd
|
@ -1354,6 +1354,187 @@ test:
|
|||
retry: 2
|
||||
```
|
||||
|
||||
## `include`
|
||||
|
||||
> Introduced in [GitLab Edition Premium][ee] 10.5.
|
||||
> Available for Starter, Premium and Ultimate [versions][gitlab-versions] since 10.6.
|
||||
> Behaviour expanded in GitLab 10.8 to allow more flexible overriding.
|
||||
> Available for Libre since [11.4](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21603)
|
||||
|
||||
Using the `include` keyword, you can allow the inclusion of external YAML files.
|
||||
|
||||
In the following example, the content of `.before-script-template.yml` will be
|
||||
automatically fetched and evaluated along with the content of `.gitlab-ci.yml`:
|
||||
|
||||
```yaml
|
||||
# Content of https://gitlab.com/awesome-project/raw/master/.before-script-template.yml
|
||||
|
||||
before_script:
|
||||
- apt-get update -qq && apt-get install -y -qq sqlite3 libsqlite3-dev nodejs
|
||||
- gem install bundler --no-ri --no-rdoc
|
||||
- bundle install --jobs $(nproc) "${FLAGS[@]}"
|
||||
```
|
||||
|
||||
```yaml
|
||||
# Content of .gitlab-ci.yml
|
||||
|
||||
include: 'https://gitlab.com/awesome-project/raw/master/.before-script-template.yml'
|
||||
|
||||
rspec:
|
||||
script:
|
||||
- bundle exec rspec
|
||||
```
|
||||
|
||||
You can define it either as a single string, or, in case you want to include
|
||||
more than one files, an array of different values . The following examples
|
||||
are both valid cases:
|
||||
|
||||
```yaml
|
||||
# Single string
|
||||
|
||||
include: '/templates/.after-script-template.yml'
|
||||
```
|
||||
|
||||
```yaml
|
||||
# Array
|
||||
|
||||
include:
|
||||
- 'https://gitlab.com/awesome-project/raw/master/.before-script-template.yml'
|
||||
- '/templates/.after-script-template.yml'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
`include` supports two types of files:
|
||||
|
||||
- **local** to the same repository, referenced by using full paths in the same
|
||||
repository, with `/` being the root directory. For example:
|
||||
|
||||
```yaml
|
||||
# Within the repository
|
||||
include: '/templates/.gitlab-ci-template.yml'
|
||||
```
|
||||
|
||||
NOTE: **Note:**
|
||||
You can only use files that are currently tracked by Git on the same branch
|
||||
your configuration file is. In other words, when using a **local file**, make
|
||||
sure that both `.gitlab-ci.yml` and the local file are on the same branch.
|
||||
|
||||
NOTE: **Note:**
|
||||
We don't support the inclusion of local files through Git submodules paths.
|
||||
|
||||
- **remote** in a different location, accessed using HTTP/HTTPS, referenced
|
||||
using the full URL. For example:
|
||||
|
||||
```yaml
|
||||
include: 'https://gitlab.com/awesome-project/raw/master/.gitlab-ci-template.yml'
|
||||
```
|
||||
|
||||
NOTE: **Note:**
|
||||
The remote file must be publicly accessible through a simple GET request, as we don't support authentication schemas in the remote URL.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Since GitLab 10.8 we are now recursively merging the files defined in `include`
|
||||
with those in `.gitlab-ci.yml`. Files defined by `include` are always
|
||||
evaluated first and recursively merged with the content of `.gitlab-ci.yml`, no
|
||||
matter the position of the `include` keyword. You can take advantage of
|
||||
recursive merging to customize and override details in included CI
|
||||
configurations with local definitions.
|
||||
|
||||
The following example shows specific YAML-defined variables and details of the
|
||||
`production` job from an include file being customized in `.gitlab-ci.yml`.
|
||||
|
||||
```yaml
|
||||
# Content of https://company.com/autodevops-template.yml
|
||||
|
||||
variables:
|
||||
POSTGRES_USER: user
|
||||
POSTGRES_PASSWORD: testing_password
|
||||
POSTGRES_DB: $CI_ENVIRONMENT_SLUG
|
||||
|
||||
production:
|
||||
stage: production
|
||||
script:
|
||||
- install_dependencies
|
||||
- deploy
|
||||
environment:
|
||||
name: production
|
||||
url: https://$CI_PROJECT_PATH_SLUG.$AUTO_DEVOPS_DOMAIN
|
||||
only:
|
||||
- master
|
||||
```
|
||||
|
||||
```yaml
|
||||
# Content of .gitlab-ci.yml
|
||||
|
||||
include: 'https://company.com/autodevops-template.yml'
|
||||
|
||||
image: alpine:latest
|
||||
|
||||
variables:
|
||||
POSTGRES_USER: root
|
||||
POSTGRES_PASSWORD: secure_password
|
||||
|
||||
stages:
|
||||
- build
|
||||
- test
|
||||
- production
|
||||
|
||||
production:
|
||||
environment:
|
||||
url: https://domain.com
|
||||
```
|
||||
|
||||
In this case, the variables `POSTGRES_USER` and `POSTGRES_PASSWORD` along
|
||||
with the environment url of the `production` job defined in
|
||||
`autodevops-template.yml` have been overridden by new values defined in
|
||||
`.gitlab-ci.yml`.
|
||||
|
||||
NOTE: **Note:**
|
||||
Recursive includes are not supported meaning your external files
|
||||
should not use the `include` keyword, as it will be ignored.
|
||||
|
||||
Recursive merging lets you extend and override dictionary mappings, but
|
||||
you cannot add or modify items to an included array. For example, to add
|
||||
an additional item to the production job script, you must repeat the
|
||||
existing script items.
|
||||
|
||||
```yaml
|
||||
# Content of https://company.com/autodevops-template.yml
|
||||
|
||||
production:
|
||||
stage: production
|
||||
script:
|
||||
- install_dependencies
|
||||
- deploy
|
||||
```
|
||||
|
||||
```yaml
|
||||
# Content of .gitlab-ci.yml
|
||||
|
||||
include: 'https://company.com/autodevops-template.yml'
|
||||
|
||||
stages:
|
||||
- production
|
||||
|
||||
production:
|
||||
script:
|
||||
- install_depedencies
|
||||
- deploy
|
||||
- notify_owner
|
||||
```
|
||||
|
||||
In this case, if `install_dependencies` and `deploy` were not repeated in
|
||||
`.gitlab-ci.yml`, they would not be part of the script for the `production`
|
||||
job in the combined CI configuration.
|
||||
|
||||
NOTE: **Note:**
|
||||
We currently do not support using YAML aliases across different YAML files
|
||||
sourced by `include`. You must only refer to aliases in the same file. Instead
|
||||
of using YAML anchors you can use [`extends` keyword](#extends).
|
||||
|
||||
## `variables`
|
||||
|
||||
> Introduced in GitLab Runner v0.5.0.
|
||||
|
|
Loading…
Reference in New Issue