Harness Cloud VM Images

Reference for VM images on Harness Cloud Machines

Harness provides preconfigured virtual machine (VM) images to run your pipeline stages in Harness Cloud. These images come with common build tools and dependencies preinstalled, so you can focus on building and testing your code without worrying about setup.

Every stage runs on a fresh VM, ensuring clean, isolated executions.

For a full list of the tools included in each image, visit the Harness Cloud VM image repository.

Cloud VM Images

Available VM Images Image Tags

Below is a list of the images used by Harness Cloud. You can either:

1. Use a moving image tag (for example, ubuntu-latest) to automatically receive updates, or

2. Pin to a specific image version to maximize build reproducibility.

VM Images:

Virtual machine image	Image label	Notes	Rollout Status
Linux AMD Ubuntu 22.04	ubuntu-latest or ubuntu-22.04	Default Linux image for Linux AMD	GA
Linux AMD Ubuntu 24.04	ubuntu-24.04	Default Linux image for Linux AMD	Beta
Linux ARM Ubuntu 22.04	ubuntu-latest or ubuntu-22.04	Default Linux image for Linux ARM	GA
Linux ARM Ubuntu 24.04	ubuntu-24.04	Default Linux image for Linux ARM	GA
macOS 14 (Sonoma)	mac-latest, mac-sonoma, or macos_sonoma_xcode_16.3	macOS 14 (Sonoma) with Xcode 15.2 (default), 16.3, 16.1, 15.1	GA
macOS 15 (Sequoia)	macos_sequoia, macos_sequoia_xcode_16.4, or macos-sequoia-xcode-26.2	macOS 15 (Sequoia) with Xcode 16.4 (default), 16.3, 26.0, 26.1, 26.2, 26.3, 26.4	BETA
macOS 26 (Tahoe)	macos-tahoe	macOS 26 (Tahoe) with Xcode 26.4.1 (default), 26.3, 26.5, 27.0 (Beta 5)	BETA
Windows Server 2022	windows-latest or windows-2022	Latest Windows 2022 Server Image	GA
Windows Server 2025	windows-2025	Latest Windows 2025 Server Image	BETA

Beta vs GA Images:

• Beta images are preview releases for testing before general availability. They are not covered by production SLA and require a feature flag to access (CI_ENABLE_HOSTED_BETA_IMAGES for Linux, CI_ENABLE_MAC_HOSTED_BETA_IMAGES for macOS).

• GA (General Availability) images are production-ready and covered by your Harness SLA. Harness supports the latest 2 major versions of each operating system.

Feature Flag Behavior:

• When CI_ENABLE_HOSTED_BETA_IMAGES is enabled, ubuntu-latest points to the Beta version instead of the GA version.

• When CI_ENABLE_MAC_HOSTED_BETA_IMAGES is enabled, mac-latest points to the Beta macOS version.

Note: Minor OS upgrades for GA images also go through the beta image process before being promoted to GA.

Choosing an image version

Harness VM images use a versioning system to help you balance between getting the latest updates and maintaining build stability.

To select an the image tag to use, simply provide it in the imageName property of the cloud infrastructure runtime section.

    runtime:
      type: Cloud
      spec:
        size: xxlarge
        imageName: ubuntu-latest # specify image tag

Best Practice: Pin Image Versions in Production

Since using the latest tag may contain breaking changes or updated tool versions that could affect your build. Always test thoroughly before updating production pipelines.

To ensure stable production deployments while still benefiting from the latest updates, we recommend the following approach:

1. Test in Dev: Use latest in non-prod pipelines and confirm everything works with the new image.

2. Update Prod: Switch production pipelines to the new image, and pin image name to a specific version.

To simplify the rollout and management of image tag updates across environments, we recommend defining the image name as a variable at the Account, Org, Project, or Pipeline level in Harness. This will ensure you can pin your pipeline to a new version globally.

The latest image may contain breaking changes or updated tool versions that could affect your build. Always test thoroughly before updating production pipelines.

Image Updates and Maintenance

Harness regularly updates VM images to include:

• Security patches and OS updates.

• Latest versions of popular development tools.

• Runtime updates (Node.js, Python, Java, etc.).

• New tools and utilities based on community feedback.

Image Lifecycle

This section outlines Harness's policy for managing VM image releases, versioning, and deprecation in Harness Cloud.

Deprecation Policy

N-1 Support Model

Harness supports the latest 2 major versions of each operating system at any given time. When a new GA version is released, deprecation of the oldest supported GA version begins.

Harness provides Ubuntu LTS (Long Term Support) images for both AMD64 and ARM64 architectures.

Example: When a new Ubuntu major version becomes LTS → Harness publishes a new image → Ubuntu 24.04 (N-1) remains available → Ubuntu 22.04 (the N-2 maintained LTS image) deprecation process begins.

Deprecation Process

When an image is deprecated, we follow this timeline to minimize disruption:

• Announcement — Public notice via RSS feed with the target deprecation date. Minimum notice: 60 days for Linux, 30 days for macOS.

• Migration period — Time to update your pipelines to use supported images.

• Removal — Image is no longer available after the deprecation date.

macOS has a shorter deprecation notice period (30 days) due to Apple's support policies, which require faster transitions when a macOS version reaches end-of-life.

Xcode Versions Availability

Harness provides three Xcode versions pre-installed on each macOS image:

1. Base version - The Xcode version that ships with the macOS release (e.g., Xcode 16.0 comes with macOS 15). This only updates when we upgrade to a new major macOS version.

2. Latest stable version - The newest production Xcode release (e.g., Xcode 16.4). This updates regularly as Apple releases new stable versions.

3. Latest beta version — The current Xcode beta or preview release (e.g., Xcode 17.0 beta). If Apple promotes the beta to GA and no new beta is available, this slot contains the newly released stable version, resulting in two stable versions on the image (e.g., Xcode 16.4 and 17.0).

We aim to make new Xcode beta versions available within approximately three business days of Apple’s release.

SWITCHING XCODE VERSIONS

The latest stable version is the default. To list all available versions:

ls /Applications | grep Xcode

To switch versions, run this before your build commands:

sudo xcode-select -s /Applications/Xcode_<VERSION>.app

Replace <VERSION> with your desired version (e.g., 16.0, 16.4).

Pre-installed Software Version Management

Using preinstalled software

Harness-hosted VM images include a comprehensive set of preinstalled software packages, development tools, and runtime environments. This eliminates the need to install common dependencies during your pipeline execution, significantly reducing build times.

You can customize the Harness Cloud build environment. In your pipelines, you can select specific versions of pre-installed tools, ensure that a step uses a specific version every time, or install additional tools and versions that aren't preinstalled on the Harness Cloud images. You can run these steps on the host machine or as separate Docker containers.

Specify versions

If a Harness Cloud image has multiple versions of a tool pre-installed, you can specify the version that you want to use in a step's Command. For example, with the Harness Cloud macOS build infrastructure, you could use the following command in a Run step to select an Xcode version:

sudo xcode-select -switch /Applications/Xcode_15.1.0.app

Harness Cloud machine images can change. If your pipeline relies on a specific version of a software, tool, or environment, make sure you lock versions to prevent your pipeline from failing when the image changes.

Lock versions or install additional tools

If your build requires a specific version of a tool or you need to use a version/tool that isn't pre-installed on the Harness Cloud image, you must add a step (such as a Run step or Plugin step) to install the version/tool directly on the build machine or run a Docker image that has the required version/tool.

When installing additional tools, run apt-get update before installing new software that might not be in the packages list.

Example: Use an Action step to setup Java

In the following YAML example, an Action step runs the actions/setup-java GitHub Action to install a Java version, and then the Run step confirms the Java version.

            steps:
              - step:
                  identifier: install_java
                  name: install java version 17
                  type: Action
                  spec:
                    uses: actions/setup-java@v3
                    with:
                      distribution: 'temurin'
                      java-version: '16'
              - step:
                  identifier: java_ver_check
                  name: java version check
                  type: Run
                  spec:
                    shell: Bash
                    command: |
                      JAVA_VER=$(java -version 2>&1 | head -1 | cut -d'"' -f2 | sed '/^1\./s///' | cut -d'.' -f1)
                      if [[ $JAVA_VER == 16 ]]; then
                        echo successfully installed $JAVA_VER
                      else
                        exit 1
                      fi

You can also use the Bitrise step to run Bitrise Workflow Steps in your CI pipelines.

Example: Use a Docker image

The following YAML example demonstrates how a Run step can use a Docker image to leverage tools that are available on the image without having to install them on the build machine.

    - stage:
        name: Print welcome message
        identifier: welcome_message
        type: CI
        spec:
          cloneCodebase: true
          platform: ## Platform properties describe the target machine required by this stage.
            os: Linux
            arch: Amd64
          runtime:
            type: Cloud ## This build runs on Harness-provided infrastructure.
            spec: {}
          execution:
            steps:
              - step:
                  type: Run
                  name: Welcome
                  identifier: Welcome
                  spec:
                    connectorRef: my_docker_hub  ## Specify a Docker connector to pull an image from Docker.
                    image: alpine ## If no image is specified, the step runs on the host machine.
                    shell: Sh
                    command: Echo "Welcome to Harness CI"

MISSING TOOLS AND ENVIRONMENT CONFIGURATION

Some tools referenced in Harness Cloud VM images might not be preinstalled, or they might not be on PATH by default. If a tool isn’t available, install it in a step or run your step inside a container image that already includes it. If a tool is present but not auto-configured, set the required environment variables (for example, update PATH, set JAVA_HOME, etc.).

Install on-demand (example: Node via NVM)

- step:
    type: Action
    name: Setup Node Using NVM
    identifier: Setup_Node_Using_NVM
    spec:
      uses: dcodeIO/setup-node-nvm@master
      with:
        node-version: 20.12.2

Alternative: run inside a container with all required dependencies

- step:
    type: Run
    name: Build with custom image
    identifier: build_with_custom_image
    spec:
      connectorRef: my_docker_hub
      image: YourCustomImage:tag
      shell: Bash
      command: your_build_command

Verifying software versions

To see the exact versions of preinstalled software on each image, check the detailed specifications in the Harness Cloud documentation. Each image type has its own README file with current software versions and installation details.

Alternatively, if you prefer verifying software versions within your pipeline, refer to the following sample:

pipeline:
  name: Check Software Version Pipeline
  identifier: check_software_version_pipeline
  stages:
    - stage:
        name: Check Software Version
        identifier: check_software_version
        type: Custom
        spec:
          execution:
            steps:
              - step:
                  identifier: run_version_check_script
                  name: Check Software Versions
                  type: ShellScript
                  timeout: 10m
                  spec:
                    shell: Bash
                    source:
                      type: Inline
                      spec:
                        script: |-
                          echo "===== Software Version Check ====="
                          echo

                          # Node.js and NPM
                          echo "Node.js Version:"
                          node --version || echo "Node.js not installed"
                          echo

                          echo "NPM Version:"
                          npm --version || echo "NPM not installed"
                          echo

                          # Python
                          echo "Python Version:"
                          python --version || echo "Python not installed"
                          python3 --version || echo "Python3 not installed"
                          echo

                          # Java
                          echo "Java Version:"
                          java -version || echo "Java not installed"
                          echo

                          # Docker
                          echo "Docker Version:"
                          docker --version || echo "Docker not installed"
                          echo

                          # Git
                          echo "Git Version:"
                          git --version || echo "Git not installed"
                          echo

                          # Maven
                          echo "Maven Version:"
                          mvn --version || echo "Maven not installed"
                          echo

                          # Gradle
                          echo "Gradle Version:"
                          gradle --version || echo "Gradle not installed"
                          echo

                          # Go
                          echo "Go Version:"
                          go version || echo "Go not installed"
                          echo

                          # Ruby
                          echo "Ruby Version:"
                          ruby --version || echo "Ruby not installed"
                          echo

                          # Operating System
                          echo "Operating System:"
                          uname -a || echo "uname command not available"
                          cat /etc/os-release 2>/dev/null || echo "OS release info not available"
                          echo

                          echo "===== Version Check Complete ====="
            rollbackSteps: []
  description: This pipeline shows if specific tools are installed on the VM and their images (if available).
  projectIdentifier: YOUR_PROJECT_IDENTIFIER
  orgIdentifier: YOUR_ORG_IDENTIFIER

Installing additional software

While Harness VM images come with many tools preinstalled, you may need to install additional software specific to your project.

Using package managers

You can install additional packages using the system package manager during your pipeline:

steps:
  - step:
      type: Run
      name: Install Dependencies
      identifier: install_deps
      spec:
        command: |
          # Ubuntu/Debian
          sudo apt-get update
          sudo apt-get install -y your-package-name
          
          # CentOS/RHEL
          sudo yum install -y your-package-name
          
          # macOS
          brew install your-package-name

Installing language-specific packages

Install packages using language-specific package managers:

steps:
  - step:
      type: Run
      name: Install Language Packages
      identifier: install_lang_packages
      spec:
        command: |
          # Node.js packages
          npm install -g your-package
          
          # Python packages
          pip3 install your-package
          
          # Ruby gems
          gem install your-gem
          
          # Go modules
          go install your-module

Performance considerations

Installing software during pipeline execution increases build time. Consider these approaches for better performance:

• Use preinstalled software when possible

• Cache dependencies between builds when available

• Consider creating custom Docker images for complex dependencies

• Use specific tool versions that are already preinstalled

Bring Your Own Image (BYOI)

Harness supports Bring Your Own Image (BYOI), allowing you to use Harness Cloud with your own custom images. Create VM images with your tools and dependencies pre-installed for faster, more consistent CI builds.

Linux BYOI

For Linux builds, you can create custom images using Packer with the BYOI builder plugin. This allows you to:

• Pre-install development tools, SDKs, and dependencies

• Configure environment settings and files

• Build on top of Ubuntu base images or your existing BYOI images

Linux BYOI images are built with the Harness BYOI builder plugin and stored in Harness-managed storage. Unlike macOS BYOI, Linux BYOI does not use an external registry pull model. Supplying a custom image connector (for example, the Override Image Connector stage infrastructure setting) is not supported for the Linux BYOI VM image, so you cannot host the Linux BYOI image in your own registry. Reference the image by imageName:imageVersion.

Go to Harness Cloud BYOI to review detailed instructions for creating and using custom Linux images.

Windows BYOI

For Windows builds, you can create custom images using Packer with the BYOI builder plugin on Windows Server 2022 or 2025 (amd64 only). The same authoring and delivery model as Linux BYOI applies:

• Windows BYOI images are built with the Harness BYOI builder plugin and stored in Harness-managed storage.

• Windows BYOI does not use an external registry pull model. Supplying a custom image connector (for example, the Override Image Connector stage infrastructure setting) is not supported for the Windows BYOI VM image, so you cannot host the Windows BYOI image in your own registry.

• Reference the image by imageName:imageVersion.

The BYOI builder plugin accepts windows-server/2019 as base images, but that version is not yet qualified to run as CI VMs on Harness Cloud. Use windows-server/2022 or windows-server/2025 for Windows BYOI images intended to run on Harness Cloud.

Go to Harness Cloud BYOI to review detailed instructions for creating and using custom Windows images.

macOS BYOI

macOS BYOI support is also available for custom macOS build environments. Unlike Linux and Windows BYOI, which use Packer to build custom VM images stored by Harness, macOS BYOI uses an OCI registry pull model — you push a pre-configured image layer to an OCI-compatible registry, and Harness pulls it onto the macOS VM at build time.

• Setting an image pull policy is currently not supported. However, by default, an image is never pulled if it already exists on the VM.

• BYOI support requires the CI_ENABLE_BYOI_HOSTED feature flag. Contact Harness support to enable this feature.

Best Practice: Always retag your custom image with a new version whenever changes are made. This ensures Harness Cloud picks up the updated image during your build.

Staying Informed

Subscribe to the Harness CI RSS feed to receive notifications about:

• Image deprecation announcements

• New image releases

RSS Feed URL: https://developer.harness.io/release-notes/continuous-integration/rss.xml

Support and Feedback

For questions, issues, or feature requests related to Harness VM images, contact Harness Support.

Related Resources

• Use Harness Cloud Build Infrastructure

• Harness Cloud BYOI (Bring Your Own Image)

• Harness Cloud VM Image Repository