---
url: /en/build/configuration.md
description: >-
  Introduces the .cnb.yml configuration file used by Cloud Native Build,
  explaining its role, format requirements, and providing a basic example for
  defining build pipelines triggered by repository events.
---
## Introduction

The configuration file defines the build tasks and step operations to execute
when specific events occur in the code repository (such as pushing a new commit or creating a pull request).

## Configuration File Specifications

1. **File Standards**
   * The file is named `.cnb.yml` and is stored in the root directory of the code repository,
     following the Configuration as Code principle.
   * Configuration changes can be managed through the Pull Request process,
     suitable for open-source collaboration.
   * The build process is version-controlled alongside the source code,
     ensuring transparency and traceability of changes.

2. **Advantages of YAML Format**
   * Supports nested structures and key-value pairs, clearly expressing complex configurations.
   * Easy to extend and modify, adapting to dynamic needs, with comments to enhance collaboration efficiency.

For more details, see the [Syntax Manual](./grammar.md) and [Trigger Rules](./trigger-rule.md).

## Example Configuration

Here is an example of a **Cloud Native Build** configuration:

```yaml title=".cnb.yml"
main:
  push:
    - docker:
        image: node:22
      stages:
        - name: install
          script: npm install
        - name: test
          script: npm test
```

### Example Workflow Description

1. **Trigger Condition**: A build is triggered when a `push` event occurs on the `main` branch (i.e.,
   a new commit is pushed to the main branch).
2. **Execution Environment**: The `node:22` Docker image is used as the task execution environment.
3. **Task Steps**:
   * Execute `npm install` to install dependencies.
   * Execute `npm test` to run tests.

## Basic Syntax

The basic structure of the configuration file is as follows:

```yaml title=".cnb.yml"
main:
  push:
    - name: push-pipeline1
      stages:
        - script: echo 1
    - name: push-pipeline2
      stages:
        - script: echo 2
```

An event can contain multiple pipelines, supporting both **array** (recommended) and **object** syntax,
and these pipelines will run **concurrently**. Where:

* `main` represents the branch name
* `push` and `pull_request` represent [trigger events](./trigger-rule.md#trigger-event)
* 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, refer to: [Syntax Manual](./grammar.md)

## Configuration File Version Selection

The rules for selecting the configuration file version are the same as for
[Code Version Selection](./trigger-rule.md#code-version-selection).

## Syntax Checking and Auto-Completion

### VSCode

It is recommended to use the [Cloud Native Development](../workspaces/intro.md)
environment to write configuration files, as it natively supports syntax checking and auto-completion, as shown below:

![yaml-auto](/images/yaml-auto.gif)

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:

   ```json
   {
     "yaml.schemas": {
       "https://docs.cnbprod.alpha.qq.com/conf-schema-en.json": ".cnb.yml",
       "https://docs.cnbprod.alpha.qq.com/tag-deploy-schema-en.json": ".cnb/tag_deploy.yml",
       "https://docs.cnbprod.alpha.qq.com/web-trigger-schema-en.json": ".cnb/web_trigger.yml",
       "https://docs.cnbprod.alpha.qq.com/settings-schema-en.json": ".cnb/settings.yml",
       "https://docs.cnbprod.alpha.qq.com/code-security-conf-schema-en.json": ".cnb/security/code_scan_config.yml"
     }
   }
   ```

### JetBrains

![jetbrains-yaml](/images/jetbrains.png)

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