Commit c841ae54 authored by Marcia Ramos's avatar Marcia Ramos

Merge branch 'docs/yaml-include' into 'master'

Refactor and simplify the docs on 'include' for CI/CD

See merge request gitlab-org/gitlab-ee!4604
parents af28096f 109197ac
...@@ -361,72 +361,82 @@ Additionally, if you have a job that unconditionally recreates the cache without ...@@ -361,72 +361,82 @@ 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 reference to its previous contents, you can use `policy: push` in that job to
skip the download step. skip the download step.
### include (EEP) ### include
> Introduced in [GitLab Enterprise Edition Premium][ee] 10.5. > Introduced in [GitLab Edition Premium][ee] 10.5.
From 10.5 we can use `include` keyword to allow the inclusion of external YAML files. 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 ```yaml
# Content of https://gitlab.com/awesome-project/raw/master/.before-script-template.yml # Content of https://gitlab.com/awesome-project/raw/master/.before-script-template.yml
before_script: before_script:
- apt-get update -qq && apt-get install -y -qq sqlite3 libsqlite3-dev nodejs - apt-get update -qq && apt-get install -y -qq sqlite3 libsqlite3-dev nodejs
- ruby -v
- which ruby
- gem install bundler --no-ri --no-rdoc - gem install bundler --no-ri --no-rdoc
- bundle install --jobs $(nproc) "${FLAGS[@]}" - bundle install --jobs $(nproc) "${FLAGS[@]}"
``` ```
```yaml ```yaml
# Content of .gitlab-ci.yml # Content of .gitlab-ci.yml
include: 'https://gitlab.com/awesome-project/raw/master/.before-script-template.yml' include: 'https://gitlab.com/awesome-project/raw/master/.before-script-template.yml'
rspec: rspec:
script: script:
- bundle exec rspec - 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`. 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:
`include` supports two types of files: ```yaml
# Single string
- **local** to the same repository, referenced using the paths in the same the repository, i.e: include: '/templates/.after-script-template.yml'
```
```yaml ```yaml
# Within the repository # Array
include: '/templates/.gitlab-ci-template.yml'
include:
- 'https://gitlab.com/awesome-project/raw/master/.before-script-template.yml'
- '/templates/.after-script-template.yml'
``` ```
- **remote** in a different location, accessed using HTTP/HTTPS protocol, referenced using the full URL, i.e: ---
```yaml `include` supports two types of files:
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 - **local** to the same repository, referenced by using full paths in the same
repository, with `/` being the root directory. For example:
```yaml ```yaml
include: '/templates/.gitlab-ci-template.yml' # Within the repository
``` include: '/templates/.gitlab-ci-template.yml'
```
and 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.
```yaml - **remote** in a different location, accessed using HTTP/HTTPS, referenced
include: using the full URL. For example:
- 'https://gitlab.com/awesome-project/raw/master/.gitlab-ci-template.yml'
- '/templates/.gitlab-ci-template.yml'
```
are both valid use cases. ```yaml
include: 'https://gitlab.com/awesome-project/raw/master/.gitlab-ci-template.yml'
```
#### 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 by `include` are evaluated first, the content of
- 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: `.gitlab-ci.yml` will always take precedence over the content of the external
files, no matter of the position of the `include` keyword. This allows you to
override values and functions with local definitions. For example:
```yaml ```yaml
# Content of https://company.com/autodevops-template.yml # Content of https://company.com/autodevops-template.yml
...@@ -434,32 +444,18 @@ are both valid use cases. ...@@ -434,32 +444,18 @@ are both valid use cases.
variables: variables:
POSTGRES_USER: user POSTGRES_USER: user
POSTGRES_PASSWORD: testing_password POSTGRES_PASSWORD: testing_password
POSTGRES_ENABLED: "true"
POSTGRES_DB: $CI_ENVIRONMENT_SLUG POSTGRES_DB: $CI_ENVIRONMENT_SLUG
KUBERNETES_VERSION: 1.8.6
HELM_VERSION: 2.6.1
CODECLIMATE_VERSION: 0.69.0
production: production:
stage: production stage: production
script: script:
- check_kube_domain
- install_dependencies - install_dependencies
- download_chart
- ensure_namespace
- install_tiller
- create_secret
- deploy - deploy
- delete canary
- persist_environment_url
environment: environment:
name: production name: production
url: http://$CI_PROJECT_PATH_SLUG.$AUTO_DEVOPS_DOMAIN url: https://$CI_PROJECT_PATH_SLUG.$AUTO_DEVOPS_DOMAIN
only: only:
refs: - master
- master
kubernetes: active
``` ```
```yaml ```yaml
...@@ -477,35 +473,24 @@ variables: ...@@ -477,35 +473,24 @@ variables:
stages: stages:
- build - build
- test - test
- review
- dast
- staging
- canary
- production - production
- performance
- cleanup
production: production:
stage: production stage: production
script: script:
- check_kube_domain
- install_dependencies - install_dependencies
- download_chart
- ensure_namespace
- install_tiller
- create_secret
- deploy - deploy
environment: environment:
name: production name: production
url: http://auto_devops_domain.com url: https://domain.com
only: only:
refs: - master
- 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`. In this case, the variables `POSTGRES_USER`, `POSTGRES_PASSWORD` and
`POSTGRES_DB` along with the `production` job defined in
`autodevops-template.yml` will be overridden by the ones defined in
`.gitlab-ci.yml`.
## Jobs ## Jobs
......
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