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:

1. Declares that when the main branch receives a push event (i.e., new commits are pushed to the main branch)
2. Selects Docker image node:22 as the execution environment
3. Executes tasks npm install and npm 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

Since the configuration file is in the project repository and subject to Git version control, there are naturally multiple versions of the configuration file. Which version of the configuration file is used in a build is information developers must understand. Fortunately, the mechanism of Cloud Native Build is very intuitive, and in most scenarios, developers don't need to pay extra attention to this.

Below lists how Cloud Native Build selects which version of the configuration file to use in various events. Special attention should be paid to the pull_request event, as its selection is relatively more complex:

1. For push, branch.create, vscode events, the configuration file is read from the latest commit node of the current branch.
2. For auto_tag, branch.delete, issue.*, the configuration file is read from the default branch.
3. For tag_push, tag_deploy.* events, the configuration file is read from the current Tag.
4. For pull_request, pull_request.update, pull_request.approved, pull_request.changes_requested events, which have source and target branches, the pre-merged configuration file is used.
5. For pull_request.merged events, the merged configuration file is used.
6. For pull_request.target, pull_request.mergeable events, the pre-merge target branch configuration file is used.
7. For api_trigger custom events, the version can be specified, while cnb:apply is limited to the version corresponding to the current pipeline.
8. For web_trigger custom events, the configuration file is read from the corresponding branch or Tag, refer to specific application scenarios.
9. For scheduled task events, the configuration file is read from the specified branch.

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:

yaml-auto

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

yaml-auto

1. "Settings" > "Languages & Frameworks" > "Schemas and DTDs" > "JSON Schema Mappings"

2. Click the add button, set "Name" (name can be arbitrary)

3. Set "Schema file or URL"

4. "Add mapping for a file"

https://docs.cnb.cool/conf-schema-en.json