---
url: /en/build/simplify-configuration.md
---
## Advanced YAML Syntax

Since the `.cnb.yml` configuration file is in `YAML` format, you can leverage more `YAML` features (such as anchors `&`, aliases `*`, and merge `<<` operators) to simplify the configuration file.

A simple example of using anchors and aliases for simplification is as follows:

```yaml title=".cnb.yml"
# The pipelines for pull_request and push events are identical, this approach reduces duplication
.pipeline: &pipeline
  docker:
    image: node:22
  stages:
    - name: install
      script: npm install
    - name: test
      script: npm test

main:
  pull_request:
    - <<: *pipeline
  push:
    - <<: *pipeline
```

Multi-level nesting is supported:

```yaml title=".cnb.yml"
.jobs: &jobs
  - name: install
    script: npm install
  - name: test
    script: npm test

.pipeline: &pipeline
  docker:
    image: node:22
  stages: *jobs

main:
  pull_request:
    - <<: *pipeline
  push:
    - <<: *pipeline
```

:::tip

The above are built-in `YAML` features that only work when parsing a single YAML file and cannot be used across files.

:::

## File References

To facilitate the reuse of pipeline configurations, `Cloud Native Build` implements the following features:

* [include](./grammar.md#include): Reference pipeline templates across files.
* [imports](./grammar.md#Pipeline-imports): Reference variables across files.
* [optionsFrom](./grammar.md#optionsfrom): Reference built-in task parameters across files.
* [settingsFrom](./grammar.md#settingsfrom): Reference plugin task parameters across files.

For detailed file reference documentation, see [File References](./file-reference.md)

## Variable References

To address the limitation that YAML anchors and aliases cannot be used across files, `Cloud Native Build` implements the following feature:

### reference (Extended Tag)

The YAML standard does not support cross-file references. `Cloud Native Build` implements the ability to reference values by property path through the extended `!reference` custom tag, which can be combined with [`include`](#include) to achieve cross-file configuration reuse.

:::tip Notes

1. `!reference` supports nested references, up to 10 levels deep.
2. When merging configurations, variables with the same name at the first level will be overwritten, not merged.
3. Parsing order: First load and merge all `include` files and the main file `.cnb.yml`, **then** parse the `!reference` tags. The merge process is based on the original text and is not aware of the values after reference resolution.
   :::

#### Example {#reference-example}

```yaml title="a.yml"
.val1:
  echo1: echo hello
.val2:
  friends:
    - one:
        name: tom
        say: !reference [.val1, echo1] # Reference value within this file
```

```yaml title=".cnb.yml"
include:
  - ./a.yml # Include a.yml

.val3:
  size: 100

main:
  push:
    - stages:
        - name: echo hello
          # Cross-file reference to value in a.yml
          script: !reference [.val2, friends, "0", say]
        - name: echo size
          env:
            # Reference value within this file .cnb.yml
            SIZE: !reference [".val3", "size"]
          script: echo my size ${SIZE}
```

**Equivalent configuration after parsing:**

```yaml title=".cnb.yml"
main:
  push:
    - stages:
        - name: echo hello
          script: echo hello # Parsed value
        - name: echo size
          env:
            SIZE: 100 # Parsed value
          script: echo my size ${SIZE}
```

#### Advanced Example: Reusing Entire Pipelines

```yaml title=".cnb.yml"
.common-pipeline:
  - stages:
      - name: echo
        script: echo hello

main:
  push: !reference [.common-pipeline] # Reference entire pipeline
test:
  push: !reference [.common-pipeline] # Reference entire pipeline
```

**Equivalent configuration after parsing:**

```yaml title=".cnb.yml"
main:
  push:
    - stages:
        - name: echo
          script: echo hello
test:
  push:
    - stages:
        - name: echo
          script: echo hello
```

#### VSCode Configuration

To avoid syntax errors when writing YAML files with `!reference` tags in VSCode, you need to configure as follows:

Add to `settings.json`:

```json
{
  "yaml.customTags": ["!reference sequence"]
}
```

:::tip
To avoid error messages caused by the system mistakenly identifying top-level variable names as branch names during schema-based parsing, it is recommended to name top-level variables used for `reference` with a leading dot (`.`) (e.g., `.var`).
:::