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:

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

.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

Tips

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 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: Reference pipeline templates across files.
• imports: Reference variables across files.
• optionsFrom: Reference built-in task parameters across files.
• settingsFrom: Reference plugin task parameters across files.

For detailed file reference documentation, see File References

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.

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

a.yml

.val1:
  echo1: echo hello
.val2:
  friends:
    - one:
        name: tom
        say: !reference [.val1, echo1] # Reference value within this file

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

.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

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

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

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

Tips

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

Previous pageContribute Plugins

Next pageFile References