Application Registry Continuous Integration

The Application Registry encourages the use of Continuous Integration for building and delivering applications to the Atlas Manager.

To support quickly integrating applications with the Atlas Manager, Bash and Powershell scripts are provided to integrate into your pipelines.

Atlas currently provides quick start templates for Bitbucket Pipelines, Github Actions, Gitlab and Jenkins but other CI servers capable of executing Bash and Powershell scripts may easily utilize the Atlas upload scripts.

WARNING

This document attempts to provide a high-level quick start, but server configuration and access may vary. For support please contact your internal Continuous Integration Service Manager or reach-out to Upswell for clarification.

Before You Begin

This document assumes that:

• You have supported CI platform, or platform capable of executing Bash or Powershell scripts as part of a build process
• Your application is available in a Git repository, or other source control platform accessible to your CI server
• You have a CI Service Account assigned to the CI/CD group

CI Server Dependencies

The Atlas Upload Script requires the following dependencies. Some container based systems may be able to install these dependencies at build time, while others may require that the be installed on the host build system:

Linux

• curl
• jq
• openssl
• zip

For Debian based systems:

sudo apt install curl jq openssl zip

Windows

For Windows based systems:

JQ

winget install jqlang.jq
# or
scoop install jq
# or
choco install jq

Or see JQ Downloads for executables.

Integration Platforms

Bitbucket Pipelines

WARNING

Bitbucket Pipelines only support building with Linux based containers. Windows applications capable of using Wine, such as Electron may work on Bitbucket, but most Windows applications should be built in a Windows based build environment.

Bitbucket Pipelines assumes that your projects Git repository is hosted on Bitbucket.

Quick start Bitbucket Pipelines templates are available in the Experience Manager, navigate to Applications (/applications/applications/) and select your Application and then select Bitbucket. Copy the template and create a file called bitbucket-pipelines.yml in the root of your directory.

Setup

To get started with Bitbucket Pipelines, open your repository in Bitbucket and select Repository Settings / Settings and then select Enable Pipeline.

Once you have Service Account credentials, select Repository Settings / Repository Variables and add them as XM_USERNAME and XM_PASSWORD.

Build Step

This Pipeline uses the Debian based debian:11-slim image to upload builds to the Experience Manager. You may choose to specify a langauge specific container such as node:22.16.0 or python:3.11-slim-bullseye you may choose to specify a language specific image in the templates &build step to ensure you start with the appropriate build dependencies.

steps:
- step: &build
    name: Build
    image: node:22.16.0
    caches:
        - node
    script:
        - yarn
        - yarn build
    artifacts:
        - dist/**

Github Actions

Gitlab

Gitlab CI/CD provides the ability to build applications for multiple OS’s and architectures with one job so long as runners are available for those systems.

When working with Gitab, it is assumed that you are familair with configuring Gitlab CI/CD via a .gitlab-ci.yml and that your Gitlab server has access to the Git repository for your application.

Setup

Once your repository is setup in Gitlab, you will need to need to provide your Service Account credentials. Under Gitlab CI/CD settings, locate CI/CD / Variables. Add the credentials as ATLAS_CI_USERNAME and ATLAS_CI_PASSWORD.

Build Step

The provided template is setup to run parallel builds allowing Gitlab to build for multiple OS’s and architectures with a single job. Additional build and upload stages may be added changing the label to match the appropriate Gitlab runner:

build_windows_x86_64:
  stage: build
  tags: [windows, x86_64]
  script:
    - 
  rules:
    - if: '$CI_COMMIT_BRANCH == "main" || $CI_COMMIT_BRANCH == "dev"'

build_debian_x86_64:
  stage: build
  tags: [linux, x86_64]
  script:
    - 
  rules:
    - if: '$CI_COMMIT_BRANCH == "main" || $CI_COMMIT_BRANCH == "dev"'

build_macos_arm:
  stage: build
  tags: [windows, arm]
  script:
    - 
  rules:
    - if: '$CI_COMMIT_BRANCH == "main" || $CI_COMMIT_BRANCH == "dev"'

TIP

Take note of the label indicating which Gitlab should be used to build the application this will be different on your system. Consult with your Gitlab Service Manager, or review your Gitlab Runner tags under Settings / CI/CD / Runners, scroll down to Available specific runners or Shared runners to determine the appropriate labels.

WARNING

Each application has a different Application ID: /get/ci/ps1/00000000-0000-0000-0000-000000000000/. Ensure that when building an application for multiple OS’s, you provide a different Application ID for each OS.

Jenkins

Jenkins provides the ability to build applications for multiple OS’s and architectures with one job so long as the build Nodes are available for those systems. As Jenkins is commonly used for building Windows applications, containers are not used in the pipeline examples and it is assumed that all build dependencies are installed on each Jenkins build Node.

When working with Jenkins, it is assumed that you are familair with configuring Jenkins Pipelines via a Jenkinsfile and that your Jenkins server has access to the Git repository for your application.

Setup

If your Jenkins server does not already have stored Service Account credentials, select Manage Jenkins / Credentials and the select the global domain and + Add Credentials. On the New credentials screen, for Kind select Secret text, ID enter ATLAS_CI_USERNAME and then provide the username in the Secret field. Repeat for ATLAS_CI_PASSWORD.

From here you may create a new Multibranch Pipeline.

Build Step

The provided template is setup to run parallel builds allowing Jenkins to build for multiple OS’s and architectures with a single job. Add additional sub-stages within the Build and Upload.

parallel {
    stage('Windows x86_64') {
        agent {
            label 'windows'
        }
        steps {
            powershell '''
            '''
        }
    }
    stage('Debian ARM') {
        agent {
            label 'linux arm'
        }
        steps {
            sh '''
            '''
        }
    }
}

TIP

Take note of the label indicating which Jenkins Node should be used to build the application this will be different on your system. Consult with your Jenkins Service Manager, or review your Jenkins Node Labels under Manage Jenkins / Nodes to determine the appropriate labels.

WARNING

Each application has a different Application ID: /get/ci/ps1/00000000-0000-0000-0000-000000000000/. Ensure that when building an application for multiple OS’s, you provide a different Application ID for each OS.

Customizing Builds

DEBUG_CI (Linux Only)

When building on Linux, with Bash, set DEBUG_CI to any value to trace each command as it runs.

DIR_DIST

The Experience Manager upload script assumes that your build distribution will be located in the ./dist directory. You may override this behavior in your Pipelines by setting the DIR_DIST environment variable. The DIR_WORKING (Bash) and $dir_working (Powershell) variables are available for use to build an absolute path to your build.

export DIR_DIST="${DIR_WORKING}/my_build_directory"

$dir_dist="${DIR_WORKING}/my_build_directory"

DIR_WORKING

The DIR_WORKING variable ensures that the upload script is running from the right location. When using one of the supported Integration Platforms, DIR_WORKING will be set automatically and will default to the abolute path to the root folder of your version controlled project.

The default DIR_WORKING behavior may be changed by setting the DIR_WORKING variable, or environment variable prior to executing the upload script.

export DIR_WORKING=/workspace/my-project/src/

$dir_working = "/workspace/my-project/src/"  # or
$env:DIR_WORKING = "/workspace/my-project/src/"

VERSION

The Atlas CI Upload Script will automatically manage the version number of your application unless you choose to override the VERSION environment variable and provide the application version.

By default, the application VERSION will be set to dev when built from branches named devor develop indicating the the build is a development pre-release.

TIP

dev is the only version in the Experience Manager that may be overwritten – overwritting other versions will raise an error.

For non-development branches, the build number will automatically be set to the CI server build number for that CI job/task. The incrementing behavior varies from playform to platform, but the build number will at minimum increment up +1 per build or per-branch build.

TIP

The default versioning behavior does not follow MAJOR.MINOR.PATCH semantic versioning. Versions will be a single integer only (i.e. 12).

You may choose to manage the version number by setting the VERSION environment variable. For instance, if you have a file named VERSION in the root of your propject, you could extract the version as follows:

export VERSION=$(cat VERSION)

WARNING

When using VERSION you are responsible for all versioning, including dev builds.