Skip to content

G
gitlab-ce
Commit 776bca5a authored by Matija Čupić's avatar Matija Čupić
Browse files
Options

Reconcile differences in doc/ci/yaml

parent 5e0ce238
Hide whitespace changes
Inline Side-by-side
Showing with 181 additions and 141 deletions
doc/ci/yaml/README.md
View file @ 776bca5a
......@@ -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.
......
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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7