When using Cloud Native Build, build tasks are dispatched to various build nodes for execution, with the specified Docker image serving as the runtime environment.

Configuration Method

In the pipeline configuration, specify the pipeline.runner.tags property to select different build clusters. Specify the pipeline.runner.cpus property to configure the maximum number of CPU cores to be used. Cloud Native Build will calculate the core-hours used by the pipeline by multiplying the actual allocated core count by the pipeline's duration.

The official available build node tags and the declarable cpus are as follows:

1. cnb:arch:amd64 represents a CPU cluster with the amd64 architecture.

   • The cpus can be configured in the range of 1 to 64, with a default value of 8.

2. cnb:arch:arm64:v8 represents a CPU cluster with the arm64/v8 architecture.

   • The cpus can be configured in the range of 1 to 8, with a default value of 8.

Use an amd64 node:

.cnb.yml

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

Use an arm64/v8 node:

.cnb.yml

main:
  push:
    - runner:
        tags: cnb:arch:arm64:v8
      stages:
        - name: uname
          script: uname -a

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

Node Scheduling

Unlike system build nodes, which by default rotate among only a few machines, every enabled root-organization custom runner matching the same set of tags takes part in the rotation.

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