Integrating the Vega SDK into CI Pipelines

This page describes how to integrate the Vega SDK into Continuous Integration (CI) pipelines, including automated installation processes and configuration requirements. A build host is the machine (virtual or physical) that builds your Vega app as part of a CI pipeline. The Vega SDK provides an installation command on the installation instructions page that can run non-interactively, avoiding user input to facilitate automated SDK installation on a build host.

Prerequisites

Before integrating the Vega SDK into your CI pipeline, make sure that your build environment meets the following requirements. Pay particular attention to selecting the correct build host configuration, as choosing the wrong one can lead to installation or runtime errors.

System requirements

The following section lists the supported host configurations for building Vega apps in CI.

Host configurations

Operating system
- Ubuntu 20.04, 22.04, 24.04, or 26.04
  - x86_64
- macOS X
  - arm64 (M-series) — recommended
  - x86_64 (Intel)

Installation process

Installing the Vega SDK in a CI environment requires a fully automated approach. Unlike developer workstations where interactive installation is common, CI environments can’t rely on prompts. The following sections guide you through this process.

Basic installation

Edit the installation command to disable installer prompts that can interrupt an automated installation.
export NONINTERACTIVE=true
Run echo $NONINTERACTIVE to confirm it outputs true.

Configure the desired installation flags.

# Skip VVD installation.
export SKIP_VVD_INSTALL=true

# Install a specific SDK version.
export VEGA_SDK_VERSION=2.0.10945

# Download and run the installer script.
curl -fsSL https://sdk-installer.vega.labcollab.net/get_vvm.sh | bash

On success, the installer prints a confirmation message and exits with code 0. Run vega -v to confirm the SDK is installed and on the expected version before continuing.

For additional configuration options, see the following sections.

Environment variable configuration

Use the following environment variables to control the installer script.

Variable	Default	Description
`NONINTERACTIVE`	FALSE	Skip all prompts and run automatically. Required for CI/CD.
`VEGA_SDK_VERSION`	(latest)	Install a specific SDK version (for example, 2.0.10945).
`SKIP_SDK_INSTALL`	FALSE	Skip SDK installation entirely.
`SKIP_VVD_INSTALL`	FALSE	Skip VVD installation during SDK setup.

Docker integration

Docker provides a consistent and isolated environment for building applications with the Vega SDK. The following example demonstrates how to create a build environment that includes all necessary dependencies and configurations. This approach can be adapted for various CI solutions that support container-based builds.

Example Dockerfile

FROM --platform=linux/amd64 ubuntu:22.04

SHELL ["/bin/bash", "-c"]

ENV DEBIAN_FRONTEND=noninteractive

# Install cURL, build tools, and utilities to fetch the installer and build native code.
RUN apt-get update && \
    apt-get install -y curl tar jq ca-certificates build-essential --no-install-recommends && \
    rm -rf /var/lib/apt/lists/*

# Install Vega SDK.
ENV NONINTERACTIVE=true

ARG VEGA_SDK_VERSION=2.0.10945
ARG SKIP_VVD_INSTALL=true

ENV VEGA_SDK_VERSION=${VEGA_SDK_VERSION}
ENV SKIP_VVD_INSTALL=${SKIP_VVD_INSTALL}

RUN curl -fsSL https://sdk-installer.vega.labcollab.net/get_vvm.sh | bash

ENV PATH="/root/vega/bin:${PATH}"

# Verify the vega command is available.
RUN vega -v

# React Native apps require Node.js and npm.
RUN apt-get update && apt-get install -y nodejs npm --no-install-recommends && rm -rf /var/lib/apt/lists/*

# Set the global npm config path and bind mount your npmrc config to this location.
ENV NPM_CONFIG_GLOBALCONFIG="/etc/npmrc"

# Verify node and npm commands are available.
RUN node -v && npm -v

ENTRYPOINT [ "/bin/bash", "-c" ]

To build the Docker image, run the following command. Find the SDK version you need on the SDK installation page, and make sure you match the build host configuration to your CI build host, not your development machine.

docker build . --tag vega-sdk \
  --build-arg VEGA_SDK_VERSION=2.0.10945 \
  --build-arg SKIP_VVD_INSTALL=true

Validate OS version compatibility in your pipeline

To stop a pipeline before it builds an incompatible app, run vega project doctor as a build step. Run it after vega project install --fix and your package manager, and before the build.

vega project install --fix
npm install
vega project doctor
npx react-native build-vega

vega project doctor returns a non-zero exit code when a check fails, so the pipeline step fails and the build doesn’t run. Replace npm install and the build command with the package manager and build script your project uses. For the checks that doctor runs, see vega project doctor.

Best practices

Version control

Always specify exact SDK versions in your CI configuration using VEGA_SDK_VERSION.
Use version pinning for stability and reproducible builds.
Document version updates in your repository changelog.

Performance optimization

Set SKIP_VVD_INSTALL=true to reduce installation size when device emulation isn’t needed.
Use caching strategies for downloaded artifacts.
Consider multi-stage Docker builds to keep final image sizes small.

Security

Always use HTTPS download URLs.
Implement proper access controls for private npm registries.
Regularly audit your CI/CD pipeline configuration.

Troubleshooting

Installation failures

Verify network connectivity to SDK repositories.
Ensure sufficient disk space for the SDK installation.
Check that environment variables are set correctly.
Confirm you selected the correct build host configuration for your build host on the installation page.

Build errors

Verify SDK version compatibility with your app.
Check for missing dependencies in your build environment.
Review build logs for specific error messages.
Confirm you selected the correct build host configuration during installation.
Confirm your manifest.toml includes the [os.version] section. Builds fail without it. Run vega project update-manifest --os-min 2.0 --os-version 2.0 in your project before building, or add the section to your committed manifest.toml.

​Prerequisites

​System requirements

​Host configurations

​Installation process

​Basic installation

​Environment variable configuration

​Docker integration

​Example Dockerfile

​Validate OS version compatibility in your pipeline

​Best practices

​Version control

​Performance optimization

​Security

​Troubleshooting

​Installation failures

​Build errors

​Related topics