CNB

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 project 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, uses indentation to denote data structures, and has some advanced features.

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

This example describes the following workflow:

  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 is treated as code.

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

By including the build process in version control, it maintains the same transparency and change process as the source code, making it easy to trace modification history.

# 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

It is recommended to use Cloud Native Development 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:

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

# If the pipelines for pull_request and push events are identical, this approach reduces 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 examples utilize built-in YAML features, which 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 to facilitate the separation and reuse of configuration files, as well as the separation of pipeline configurations and sensitive information.

For more details, please refer to File References.