Commit 34b5d0c0 authored by Marcel Amirault's avatar Marcel Amirault

Merge branch 'add-documentation-for-ci-reference-tag' into 'master'

Add documentation for custom YAML tags

See merge request gitlab-org/gitlab!53712
parents da1c56cb 1d830cc8
......@@ -4597,6 +4597,94 @@ Use this feature to ignore jobs, or use the
[special YAML features](#special-yaml-features) and transform the hidden jobs
into templates.
### `!reference` tags
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/266173) in GitLab 13.9.
> - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default.
> - It's disabled on GitLab.com.
> - It's not recommended for production use.
> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-reference-tags). **(FREE SELF)**
WARNING:
This feature might not be available to you. Check the **version history** note above for details.
Use the `!reference` custom YAML tag to select keyword configuration from other job
sections and reuse it in the current section. Unlike [YAML anchors](#anchors), you can
use `!reference` tags to reuse configuration from [included](#include) configuration
files as well.
In this example, a `script` and an `after_script` from two different locations are
reused in the `test` job:
- `setup.yml`:
```yaml
.setup:
script:
- echo creating environment
```
- `.gitlab-ci.yml`:
```yaml
include:
- local: setup.yml
.teardown:
after_script:
- echo deleting environment
test:
script:
- !reference [.setup, script]
- echo running my own command
after_script:
- !reference [.teardown, after_script]
```
In this example, `test-vars-1` reuses the all the variables in `.vars`, while `test-vars-2`
selects a specific variable and reuses it as a new `MY_VAR` variable.
```yaml
.vars:
variables:
URL: "http://my-url.internal"
IMPORTANT_VAR: "the details"
test-vars-1:
variables: !reference [.vars, variables]
script:
- printenv
test-vars-2:
variables:
MY_VAR: !reference [.vars, variables, IMPORTANT_VAR]
script:
- printenv
```
You can't reuse a section that already includes a `!reference` tag. Only one level
of nesting is supported.
#### Enable or disable `!reference` tags **(FREE SELF)**
The `!reference` tag is under development and not ready for production use. It is
deployed behind a feature flag that is **disabled by default**.
[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md)
can enable it.
To enable it:
```ruby
Feature.enable(:ci_custom_yaml_tags)
```
To disable it:
```ruby
Feature.disable(:ci_custom_yaml_tags)
```
## Skip Pipeline
To push a commit without triggering a pipeline, add `[ci skip]` or `[skip ci]`, using any
......
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