summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorKamil Trzciński <ayufan@ayufan.eu>2018-09-05 18:13:02 +0000
committerKamil Trzciński <ayufan@ayufan.eu>2018-09-05 18:13:02 +0000
commit498f3d83ca2abde4776d581f43d270ee45e4168a (patch)
treeff8457d83e5ea9d1dea651a039795eb999c86ee1 /doc
parentd9f05f87ee01d99109505a2b90527d4712f57ee3 (diff)
parente8648241e4af7d5f9ae1345fef9636bfdbb85557 (diff)
downloadgitlab-ce-498f3d83ca2abde4776d581f43d270ee45e4168a.tar.gz
Merge branch 'feature/gb/allow-to-extend-keys-in-gitlab-ci-yml' into 'master'
Add support for advanced CI/CD config extension with `extends:` Closes gitlab-ee#6136 See merge request gitlab-org/gitlab-ce!21243
Diffstat (limited to 'doc')
-rw-r--r--doc/ci/yaml/README.md74
1 files changed, 74 insertions, 0 deletions
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index e93060fec85..c1ebe39e076 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -56,6 +56,7 @@ A job is defined by a list of parameters that define the job behavior.
| Keyword | Required | Description |
|---------------|----------|-------------|
| script | yes | Defines a shell script which is executed by Runner |
+| extends | no | Defines a configuration entry that this job is going to inherit from |
| image | no | Use docker image, covered in [Using Docker Images](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml) |
| services | no | Use docker services, covered in [Using Docker Images](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml) |
| stage | no | Defines a job stage (default: `test`) |
@@ -75,6 +76,79 @@ A job is defined by a list of parameters that define the job behavior.
| coverage | no | Define code coverage settings for a given job |
| retry | no | Define how many times a job can be auto-retried in case of a failure |
+### `extends`
+
+> Introduced in GitLab 11.3
+
+`extends` defines an entry name that a job, that uses `extends` is going to
+inherit from.
+
+`extends` in an alternative to using [YAML anchors](#anchors) that is a little
+more flexible and readable.
+
+```yaml
+.tests:
+ only:
+ refs:
+ - branches
+
+rspec:
+ extends: .tests
+ script: rake rspec
+ stage: test
+ only:
+ variables:
+ - $RSPEC
+```
+
+In the example above the `rspec` job is going to inherit from `.tests`
+template. GitLab will perform a reverse deep merge, what means that it will
+merge `rspec` contents into `.tests` recursively, and it is going to result in
+following configuration of the `rspec` job:
+
+```yaml
+rspec:
+ script: rake rspec
+ stage: test
+ only:
+ refs:
+ - branches
+ variables:
+ - $RSPEC
+```
+
+`.tests` in this example is a [hidden key](#hidden-keys-jobs), but it is
+possible to inherit from regular jobs as well.
+
+`extends` supports multi-level inheritance, however it is not recommended to
+use more than three levels of inheritance. Maximum nesting level supported is
+10 levels.
+
+
+```yaml
+.tests:
+ only:
+ - pushes
+
+.rspec:
+ extends: .tests
+ script: rake rspec
+
+rspec 1:
+ variables:
+ RSPEC_SUITE: '1'
+ extends: .rspec
+
+rspec 2:
+ variables:
+ RSPEC_SUITE: '2'
+ extends: .rspec
+
+spinach:
+ extends: .tests
+ script: rake spinach
+```
+
### `pages`
`pages` is a special job that is used to upload static content to GitLab that