Reconcile differences in doc/ci/yaml
This commit is contained in:
parent
5e0ce238d2
commit
776bca5a8f
|
@ -966,147 +966,6 @@ Additionally, if you have a job that unconditionally recreates the cache without
|
|||
reference to its previous contents, you can use `policy: push` in that job to
|
||||
skip the download step.
|
||||
|
||||
### include
|
||||
|
||||
From 10.5 we can use `include` keyword to allow the inclusion of external YAML files.
|
||||
|
||||
```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
|
||||
- ruby -v
|
||||
- which ruby
|
||||
- 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
|
||||
|
||||
rubocop:
|
||||
script:
|
||||
- bundle exec rubocop
|
||||
```
|
||||
|
||||
In the above example `.before-script-template.yml` content will be automatically fetched and evaluated along with the content of `.gitlab-ci.yml`.
|
||||
|
||||
`include` supports two types of files:
|
||||
|
||||
- **local** to the same repository, referenced using the paths in the same the repository, i.e:
|
||||
|
||||
```yaml
|
||||
# Within the repository
|
||||
include: '/templates/.gitlab-ci-template.yml'
|
||||
```
|
||||
|
||||
- **remote** in a different location, accessed using HTTP/HTTPS protocol, referenced using the full URL, i.e:
|
||||
|
||||
```yaml
|
||||
include: 'https://gitlab.com/awesome-project/raw/master/.gitlab-ci-template.yml'
|
||||
```
|
||||
|
||||
Also, `include` supports a single string or an array composed by different values, so
|
||||
|
||||
```yaml
|
||||
include: '/templates/.gitlab-ci-template.yml'
|
||||
```
|
||||
|
||||
and
|
||||
|
||||
```yaml
|
||||
include:
|
||||
- 'https://gitlab.com/awesome-project/raw/master/.gitlab-ci-templates.yml'
|
||||
- '/templates/.gitlab-ci-templates.yml'
|
||||
```
|
||||
|
||||
are both valid use cases.
|
||||
|
||||
#### Restrictions
|
||||
|
||||
- We 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.
|
||||
- Since external files defined on `include` are evaluated first, the content on `.gitlab-ci.yml` **will always take precedence over the content of the external files, no matters of the position of the `include` keyword, allowing to override values and functions with local definitions**, for example:
|
||||
|
||||
```yaml
|
||||
# Content of http://company.com/autodevops-template.yml
|
||||
|
||||
variables:
|
||||
POSTGRES_USER: user
|
||||
POSTGRES_PASSWORD: testing_password
|
||||
POSTGRES_ENABLED: "true"
|
||||
POSTGRES_DB: $CI_ENVIRONMENT_SLUG
|
||||
KUBERNETES_VERSION: 1.8.6
|
||||
HELM_VERSION: 2.6.1
|
||||
CODECLIMATE_VERSION: 0.69.0
|
||||
|
||||
production:
|
||||
stage: production
|
||||
script:
|
||||
- check_kube_domain
|
||||
- install_dependencies
|
||||
- download_chart
|
||||
- ensure_namespace
|
||||
- install_tiller
|
||||
- create_secret
|
||||
- deploy
|
||||
- delete canary
|
||||
- persist_environment_url
|
||||
environment:
|
||||
name: production
|
||||
url: http://$CI_PROJECT_PATH_SLUG.$AUTO_DEVOPS_DOMAIN
|
||||
only:
|
||||
refs:
|
||||
- master
|
||||
kubernetes: active
|
||||
```
|
||||
|
||||
```yaml
|
||||
# Content of .gitlab-ci.yml
|
||||
|
||||
include: 'https://company.com/autodevops-template.yml'
|
||||
|
||||
image: alpine:latest
|
||||
|
||||
variables:
|
||||
POSTGRES_USER: root
|
||||
POSTGRES_PASSWORD: secure_password
|
||||
POSTGRES_DB: company_database
|
||||
|
||||
stages:
|
||||
- build
|
||||
- test
|
||||
- review
|
||||
- dast
|
||||
- staging
|
||||
- canary
|
||||
- production
|
||||
- performance
|
||||
- cleanup
|
||||
|
||||
production:
|
||||
stage: production
|
||||
script:
|
||||
- check_kube_domain
|
||||
- install_dependencies
|
||||
- download_chart
|
||||
- ensure_namespace
|
||||
- install_tiller
|
||||
- create_secret
|
||||
- deploy
|
||||
environment:
|
||||
name: production
|
||||
url: http://auto_devops_domain.com
|
||||
only:
|
||||
refs:
|
||||
- master
|
||||
```
|
||||
|
||||
In this case, the variables `POSTGRES_USER`, `POSTGRES_PASSWORD` and `POSTGRES_DB` along with the `production` job defined on `autodevops-template.yml` will be overridden by the ones defined on `.gitlab-ci.yml`.
|
||||
|
||||
## `artifacts`
|
||||
|
||||
> **Notes:**
|
||||
|
@ -1493,6 +1352,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
|
||||
|
||||
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