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. On the installation page, you must select the appropriate operating system and architecture for your build host. For example, if your build host is running Ubuntu 22.04, select "Linux (x86_64)" from the "Operating System" drop-down. The resulting command can then be run on the 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 platform for your build host, as choosing the wrong platform can lead to installation or runtime errors.
System Requirements
Host Configurations
- Operating System
- Ubuntu 20.04 or higher
- x86_64
- Mac OS X
- arm64 (M-series) or x86_64 (Intel)
- Ubuntu 20.04 or higher
User Requirements
Vega SDK versions prior to 0.20.3106
* Non-root user account on the build host/CI environment
* Required for all installation methods
* For direct CI/CD installations, ensure build process runs as non-root
Vega SDK versions 0.20.3106 and later
* There is no longer a requirement for a non-root user account
* Set `NONINTERACTIVE=true` for CI environments
Installation Process
The Vega SDK installation process needs special consideration when implementing it in a CI environment. Unlike developer workstations where interactive installation is common, CI environments require a fully automated approach. The following sections guide you through this process.
Basic Installation
- From the installation page, select the appropriate OS and architecture for your build host and copy the installation command
- Edit the installation command:
- Set the
NONINTERACTIVE
environment variable to disable installer prompts that can interrupt an automated installation - Remove the
--sim-url
flag and its value from to skip Vega Virtual Device installation
- Set the
- Configure the
KEPLER_SDK_PATH
andPATH
environment variables accordingly
# Replace values in angle brackets with relevant values from the installation page
curl -fsSL <installer-script-url> | NONINTERACTIVE=true /bin/bash -- --sdk-url <sdk-url> --version <version>
# Replace <version> with the SDK version
export KEPLER_SDK_PATH="$HOME/kepler/sdk/<version>"
export PATH="$KEPLER_SDK_PATH/bin:$PATH"
For additional configuration options, see the following sections.
Installation Script Flags
The installation script accepts the following command line flags.
Flag | Description | Values |
---|---|---|
--sdk-url |
SDK download URL. Required. | Can be http(s):// or file://. Does not accept plain file names. Value must be valid URL: file:///Users/somebody/sdk.sh Overrides SDK_URL environment variable |
--sim-url |
Virtual Device (VVD) download URL. Optional | Can be http(s) or file. Does not accept plain file names. Value must be valid URL: file:///Users/somebody/sim.tar.bz2 Overrides SIM_URL environment variable |
--version |
SDK version. Required. | Semantic version <major>.<minor>.<patch> Overrides VERSION environment variable |
Environment Variable Configuration
Use the following environment variables to control the installer script.
Variable Name | Valid Values | Default | Description | |
---|---|---|---|---|
DELETE_DOWNLOADS |
true | false | "true" | Controls deletion of downloaded SDK/simulator files |
DOWNLOAD_DIR |
Valid path | $HOME/Downloads | Download location for SDK/simulator | |
DIRECTED_ID |
String | - | Anonymized customer ID | |
INSECURE_DOWNLOADS |
true | false | "false" | Enables insecure curl downloads |
INSTALL_ROOT_DIR |
Valid path | $HOME/kepler/sdk | Base directory for SDK installations | |
LOG_ENABLED |
true | false | "true" | Enables file logging |
LOG_FILE |
Valid path | $HOME/.kepler/logs/kepler-YYYY-MM-DD.log | Log file location | |
NONINTERACTIVE |
true | false | "false" | Enables non-interactive installation |
OPT_IN |
true | false | "false" | Enables usage metrics collection |
VERBOSE |
true | false | - | Enables verbose output |
OVERWRITE_PREVIOUS |
true | false | Varies | Controls overwriting of existing installations |
SDK_URL |
URL | None | Required: SDK download URL | |
SIM_URL |
URL | None | Optional: Simulator download URL | |
VERSION |
String | None | SDK version number |
Installation Directory Configuration
The default installation path is $HOME/kepler/sdk/$VERSION.
To change the directory prefix where SDK versions are installed, set the INSTALL_ROOT_DIR
environment variable when running the installation script.
curl -fsSL <installer-script-url> | INSTALL_ROOT_DIR=/opt/kepler /bin/bash --version <version> --sdk-url <sdk-url>
Important Considerations
Environment Variables
After installation, you need to configure the environment to locate the SDK tools.
Set KEPLER_SDK_PATH
export KEPLER_SDK_PATH="/path/to/kepler/sdk/version"
Add to System PATH
export PATH="$KEPLER_SDK_PATH/bin:$PATH"
Example
If your SDK is installed at /home/user/kepler/sdk/0.20.3106.
export KEPLER_SDK_PATH="/home/user/kepler/sdk/0.20.3106"
export PATH="$KEPLER_SDK_PATH/bin:$PATH"
Verification: To verify correct setup, run the following command.
kepler -v
Optional VVD Image Installation
Starting in version 0.20.3106, the installation of the Vega Virtual Device (VVD) image is optional to reduce the effective size of the SDK installation:
- Remove the
--sim-url
flag to skip downloading and installing the VVD image - This can significantly reduce installation footprint in CI environments
VS Code Plugin Notes
In CI environments, you can safely ignore VS Code plugin installation errors.
Telemetry Configuration
To explicitly enable telemetry, set the OPT_IN
environment variable.
# Enable telemetry using the OPT_IN environment variable.
curl -fssL <installer-script-url> | OPT_IN=true /bin/bash --version <version> --sdk-url <sdk-url>
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 ubuntu:22.04
SHELL ["/bin/bash", "-c"]
# Need cURL to fetch the installer.
RUN apt-get update && \
apt-get install curl ca-certificates --no-install-recommends -y && \
rm -rf /var/lib/apt/lists/*
# Install Vega SDK
ARG INSTALLER_SCRIPT
ARG SDK_VERSION
ARG SDK_URL
ARG SDK_ROOT=/kepler
ARG SIM_URL
RUN test -n "$INSTALLER_SCRIPT" || (echo "INSTALLER_SCRIPT not set" && false)
RUN test -n "$SDK_VERSION" || (echo "SDK_VERSION not set" && false)
RUN test -n "$SDK_URL" || (echo "SDK_URL not set" && false)
RUN curl ${INSTALLER_SCRIPT} | NONINTERACTIVE=true INSTALL_ROOT_DIR=${SDK_ROOT} bash -s -- \
--sdk-url=${SDK_URL} \
--sim-url=${SIM_URL} \
--version=${SDK_VERSION}
## Setup required environment variables
## Note that the script installs into $SDK_ROOT/sdk/$SDK_VERSION
## If $SDK_ROOT was not set, it defaults to /kepler
ENV KEPLER_SDK_PATH="$SDK_ROOT/$SDK_VERSION"
ENV PATH="$KEPLER_SDK_PATH/bin:$PATH"
## Verify kepler command is available
RUN kepler -v
# If you are building a React Native app, NodeJS and NPM are required
RUN curl -sL https://deb.nodesource.com/setup_lts.x | bash -
RUN apt-get update && apt-get install -y nodejs
RUN npm install -g npm
## Set global npm config path to /etc/npmrc
## 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" ]
Build the Docker image
The following code example shows how to build a Docker image using the example Dockerfile file. Replace the Dockerfile build arguments with the values provided to the installation script flags in the generated installation command:
- Set
INSTALLER_SCRIPT
to the value to the URL passed to the curl command - Set
SDK_URL
to the value passed to the--sdk-url
script flag - Set
SIM_URL
to the value passed to the--sim-url
script flag - Set
SDK_VERSION
to the value passed to the--version script
flag
docker build . --tag ksdk \
--build-arg INSTALLER_SCRIPT=<installer-script-url> \
--build-arg SDK_URL=<sdk-url> \
--build-arg SIM_URL=<sim-url> \
--build-arg SDK_VERSION=<version> \
--build-arg SDK_ROOT=/tmp/kepler
Last updated: Oct 14, 2025