Build Environment
About 650 wordsAbout 2 min
Build Environment explains how to specify the runtime environment for a job - the software and tools required for execution, such as specific versions of JDK, Node.js, or Python.
When to use: when a pipeline needs a specific language or tool version, extra dependencies, or a team-maintained shared image - this is where you decide between a ready-made image and one built from a Dockerfile.
Overview
Cloud Native Build uses Docker containers as the build runtime. Compared with traditional virtual machines, containers start faster, cost fewer resources, and offer better environment consistency - the standard approach across the CI/CD industry.
Note
A basic understanding of Docker helps you get more out of Cloud Native Build.
Configuration Methods
You can configure the build environment in the following two ways:
- Use Existing Image (image): use an image already pushed to a container registry. Suitable for official images or a team's shared public tool images; private images need registry authentication configured.
- Build Image Dynamically (build): point to a Dockerfile in the project and build an image when the build starts. Suitable for complex projects needing a highly customized environment or specific dependencies and tools. No special permissions required.
Use Existing Image (image)
Syntax Reference: pipeline.docker.image
Build Image Dynamically (build)
Mechanism:
- The system calculates a hash for the image version
- If the image exists in the local cache or a remote registry, it is reused to speed up the build
- Otherwise
docker buildruns, and the image is automatically pushed to the pipeline project's artifact registry for reuse by later builds
Syntax Reference: pipeline.docker.build
Environment Scope
The build environment declared at the pipeline level serves as the default runtime environment for all script tasks. Each script task can also specify its own image environment.
Warning
Task-level configuration only supports image, not dockerfile.
Syntax Reference: Script Task | Script Tasks vs Plugin Tasks
Examples
Example 1: Using Existing Image (image)
main:
push:
- docker:
image: node:22
stages:
- node -vExample 2: Building Image with Dockerfile (build)
Step 1: Create a Dockerfile
FROM node:20Step 2: Configure the pipeline to use this Dockerfile
main:
push:
- docker:
build: image/Dockerfile
stages:
- node -vExample 3: Job-Level Override + Default Image
main:
push:
- docker:
image: node:22
stages:
- node -v
- name: Using a specific image version
image: node:20
script:
- node -vExample 4: Using Default Images
When a pipeline does not explicitly specify an image or build configuration, the system automatically uses a default image to ensure a basic environment is available.
| Build Type | Default Image Variable |
|---|---|
| Cloud Native Build | cnbcool/default-build-env |
| Cloud Native Development | cnbcool/default-dev-env |
main:
push:
- stages:
- stage1
- stage2
# Without explicit environment, equivalent to using cnbcool/default-build-envCloud native development works similarly — the default dev image is used when no image is declared:
$:
vscode:
- services:
- vscode
stages:
- stage1
# Without explicit environment, equivalent to using cnbcool/default-dev-envVolume Sharing
Data volumes declared by your custom image through the VOLUME instruction (for example VOLUME /cache) are automatically shared with containers started by later plugin tasks.
Application Example
Step 1: Prepare shared data in the Dockerfile
FROM alpine
RUN mkdir /cache && echo 'Initial data' > /cache/data.txt
VOLUME /cacheStep 2: Access the shared data in a subsequent task
- name: Read data from the shared volume
image: alpine
script:
- cat /cache/data.txtVolume sharing lets tasks running different images share data, which suits scenarios such as caching dependencies and sharing build artifacts.