Quick Start

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

Cloud Native Build focus on repositories, with configuration files specifying tasks to run when particular events happen on specific branches.

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

Following this, we focus on the typical development use case of triggering a pipeline for code quality checks during Pull Request operations, detailing how to create the corresponding configuration file.

Based on this, you can fork a repository or copy its configuration file from the showcase, then customize it to create a pipeline configuration that meets your 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.

Select WebIDE for online code editing, offering a quick and efficient development experience.

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 configuration file .cnb.yml to the repository root, copy the above content into the file, commit, and push 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 in the list corresponds to the pipeline triggered by the recent push event. Click to view 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 Top-level property is the branch name:

# Branch name
main:

When a pull_request event happens on the branch, 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 a Stage fails, notifications are typically sent to the responsible person. In addition to stages, which define the expected tasks, there is also failStages to specify tasks to execute when stages 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 is triggered in the repository.
2. Determine the branch associated with the event.
3. Identify the name of the event.
4. Execute the pipeline associated with the event.
5. Execute the tasks defined in the pipeline.
6. Execute the tasks for the failure scenario.

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 showcase.