Configuration File

About 711 wordsAbout 2 min

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

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 (PR) process, suitable for open-source collaboration scenarios.
- The build process is version-controlled alongside the source code, ensuring transparency and traceability of changes.
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.

For more details, please refer to the Syntax Manual and Trigger Rules.

Example Configuration

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

.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

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).
Execution Environment: The node:22 Docker image is used as the task execution environment.
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):

.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:

.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.
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

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

VSCode

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 VSCode, configure it as follows:

Install the redhat.vscode-yaml plugin.

Add the following to the settings.json configuration file:

{
  "yaml.schemas": {
    "https://docs.cnb.cool/conf-schema-en.json": ".cnb.yml"
  }
}

Jetbrains

Open Settings / Preferences.
Navigate to Languages & Frameworks -> Schemas and DTDs -> JSON Schema Mappings.
Click + to add a new mapping.
Set a Name.
In Schema file or URL, enter: https://docs.cnb.cool/conf-schema-en.json
Add the mapping file pattern .cnb.yml.