Configuration File

About 717 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, 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.
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 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.