Overview

The build environment defines the runtime environment for pipeline jobs, containing all the software and tools required for execution, such as specific versions of JDK, Node.js, Python, etc.

Cloud Native Build uses Docker containers as the runtime for the build environment. Compared to traditional virtual machines, Docker containers offer significant advantages including faster startup times, lower resource overhead, and superior environment consistency, making them the industry standard for modern CI/CD.

Tips

Having a basic understanding of Docker will help you better comprehend and utilize Cloud Native Build.

Configuration Methods

You can configure the build environment for your pipeline in the following two ways:

Configuration Method	Description	Use Case	Permission Requirements
Use Existing Image (image)	Directly use a pre-built image that has been pushed to a container registry	Using official images or team-internal pre-configured public tool images	Private images require registry authentication configuration
Build Image Dynamically (build)	Specify a Dockerfile in the project to dynamically build an image	Complex projects requiring highly customized environments, specific dependencies, or tools	No special requirements

Use Existing Image (image)

Directly use a pre-built image that has been pushed to a container registry (e.g., Docker Hub, private registry). This is the fastest method.

Syntax Reference: pipeline.docker.image

Build Image Dynamically (build)

Specify a Dockerfile file within your project. At the start of the build, the system will dynamically build an image based on this file for use in subsequent steps.

Mechanism:

1. The system first calculates a hash value for the image version
2. If an image with this hash already exists in the local cache or remote registry, it is used directly, significantly speeding up the build process
3. Otherwise, it executes docker build to create the image, and automatically pushes it to the artifact repository associated with the pipeline project for reuse in subsequent builds

Syntax Reference: pipeline.docker.build

Environment Scope

The build environment declared at the pipeline level serves as the default runtime environment for all its script tasks.

Furthermore, each script task can override this and specify its own image environment.

Warning

Task-level configuration only supports image, not dockerfile.

Syntax Reference: Script Task

Examples

Example 1: Using Existing Image (image)

.cnb.yml

main:
  push:
    - docker:
        # Declare the official Node.js 22 image as the default build environment for the pipeline
        image: node:22
      stages:
        # The following script tasks will run in the node:22 environment
        - node -v # Output: v22.x.x

Example 2: Building Image with Dockerfile (build)

Step 1: Create a Dockerfile

image/Dockerfile

# Build a custom environment based on Node.js 20
FROM node:20
# You can install more project-specific global dependencies here
# RUN npm install -g yarn

Step 2: Configure the pipeline to use this Dockerfile

.cnb.yml

main:
  push:
    - docker:
        # Declare to use the project's Dockerfile to build the environment image
        build: image/Dockerfile
      stages:
        # The following script tasks will run in the custom-built environment
        - node -v # Output: v20.x.x

Example 3: Overriding Environment at Task Level

.cnb.yml

main:
  push:
    - docker:
        # Pipeline default environment
        image: node:22
      stages:
        - node -v # Output: v22.x.x (Uses default environment)
        - name: Task using a specific image version
          image: node:20 # This task overrides and uses Node.js 20
          script:
            - node -v # Output: v20.x.x

Example 4: Using Default Images

When a pipeline does not explicitly specify any image or build configuration, the system automatically uses a default image to ensure a basic environment is available.

Default Image Configuration:

Build Type	Default Image Variable
Cloud Native Build	cnbcool/default-build-env
Cloud Native Development	cnbcool/default-dev-env

Cloud Native Build Example:

.cnb.yml

main:
  push:
    - stages:
        - stage1
        - stage2
# The above configuration is equivalent to:
# docker:
#   image: cnbcool/default-build-env

Cloud Native Development Example:

.cnb.yml

main:
  vscode:
    - services:
        - vscode
      stages:
        - stage1
        - stage2
# For Cloud Native Development without a specified environment, equivalent to:
# docker:
#   image: cnbcool/default-dev-env

Volume Sharing

If your custom image declares data volumes using the VOLUME instruction (e.g., VOLUME /cache), these volumes are automatically shared with containers started by subsequent plugin tasks.

Application Example

Step 1: Prepare shared data in the Dockerfile

FROM alpine
RUN mkdir /cache && echo 'Initial data' > /cache/data.txt
VOLUME /cache # Declare /cache as a data volume

Step 2: Access the shared data in a subsequent task

- name: Read data from the shared volume
  image: alpine # A task using a different image
  script:
    - cat /cache/data.txt # Successfully outputs: Initial data

Tips

Volume sharing allows different image tasks to share data, making it ideal for scenarios like caching dependencies and sharing build artifacts.

Previous pageGrammar Manual

Next pageBuild Nodes