CNB Docs

English

简体中文

English

简体中文

Appearance

Configuration File

About 1453 wordsAbout 5 min

Introduction

The Cloud Native Build configuration file (.cnb.yml) defines whether the Cloud Native Build service should trigger a build task when specific events occur in the repository (e.g., a new commit is pushed, a PR is created, etc.), and specifies the detailed operations for each step within the build task.

This configuration file uses the YAML format, consistent with mainstream CI services in the industry.

Here is a simple, working example of a Cloud Native Build configuration:

.cnb.yml
main: # Target branch
  push: # Trigger event
    - docker:
        image: node:22 # Pipeline execution environment, any Docker image can be used
      stages:
        - name: install
          script: npm install
        - name: test
          script: npm test

This example describes the following workflow:

  1. A build is triggered when the main branch receives a push event (i.e., a new commit is pushed to the main branch).
  2. The node:22 Docker image is selected as the task execution environment.
  3. The npm install and npm test tasks are executed sequentially.

Location

The designated configuration file name for Cloud Native Build is .cnb.yml, which should be placed in the root directory of the code repository, adhering to the "Configuration as Code" principle.

This means:

  • Changes to the configuration file can be managed through the Pull Request (PR) process.
  • This is particularly important in open-source collaboration scenarios.
  • The build process is version-controlled alongside the source code, maintaining the same transparency and change history, making it easy to trace.

Basic Syntax Structure

The basic structure of the configuration file is as follows:

Array Form (Recommended):

.cnb.yml
# Pipeline structure: Array form
main:
  push:
    # The push event for the main branch contains two pipelines
    - name: push-pipeline1 # Pipeline name, optional
      stages:
        - name: job1
          script: echo 1
    - name: push-pipeline2 # Pipeline name, optional
      stages:
        - name: job2
          script: echo 2

  pull_request:
    # The pull_request event for the main branch contains two pipelines
    - name: pr-pipeline1 # Pipeline name, optional
      stages:
        - name: job1
          script: echo 1
    - name: pr-pipeline2 # Pipeline name, optional
      stages:
        - name: job2
          script: echo 2

Object Form:

.cnb.yml
# Pipeline structure: Object form
main:
  push:
    # The push event for the main branch contains two pipelines
    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:
    # The pull_request event for the main branch contains two pipelines
    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 2

Where:

  • main represents the branch name.
  • push and pull_request represent trigger events.
  • An event can contain multiple pipelines (supporting both array and object syntax), which are executed concurrently.
  • A single pipeline contains a set of stages that are executed sequentially within the same build environment (physical machine, virtual machine, or Docker container).

For more detailed syntax instructions, please refer to: Syntax Manual

Configuration File Version Selection

The rules for selecting the configuration file version are the same as for Code Version Selection.

Syntax Checking and Auto-Completion

VSCode

It is recommended to use the Cloud Native Development environment to write configuration files, as it natively supports syntax checking and auto-completion, as shown below:

yaml-auto
yaml-auto

If developing locally in VSCode, configure it as follows:

  1. Install the redhat.vscode-yaml plugin.

  2. Add the following to the settings.json configuration file:

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

Jetbrains

jetbrains-yaml
jetbrains-yaml
  1. Open Settings / Preferences.
  2. Navigate to Languages & Frameworks -> Schemas and DTDs -> JSON Schema Mappings.
  3. Click + to add a new mapping.
  4. Set a Name.
  5. In Schema file or URL, enter: https://docs.cnb.cool/conf-schema-en.json
  6. Add the mapping file pattern .cnb.yml.

Configuration Reuse

YAML Anchor

YAML Anchors and Aliases allow reusing configuration snippets within the same file, avoiding duplication and keeping it concise.

Example:

.cnb.yml
# Common jobs configuration
.jobs: &jobs
  - echo "do something"
  - echo "do something other"

main:
  push:
    - stages:
        - echo "in main push"
        # Reference
        - *jobs
  pull_request:
    - stages:
        - echo "in main pull_request"
        # Reference
        - *jobs
dev:
  push:
    - stages:
        - echo "in dev push"
        # Reference
        - *jobs

Include

Using the include keyword, you can import YAML files from the current repository or other repositories into the current configuration file. This helps split large configurations, improving maintainability and reusability.

Usage Example

template.yml (File to be included)

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

.cnb.yml (Main configuration file)

.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 # New environment variable
        ENV_KEY3: outer # Override ENV_KEY3 from template.yml
      stages:
        - name: echo
          script: echo 333 # New step

Merged Equivalent Configuration:

main:
  push:
    pipeline_1: # Key doesn't exist, added during merge
      stages:
        - name: echo
          script: echo 111
    pipeline_2: # Key exists, merge content
      env: # Object merge: Overwrite same keys, add new keys
        ENV_KEY1: xxx # From template.yml
        ENV_KEY2: xxx # From .cnb.yml (new)
        ENV_KEY3: outer # From .cnb.yml (override)
      services: # Array merge: Append elements
        - docker # From template.yml
      stages: # Array merge: Append elements
        - name: echo # From template.yml
          script: echo 222
        - name: echo # From .cnb.yml
          script: echo 333

Syntax Description

include supports three import methods:

.cnb.yml
include:
  # 1. Directly pass the configuration file path (string)
  - "https://cnb.cool/<your-repo-slug>/-/blob/main/xxx/template.yml"
  - "template.yml" # Relative path (relative to the repository root)

  # 2. Pass an object for more control
  # path: Configuration file path
  # ignoreError: Whether to report an error if the file is not found. true-Ignore error; false-Report error (default)
  - path: "template1.yml"
    ignoreError: true

  # 3. Directly pass an inline YAML configuration object
  - config:
      main:
        push:
          - stages:
              - name: echo
                script: echo "hello world"

Merge Rules

Configurations from different files are merged according to the following rules:

  • Array + Array: Combine all elements (append).
  • Object + Object: Merge keys, values of the same key are overwritten.
  • Array + Object or Object + Array: The final result is only the Array (the object is ignored).
  • Merge order: Local .cnb.yml configuration overwrites configurations included via include; configurations later in the include array overwrite those earlier.

Permission Note: For security reasons, consistent with the principle of sensitive information protection, include cannot reference files stored in the Secret Storage, because the merged complete configuration will be displayed on the build details page.

Notes

  1. Nested includes are supported, but a maximum of 50 configuration files is allowed.
  2. Local file paths for include are relative to the project root directory.
  3. Referencing files in git submodules is not supported.
  4. Using YAML anchors (&, *) across files is not supported.

Reference (Extended Tag)

The YAML standard does not support cross-file references. Cloud Native Build implements value referencing by property path through the extended !reference custom tag, which can be combined with include to achieve cross-file configuration reuse.

Notes

  1. !reference supports nested references, up to 10 levels deep.
  2. During configuration merge, top-level variables with the same name will be overwritten, not merged.
  3. Parsing order: First, load and merge all files from include 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 resolved by the references.

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 in this file .cnb.yml
            SIZE: !reference [".val3", "size"]
          script: echo my size ${SIZE}

Parsed Equivalent Configuration:

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

Advanced Example: Reusing an Entire Pipeline

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

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

Parsed Equivalent Configuration:

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 the !reference tag in VSCode, configure as follows:

Add the following to settings.json:

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

Tips

To prevent the system parser from mistaking top-level variable names for branch names based on the schema and generating error prompts, it is recommended to name top-level variables used for reference with a dot (.) prefix (e.g., .var).

© 2025 cnb.cool