How to create your own CI/CD pipeline (Omniverse example)

Here you can find an example GitHub Actions pipeline for building and deploying Omniverse on Portal.

To learn how to get started with creating your own custom kit application on Portal, read How to create and stream your own Kit app.

name: Build and Deploy (Minimal Example)

# This is a reusable workflow, meant to be called from another workflow.
on:
    workflow_call:
        inputs:
            portal-app-id:
                description: 'The ID of the Portal application to upload the build to.'
                required: true
                type: string
            app-name:
                description: 'The app name to be used for build and package'
                required: true
                type: string
        secrets:
            PORTAL_CI_PASSWORD:
                required: true
            PORTAL_CI_USERNAME:
                required: true

jobs:
    build_package_and_upload:
        runs-on: windows-latest
        steps:
            # 1. Checkout Code
            -   name: Checkout Repository
                uses: actions/checkout@v3
                with:
                    lfs: true
                    fetch-depth: 0
            
            # 2. Versioning
            -   name: Set Build Version
                id: versioning
                run: |
                    $versionLine = Get-Content tools/VERSION.md | Select-Object -First 1
                    $kitVersion = $versionLine -split '-' | Select-Object -First 1
                    $version = "$kitVersion+${{ github.run_number }}"
                    echo "version=$version" >> $env:GITHUB_OUTPUT

            # 3. Build Omniverse Kit Application
            -   name: Build Kit Application
                run: ./repo.bat build -x
            
            # 4. Package Omniverse Kit Application (Creating the ZIP file/artifact)
            -   name: Package Kit Application
                run: ./repo.bat package --name ${{ inputs.app-name }}
            
            # 5. Install Portal Client
            -   name: Install Portal Client
                uses: actions/setup-python@v4
                with:
                    python-version: '3.10'
            -   name: Install Portal Python Client
                run: pip install portal-client@git+https://github.com/Innoactive/Portal-Python-CLI.git@v3.3.0

            # 6. Upload to Portal
            -   name: Upload to Portal
                id: upload
                run: |
                    # Package step places the ZIP in ./_build/packages/
                    $archivePath = Get-ChildItem -Path "./_build/packages/*.zip" | Select-Object -ExpandProperty 'FullName'
                    $version = '${{ steps.versioning.outputs.version }}'

                    Write-Host "Uploading $archivePath to Application ID: ${{ inputs.portal-app-id }}"

                    # Portal Upload command
                    innoactive-portal applications v2 upload-build `
                    --app-id ${{ inputs.portal-app-id }} `
                    --xr-platform win-vr `
                    --executable-path 'kit/kit.exe' `
                    --launch-args 'apps/your_application.kit' `
                    --target-platform windows `
                    --version $version `
                    $archivePath
                env:
                    # Credentials needed for the innoactive-portal command
                    PORTAL_BACKEND_USERNAME: ${{ secrets.PORTAL_CI_USERNAME }}
                    PORTAL_BACKEND_PASSWORD: ${{ secrets.PORTAL_CI_PASSWORD }}

Explanation:

1. Checkout Repository
   First we do what pretty much any build pipeline does: we checkout the repository containing our kit application.

2. Versioning
   This step determines the version of our build and is just an example of how this can be done. There are many valid ways of versioning. Use whatever is applicable in your case.
   This example creates versions looking like {Omniverse Version}+{GitHub Run Number}, e.g. 109.0.1+30.

3. Build Kit Application
   Next step is to build the kit application using the ./repo.bat build -x command. The -x causes a clean build, discarding any leftovers from previous builds. While this isn’t strictly necessary when using GitHub agents, it is good practice so no matter the circumstances you get a good, clean build.

4. Package Kit Application
   After a successful build step follows the package step using ./repo.bat package --name {AppName}. It creates a self-contained zip file containing everything that is required to run your kit application without external dependencies and without requiring additional downloads.

5. Install Portal Client
   The Portal client is a CLI tool provided by Innoactive for interacting with the Portal API. This step installs a specific version, in this case v3.3.0. Check the repository for updates and other ways of using this tool: https://github.com/Innoactive/Portal-Python-CLI

6. Upload to Portal
   Final step of our pipeline is to upload the kit application package from step 4. We find the zip file to upload, get the version from step 2, then use the Portal client application to upload.
   It requires the app-id (find it on the Integrations tab of your application in Portal Control Panel), the platform(s) to use, executable path and arguments, target platform, version to use in Portal and finally the zip file to upload.
   For interacting with the API, a set of username/password is required. Ideally this is some kind of system account like portal-ci@your-company.com.

Additional steps & possibilities

Wrapper

The wrapper is a small application that allows launching Omniverse in just the right way based on the users selection in Portal and their hardware (e.g. whether to stream to the browser or to an XR device). It gives developers the flexibility of supporting all ways of streaming Portal has to offer.

An additional step would be required to copy it to the build output directory for it to be part of your application package.

The wrapper application is not publicly available. Contact us to get started.

Portal CLI

The Portal CLI offers additional control over your application:

• set a specific build as the active one

• provide a changelog

• …

Versioning

The example shows one of many possible versioning schemes. We recommend using some kind of semantic versioning.

The example only sets the version on Portal. The running application itself will show whatever version is currently set in your application configuration. An additional step before building could also update your application kit file version through a bit of scripting.

Conclusion

This minimal example is meant to be a base for you to get started and shows the basics. Depending on your use case, you’ll likely add additional steps or modify the ones already there.

The steps should be easy to translate to other CI/CD systems if you’re not using GitHub Actions.

While this example shows how to build and publish an Omniverse application, the basic steps remain more or less the same when building other applications:

1. Checkout

2. Determine version

3. Build

4. Upload

If you need additional advice or help creating a workflow for your use case, contact us.