Configuration File
About 576 wordsAbout 2 min
Configuration File explains the format and authoring rules of the Cloud Native Build configuration file .cnb.yml.
When to use: when onboarding a repository to Cloud Native Build. For example, running build tasks automatically on a new commit push or pull request creation, or organizing multiple pipelines by branch and event.
Introduction
The configuration file defines the build tasks and steps to execute when specific events occur in the code repository, such as pushing a new commit or creating a pull request.
The file is named .cnb.yml and lives in the repository root, following the configuration-as-code principle:
- Changes are managed through the Pull Request process, which suits open-source collaboration.
- The build process is version-controlled alongside the source code, keeping changes transparent and traceable.
YAML is used because it supports nested structures and key-value pairs, so complex configurations stay readable, and because it is easy to extend, modify, and annotate.
For the full field reference, see the Syntax Manual; for trigger conditions, see Trigger Rules.
Example Configuration
Here is an example of a Cloud Native Build configuration:
main:
push:
- docker:
image: node:22
stages:
- name: install
script: npm install
- name: test
script: npm testExample Workflow Description
- Trigger Condition: A build is triggered when a
pushevent occurs on themainbranch (i.e., a new commit is pushed to the main branch). - Execution Environment: The
node:22Docker image is used as the task execution environment. - Task Steps:
- Execute
npm installto install dependencies. - Execute
npm testto run tests.
- Execute
Basic Syntax
The basic structure of the configuration file is as follows:
main:
push:
- name: push-pipeline1
stages:
- script: echo 1
- name: push-pipeline2
stages:
- script: echo 2An event can contain multiple pipelines, supporting both array (recommended) and object syntax, and these pipelines will run concurrently. Where:
mainrepresents the branch namepushandpull_requestrepresent trigger events- A single
pipelinecontains a set ofstagesthat are executed sequentially within the same build environment (physical machine, virtual machine, or Docker container).
For more detailed syntax instructions, 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
VS Code
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:

If developing locally in VS Code, configure it as follows:
Install the
redhat.vscode-yamlplugin.Add the following to the
settings.jsonconfiguration file:{ "yaml.schemas": { "https://docs.cnb.cool/conf-schema-en.json": ".cnb.yml", "https://docs.cnb.cool/tag-deploy-schema-en.json": ".cnb/tag_deploy.yml", "https://docs.cnb.cool/web-trigger-schema-en.json": ".cnb/web_trigger.yml", "https://docs.cnb.cool/settings-schema-en.json": ".cnb/settings.yml", "https://docs.cnb.cool/code-security-conf-schema-en.json": ".cnb/security/code_scan_config.yml" } }
JetBrains

- Open
Settings/Preferences. - Navigate to
Languages & Frameworks->Schemas and DTDs->JSON Schema Mappings. - Click
+to add a new mapping. Add five mappings in total:https://docs.cnb.cool/conf-schema-en.json→.cnb.ymlhttps://docs.cnb.cool/tag-deploy-schema-en.json→.cnb/tag_deploy.ymlhttps://docs.cnb.cool/web-trigger-schema-en.json→.cnb/web_trigger.ymlhttps://docs.cnb.cool/settings-schema-en.json→.cnb/settings.ymlhttps://docs.cnb.cool/code-security-conf-schema-en.json→.cnb/security/code_scan_config.yml