Configuration File
About 1295 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:
- Declares that when the
main
branch receives apush
event (i.e., new commits are pushed to the main branch) - Selects Docker image
node:22
as the execution environment - Executes tasks
npm install
andnpm 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:

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

"Settings" > "Languages & Frameworks" > "Schemas and DTDs" > "JSON Schema Mappings"
Click the add button, set "Name" (name can be arbitrary)
Set "Schema file or URL"
"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"
Pipeline configurations from different files are merged using object merge
mode:
- 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
- The local
.cnb.yml
will overwrite configurations ininclude
. Configurations later in theinclude
array will overwrite earlier ones. - Nested
include
is supported. Local file paths ininclude
are relative to the project root directory. - A maximum of 50 configuration files can be included.
- Files in submodules cannot be referenced.
- 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
- Variables with the same name at the first level will be overwritten, not merged. Local
.cnb.yml
will overwrite variables ininclude
. Variables later in theinclude
array will overwrite earlier ones. reference
supports nested references, up to 10 levels deep.
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
.