Cloud-native builds distribute tasks to build nodes for execution, using Docker images as the build environment.

Configuration Method

Use pipeline.runner.tags to specify the build node, and pipeline.runner.cpus to configure the CPU core count.

Available Nodes

Tags	Architecture	CPU Cores	GPU Memory	Build Max Time	Dev Max Time
cnb:arch:amd64	amd64	1 ~ 64 (default 8)	-	20 hours	18 hours
cnb:arch:arm64:v8	arm64/v8	1 ~ 16 (default 8)	-	20 hours	18 hours
cnb:arch:amd64:gpu	amd64	Fixed 16	48GB (shared)	4 hours	4 hours
cnb:arch:amd64:gpu:L40	amd64	Fixed 16	48GB (shared)	4 hours	4 hours

Example

.cnb.yml

main:
  push:
    - runner:
        tags: cnb:arch:amd64
        cpus: 8
      stages:
        - name: uname
          script: uname -a

    - runner:
        tags: cnb:arch:arm64:v8
        cpus: 8
      stages:
        - name: uname
          script: uname -a

$:
  vscode:
    - runner:
        tags: cnb:arch:amd64:gpu
      services:
        - vscode

Root-Organization Custom Runners

In addition to the platform-provided build nodes, root-organization administrators can self-attach Mac, Windows and Linux build machines as resources dedicated to the organization, supporting use cases such as iOS builds, Windows desktop packaging, or Linux ARM server builds.

Connecting a Build Machine

1. Open Root Organization / Organization Settings / Build Nodes, click + Add Runner, fill in the name and tags, and save.
2. The new node starts in the Offline state. Click the Connection Guide button at the end of the row; the dialog shows a one-click setup script for each platform (Mac, Windows, Linux) with the node's unique identifier already injected — no manual replacement is required.
3. Run the script for the matching platform on the target Mac/Windows/Linux build machine. The node turns Online once it successfully connects.

Using It in .cnb.yml

Once the node is online and enabled, schedule pipelines onto it via runner.namespace plus runner.tags:

• Set runner.namespace to group to use the self-hosted nodes attached to the root organization that owns the current repository.
• runner.tags must be a subset of the tags declared on the node (an AND match — every tag listed must appear on the node). For example, when the node is tagged [mac, arm64, xcode15], using tags: [mac, arm64] will match.

Mac Node Example

.cnb.yml

main:
  push:
    - runner:
        # Use a self-hosted runner under the root organization the current repo belongs to
        namespace: group
        # Each listed tag must be present on the node's labels (node labels form a superset)
        # e.g. when the node is tagged [mac, arm64, xcode15], the following will match
        tags:
          - mac
          - arm64
      stages:
        - name: build-on-mac
          script: |
            # Show system info (verify we are running on a mac node)
            sw_vers
            uname -m
            # Common build tools (print versions if installed; missing ones do not fail the pipeline)
            command -v xcodebuild >/dev/null && xcodebuild -version || echo "xcodebuild not installed"
            command -v brew >/dev/null && brew --version || echo "brew not installed"

Windows Node Example

.cnb.yml

main:
  push:
    - runner:
        # Use a self-hosted runner under the root organization the current repo belongs to
        namespace: group
        # Each listed tag must be present on the node's labels (node labels form a superset)
        # e.g. when the node is tagged [windows, win11, msvc2022], the following will match
        tags:
          - windows
      stages:
        - name: build-on-windows
          script: |
            # Show system info (verify we are running on a windows node)
            # Note: on self-hosted Windows runners, stage scripts default to PowerShell.
            # `ver` is a cmd built-in, so invoke it via `cmd /c`.
            cmd /c ver
            systeminfo | findstr /B /C:"OS Name" /C:"OS Version"
            # git is a required dependency for self-hosted windows runners
            git -v

Linux Node Example

.cnb.yml

main:
  push:
    - runner:
        # Use a self-hosted runner under the root organization the current repo belongs to
        namespace: group
        # Each listed tag must be present on the node's labels (node labels form a superset)
        # e.g. when the node is tagged [linux, arm64, ubuntu22.04], the following will match
        tags:
          - linux
          - arm64
      stages:
        - name: build-on-linux
          script: |
            # Show system info (verify we are running on a linux node)
            uname -a
            cat /etc/os-release
            # git is a required dependency for self-hosted linux runners
            git --version

Limitations

• Mac, Windows and Linux build machines are supported. Linux runners must be arm64/aarch64; x86_64/amd64 is not supported yet.
• The custom build machine must be able to reach the CNB site (for node registration, heartbeat reporting, pulling pipeline tasks, and uploading logs/artifacts). If the machine sits on an internal network, make sure the required egress policy is in place.
• Custom Runners do not enable Docker by default; build scripts run directly on the host. As a result:
  • runner.cpus has no effect (resource limits are enforced via Docker cgroups; without Docker, the full host capacity is available) and is not counted as core-hour usage.
  • Docker-image-based build environments (pipeline.docker.image, etc.) are not effective.
  • OverlayFS is unavailable, so second-read clones automatically fall back to plain git clone.
• Custom Runners are for Cloud Native Build only and cannot be used for Workspaces (remote development) tasks.
• When a pipeline targets this Runner and the picked node is temporarily unavailable (offline, temporarily disabled, or resource usage has reached the limits configured by the node administrator, e.g. CPU / memory, concurrent pipeline count), the system automatically tries to re-allocate to another available node. The pipeline fails if no other available node can be assigned.

Tips

If Build Nodes is not visible under Root Organization / Organization Settings, this capability has not been enabled for your organization yet — please contact the platform administrator.

Previous pageScript & Plugin Tasks

Next pageEnvironment Variables