Quick Start

• Simple Example
  • Create a Repository
  • Configuration File
  • Build Details
• Configuration Explanation
  • Common Requirements
  • Configuration Writing
  • Syntax Explanation
• Complete Examples

Cloud Native Build is repository-centric, using configuration files to describe what tasks to execute when certain events occur on which branches.

Let's start with a simple example to demonstrate how to create a repository and trigger a pipeline step by step.

Then, we will focus on a common development scenario, which is setting up a Pull Request pipeline to fulfill specific requirements.

Based on that, you can choose a specific scenario repository from the complete examples, fork the repository, or copy the configuration file to customize the pipeline configuration according to your own needs.

Simple Example

Create a Repository

If you have already created a repository, you can skip this step. Otherwise, create a new repository. Once created, you can click on the "Workspace" button to quickly set up a development environment.

Choose WebIDE to enter the development interface for convenience.

Configuration File

Here is a simple pipeline configuration:

# Branch name
main:
  # Event name
  push:
    # Tasks to execute
    - stages:
        - name: echo
          script: echo "hello world"

Add a CI configuration file .cnb.yml, copy the content into the configuration file, commit, and push it to the remote main branch.

This will trigger the pipeline build.

Build Details

Click on Cloud Native Build on the repository page to view the build list.

The latest entry is the pipeline triggered by the push event. Clicking on it will show the build details.

The entry with the loading icon below is the build for Workspace.

Configuration Explanation

Common Requirements

A common CI requirement is to trigger a pipeline for linting and testing when there is a Pull Request on the main branch. If the tests fail, a notification is sent.

Let's analyze this requirement and extract some key elements:

1. Main branch, such as main.
2. Repository event, specifically the pull_request event.
3. Pipeline tasks:
   1. Linting
   2. Testing
4. Action to take when the pipeline fails:
   1. Notify

Now, let's write the CI configuration file step by step based on these elements.

Configuration Writing

The first level property is the branch name:

# Branch name
main:

When the branch has a pull_request event, trigger the build:

# Branch name
main:
  # Event name
  pull_request:

Multiple pipelines can be executed for an event (in parallel), and each pipeline can have multiple tasks (in series or parallel).

Here, we simplify it to have only one pipeline under the event:

# Branch name
main:
  # Event name
  pull_request:
    # Array type indicates multiple pipelines
    - name: pr-check
      stages:

This pipeline consists of two sequential tasks: linting and testing.

# Branch name
main:
  # Event name
  pull_request:
    # Array type indicates multiple pipelines
    - name: pr-check
      # Multiple tasks under the pipeline
      stages:
        # Tasks to execute
        - name: lint
          script: echo "lint job"
        - name: test
          script: echo "test job"

If the tests fail, a notification is sent. In the pipeline, in addition to the stages that represent the expected tasks to execute, there is also a failStages section that indicates the tasks to execute when the stages tasks fail.

# Branch name
main:
  # Event name
  pull_request:
    # Array type indicates multiple pipelines
    - name: pr-check
      # Multiple tasks under the pipeline
      stages:
        - name: lint
          script: echo "lint job"
        - name: test
          script: echo "test job"
      # Tasks to execute when stages fail
      failStages:
        - name: lint
          script: echo "notify to some chat group"

To summarize, the execution process of a pipeline is as follows:

1. An event occurs in the repository.
2. Determine the branch to which the event belongs.
3. Identify the event name.
4. Execute the pipeline.
5. Execute the tasks.
6. Execute the tasks for failure cases.

In reality, there is an additional layer called stages between the pipeline and tasks, but it can often be omitted.

Syntax Explanation

For detailed syntax information about the configuration file, please refer to the Syntax section.

For more usage examples of the configuration file, please refer to the Configuration File section.

Complete Examples

For more complete examples, please refer to the complete examples.