---
url: /en/build/simplify-configuration.md
description: >-
  Explains how to use advanced YAML features (anchors, aliases, merge operators)
  and CNB's include/imports directives to reduce duplication and simplify
  complex .cnb.yml pipeline configuration files.
---
## Advanced YAML Syntax

Since `.cnb.yml` uses YAML format, you can leverage YAML anchors `&`, aliases `*`,
and merge `<<` operators to simplify configuration and reduce duplication.

Here is an example showing basic usage and anchor reuse:

```yaml title=".cnb.yml"
# Define a pipeline anchor and reuse across events
.pipeline: &pipeline
  docker:
    image: node:22
  stages:
    - name: install
      script: npm install
    - name: test
      script: npm test

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

When there's more repetition, stages can be extracted as a separate anchor:

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

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

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.

Additionally, anchors reduce readability:
when multiple branches reference them, readers must repeatedly jump back and forth to understand the full configuration.
When the same anchor is referenced more than 3 times, consider using [include](#include) for cross-file reuse,
or extract it into a standalone template file to keep each file independently readable.

:::

## File References

To reuse pipeline configurations, `Cloud Native Build` provides 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 cross-file value referencing by property path
through the extended `!reference` custom tag, which can be combined with [`include`](#include).

:::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

Add the following configuration in VSCode to avoid syntax errors
when writing YAML files with `!reference` tags:

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`).
:::