Configuration File

About 683 wordsAbout 2 min

Introduction

The configuration file defines whether build tasks should execute when specific events occur in the code repository (such as pushing a new commit or creating a pull request), along with the operations for each step.

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 process, suitable for open-source collaboration.
- 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 configurations.
- Easy to extend and modify, adapting to dynamic needs, with comments to enhance collaboration efficiency.

For more details, see 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",
    "https://docs.cnb.cool/tag-deploy-schema-en.json": ".cnb/tag_deploy.yml",
    "https://docs.cnb.cool/web-trigger-schema-en.json": ".cnb/web_trigger.yml"
  }
}

Jetbrains

Open Settings / Preferences.
Navigate to Languages & Frameworks -> Schemas and DTDs -> JSON Schema Mappings.
Click + to add a new mapping. Add three mappings in total:
- https://docs.cnb.cool/conf-schema-en.json → .cnb.yml
- https://docs.cnb.cool/tag-deploy-schema-en.json → .cnb/tag_deploy.yml
- https://docs.cnb.cool/web-trigger-schema-en.json → .cnb/web_trigger.yml