---
url: /en/build/configuration.md
---
## Introduction

The cloud-native build configuration file is used to define whether the **Cloud-Native Build Service** should execute build tasks when specific events occur in the code repository (such as pushing a new commit, creating a pull request, etc.), as well as the specific operations for each step in the build task.

## Configuration File Specifications

1. **File Standards**
   * The file is named `.cnb.yml` and is stored in the root directory of the code repository, adhering to the "Configuration as Code" principle.
   * Configuration changes can be managed through the Pull Request (PR) process, making it particularly suitable for open-source collaboration scenarios.
   * 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 configuration logic.
   * Easy to extend and modify, adapting to dynamic needs, with comments to enhance collaboration efficiency.
   * Simple and strict syntax, reducing configuration errors, with lightweight files for efficient loading and parsing.

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

## Example Configuration

Here is a simple and functional example of a **Cloud Native Build** configuration:

```yaml title=".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
```

### 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 Structure

The basic structure of the configuration file is as follows:

**Array Form (Recommended):**

```yaml title=".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:**

```yaml title=".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](./trigger-rule.md#trigger-event).
* 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](./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.cnb.share.ralphlauren.cn/conf-schema-en.json": ".cnb.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.
4. Set a Name.
5. In `Schema file or URL`, enter: `https://docs.cnb.share.ralphlauren.cn/conf-schema-en.json`
6. Add the mapping file pattern `.cnb.yml`.