Simplifying Configuration Files

About 567 wordsAbout 2 min

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:

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

.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

Tips

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

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 to achieve cross-file configuration reuse.

Notes

!reference supports nested references, up to 10 levels deep.
When merging configurations, variables with the same name at the first level will be overwritten, not merged.
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

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

Add to settings.json:

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