Cloud Native Build

Configuration File

# What is a CI Configuration File?

A CI configuration file describes what actions should be taken by the Cloud Native Build when certain events occur in a repository (such as new commits being pushed or new PR requests). It determines whether the Cloud Native Build should initiate a build task and, if so, what each step of the build task should do.

The configuration file for Cloud Native Build is in the YAML format, which is the same format used by popular CI services in the industry.

YAML is a format that can be converted to JSON. It is more human-readable than JSON, use indentation to represent data structures at different levels.

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

main:
  push:
    - docker:
        image: node:22
      stages:
        - name: install
          script: npm install
        - name: test
          script: npm test

The usage effect is as shown below.

  1. It declares that when the main branch receives a push event (i.e., when new commits are pushed to the main branch),
  2. It will use the Docker image node:22 as the execution environment,
  3. It will execute the tasks npm install and npm test sequentially.

# Configuration File Location

The convention for the Cloud Native Build configuration file is to name it .cnb.yml and place it in the root directory of the repository. The configuration file can also be treated as code.

This means that the configuration file can be modified through a PR, which is crucial in open-source collaboration scenarios.

Include the build configuration files in version control, maintaining the same transparency and change process as the source code, making modification history easy to trace.

# Basic Syntax Structure of the Configuration File

The basic syntax structure of the configuration file is as follows:

# Pipeline structure: array format
main:
  push:
    # The 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:
    # The 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:
    # The 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:
    # The 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

In the above example, main represents the branch name, and push and pull_request represent the trigger events.

An event can contain multiple pipelines, which can be executed concurrently and support both array and object formats.

A pipeline consists of a set of sequentially executed tasks within the same build environment (physical machine, virtual machine, or Docker container).

For detailed syntax explanations, please refer to: Syntax Explanation

# Syntax Checking and Auto-completion

# VSCode

It is recommended to use Workspace for writing the configuration file, as it provides native support for syntax checking and auto-completion. The effect is as follows:

yaml-auto

To configure local development, using VSCode as an example:

First, install the redhat.vscode-yaml extension, then add the following configuration to settings.json:

# Jetbrains

yaml-auto

  1. 「Settings」「Languages & Frameworks」「Schemas and DTDs」「JSON Schema Mappings」

  2. Click '+'，Write 「Name」

  3. 「Schema file or URL」

  4. 「Add mapping for a file」

# Simplified Configuration File Syntax

The configuration file is in the YAML format, and you can leverage more YAML features (such as anchors &, aliases *, and object merging << symbol) to simplify the configuration file.

Here is a simple example that demonstrates the use of anchors and aliases to reduce duplication:

# In the following example, the pipelines for the pull_request and push events are identical.
# This approach can reduce duplication.
.pipeline: &pipeline
  docker:
    image: node:22
  stages:
    - name: install
      script: npm install
    - name: test
      script: npm test

main:
  pull_request:
    - <<: *pipeline
  push:
    - <<: *pipeline

Supports multiple levels of nesting:

.jobs: &jobs
  - name: install
    script: npm install
  - name: test
    script: npm test

.pipeline: &pipeline
  docker:
    image: node:22
  stages: *jobs

main:
  pull_request:
    - <<: *pipeline
  push:
    - <<: *pipeline

TIP

The above is a built-in feature of YAML and cannot be used across files.

To facilitate the reuse of pipeline configurations, Cloud Native Build provides more advanced features:

include: Allows referencing pipeline templates across files.

reference: Allows referencing variables by property path across files.

# File References

Cloud Native Build supports referencing configurations from other files, enabling the separation and reuse of configuration files, as well as the separation of pipeline configurations from sensitive information.

For more details, please refer to File References.