CNB Docs

English

简体中文

English

简体中文

Appearance

Configuration File

About 1332 wordsAbout 4 min

Introduction

The Cloud Native Build configuration file (.cnb.yml) describes whether Cloud Native Build should start a build task when certain events occur in the repository (such as new commits being pushed, new PR requests, etc.), and if so, what each step of the build task should do.

The configuration file format for Cloud Native Build is YAML, which is the same as mainstream CI services in the industry.

Here's a simple, working Cloud Native Build configuration file:

main: # Trigger branch
  push: # Trigger event
    - docker:
        image: node:22 # Pipeline execution environment, can specify any docker image
      stages:
        - name: install
          script: npm install
        - name: test
          script: npm test

This example describes the following workflow:

  1. Declares that when the main branch receives a push event (i.e., new commits are pushed to the main branch)
  2. Selects Docker image node:22 as the execution environment
  3. Executes tasks npm install and npm test sequentially

File Location

The configuration file for Cloud Native Build is named .cnb.yml by convention and stored in the repository root directory - configuration as code.

This means configuration files can be modified through PRs, which is very important in open-source collaboration scenarios.

Build processes are version-controlled, maintaining the same transparency and change process as source code, making modification history easy to trace.

Basic Syntax Structure

The basic syntax structure of the configuration file is as follows:

# Pipeline structure: array format
main:
  push:
    # main branch - push event contains two pipelines: push-pipeline1 and push-pipeline2
    - name: push-pipeline1 # Pipeline name, can be omitted
      stages:
        - name: job1
          script: echo 1
    - name: push-pipeline2 # Pipeline name, can be omitted
      stages:
        - name: job2
          script: echo 2

  pull_request:
    # main branch - pull_request event contains two pipelines: pr-pipeline1 and pr-pipeline2
    - name: pr-pipeline1 # Pipeline name, can be omitted
      stages:
        - name: job1
          script: echo 1
    - name: pr-pipeline2 # Pipeline name, can be omitted
      stages:
        - name: job2
          script: echo 2

Equivalent to the following format:

# Pipeline structure: object format
main:
  push:
    # main branch - push event contains two pipelines: push-pipeline1 and push-pipeline2
    push-pipeline1: # Pipeline name, must be unique
      stages:
        - name: job1
          script: echo 1
    push-pipeline2: # Pipeline name, must be unique
      stages:
        - name: job2
          script: echo 2

  pull_request:
    # main branch - pull_request event contains two pipelines: pr-pipeline1 and pr-pipeline2
    pr-pipeline1: # Pipeline name, must be unique
      stages:
        - name: job1
          script: echo 1
    pr-pipeline2: # Pipeline name, must be unique
      stages:
        - name: job2
          script: echo 3

Where main represents the branch name, and push and pull_request represent trigger events.

An event contains multiple pipelines, supporting both array and object formats, executed concurrently.

A pipeline contains a set of sequentially executed tasks, running in the same build environment (physical machine, virtual machine, or Docker container).

For detailed syntax, refer to: Pipeline Syntax

Configuration File Version Selection

Same as Code Version Selection.

Syntax Checking and Auto-completion

VSCode

It is recommended to use Workspaces to write configuration files, as it natively supports syntax checking and auto-completion, with the following effect:

yaml-auto
yaml-auto

Local development configuration method, taking VSCode as an example:

First install the redhat.vscode-yaml plugin, then add the following configuration to settings.json:

"yaml.schemas": {
  "https://docs.cnb.cool/conf-schema-en.json": ".cnb.yml"
},

Jetbrains

yaml-auto
yaml-auto

  1. "Settings" > "Languages & Frameworks" > "Schemas and DTDs" > "JSON Schema Mappings"

  2. Click the add button, set "Name" (name can be arbitrary)

  3. Set "Schema file or URL"

  4. "Add mapping for a file"

https://docs.cnb.cool/conf-schema-en.json

Configuration Reuse

Anchor

In YAML, anchors and aliases allow reusing configurations within the same file, avoiding duplication and keeping the file concise.

Example:

# .cnb.yml
# Common pipeline configuration
.pipeline-config: &pipeline-config
  stages:
    - echo "do something"
main:
  push:
    # Reference pipeline-config
    - *pipeline-config
dev:
  push:
    # Reference pipeline-config
    - *pipeline-config

Include

Using the include parameter, you can import files from the current repository or other repositories into the current file. This allows for splitting configuration files, making them easier to reuse and maintain.

Usage Example

template.yml

# template.yml
main:
  push:
    pipeline_2:
      env:
        ENV_KEY1: xxx
        ENV_KEY3: inner
      services:
        - docker
      stages:
        - name: echo
          script: echo 222

.cnb.yml

# .cnb.yml
include:
  - https://cnb.cool/<your-repo-slug>/-/blob/main/xxx/template.yml

main:
  push:
    pipeline_1:
      stages:
        - name: echo
          script: echo 111
    pipeline_2:
      env:
        ENV_KEY2: xxx
        ENV_KEY3: outer
      stages:
        - name: echo
          script: echo 333

Merged Configuration

main:
  push:
    pipeline_1: # Key does not exist, added during merge
      stages:
        - name: echo
          script: echo 111
    pipeline_2:
      env:
        ENV_KEY1: xxx
        ENV_KEY2: xxx # Key does not exist, added during merge
        ENV_KEY3: outer # Same key, overwritten during merge
      services:
        - docker
      stages: # Arrays are appended during merge
        - name: echo
          script: echo 222
        - name: echo
          script: echo 333

Syntax Explanation

include:
  # 1. Directly pass the configuration file path
  - "https://cnb.cool/<your-repo-slug>/-/blob/main/xxx/template.yml"
  - "template.yml"
  # 2. Pass an object.
  # path: Configuration file path
  # ignoreError: Whether to throw an error if the file is not read. true: no error; false: throw error. Default is false
  - path: "template1.yml"
    ignoreError: true
  # 3. Pass an object
  # config: Pass YAML configuration
  - config:
      main:
        push:
          - stages:
              - name: echo
                script: echo "hello world"

Merge Rules

Merge rules for pipeline configurations across different files:

  • Array and Array merge: Sub-elements are appended.
  • Map and Map merge: Same keys are overwritten.
  • Array and Map merge: Only the array is retained.
  • Map and Array merge: Only the array is retained.

For permission control on referenced configuration files, refer to Configuration File Reference Authentication.

Tips

The merged pipeline configuration will be displayed on the build details page, which conflicts with the concept of secret repository content protection. Therefore, include cannot reference files from secret repositories.

Tips

  1. The local .cnb.yml will overwrite configurations in include. Configurations later in the include array will overwrite earlier ones.
  2. Nested include is supported. Local file paths in include are relative to the project root directory.
  3. A maximum of 50 configuration files can be included.
  4. Files in submodules cannot be referenced.
  5. Cross-file YAML anchor functionality is not supported.

Reference

YAML does not support cross-file references. Cloud Native Build extends YAML with a custom tag reference to implement variable value references by property paths, enabling cross-file configuration reuse in combination with include.

Tips

  1. The reference supports nested references, up to a maximum of 10 levels.
  2. Variables with the same name at the first level will be overridden and not merged.
  3. In "Cloud-Native Builds," the system first loads and parses files declared in the include statement and .cnb.yml, merges the configurations, and then processes the reference. During merging, the system cannot determine the resolved value of reference, and overrides will occur based on the priority indicated in the include statement.

Example

a.yml

.val1:
  echo1: echo hello
.val2:
  friends:
    - one:
      name: tom
      say: !reference [.val1, echo1]

.cnb.yml

include:
  - ./a.yml
.val3:
  size: 100
main:
  push:
    - stages:
        - name: echo hello
          script: !reference [.val2, friends, "0", say]
        - name: echo size
          env:
            SIZE: !reference [".val3", "size"]
          script: echo my size ${SIZE}

After parsing, it is equivalent to:

main:
  push:
    - stages:
        - name: echo hello
          script: echo hello
        - name: echo size
          env:
            SIZE: 100
          script: echo my size ${SIZE}

Advanced Example

You can reference an entire pipeline configuration:

.common-pipeline:
  - stages:
      - name: echo
        script: echo hello

main:
  push: !reference [.common-pipeline]
test:
  push: !reference [.common-pipeline]

After parsing, it is equivalent to:

main:
  push:
    - stages:
        - name: echo
          script: echo hello
test:
  push:
    - stages:
        - name: echo
          script: echo hello

VSCode Configuration

After installing the VSCode YAML plugin, to avoid errors when writing YAML files with the custom tag reference in VSCode, configure as follows:

setting.json

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

Tips

To prevent the YAML plugin from treating first-level variable names as branch names based on Schema and showing errors, you can prefix the first-level variable names with ., such as .var.

© 2025 cnb.cool