Reconcile differences in doc/ci/yaml

776bca5a · Matija Čupić · 5e0ce238 · 776bca5a
Commit 776bca5a authored Sep 08, 2018 by Matija Čupić
Hide whitespace changes
Inline Side-by-side

Showing with 181 additions and 141 deletions

doc/ci/yaml/README.md doc/ci/yaml/README.md +181 -141

No files found.
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -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.