Custom & Optional Applications in CI/CD Pipelines (Architectural Design)

1. Problem Statement

The current CI/CD pipeline infrastructure supports deploying environments with applications from the FOLIO Application Registry (FAR), where all application versions are production-ready snapshots or releases. There is no mechanism to:

Deploy environments with experimental applications that are still in development
Build application descriptors from feature branches using custom module versions stored in ECR/S3
Reference feature-branch-built application descriptors in the platform descriptor instead of FAR versions
Validate Docker images in ECR during application descriptor generation
Deploy custom UI modules from feature branches

2. Current Architecture

Environment Provisioning Flow

Key Components

Component	Role	Location

Component	Role	Location
`platform-lsp`	Central platform descriptor with app list + versions	`platform-descriptor.json`
`FAR`	Application descriptor registry	`https://far.ci.folio.org`
`pipelines-shared-library`	Jenkins pipeline logic	`folioNamespaceCreateEureka.groovy`
`kitfox-github`	GitHub Actions CI for app builds	`application-update-flow.yml`
`folio-application-generator`	Maven plugin for descriptor generation	Okapi/S3 registries, DockerHub/NPM validation
`v2/modules/buildPush`	Standalone module build pipeline	Compile, Docker build, ECR push, S3 descriptor
`deployModuleFromFeatureBranchEureka`	Feature module deploy pipeline	Build + deploy to running env

Application Selection (Jenkins UI)

folioStringScripts.getApplicationsFromPlatformDescriptor() fetches platform-descriptor.json from GitHub raw and populates PT_CHECKBOX parameters. Currently all required and optional apps are marked as :selected (checked).

Module Registry Routing (`folioHelm.determineModulePlacement()`)

Version Pattern	Registry	Example

Version Pattern	Registry	Example
`X.Y.Z` (release)	DockerHub `folioorg`	`1.2.0`
`X.Y.Z-SNAPSHOT.NNN` (numeric)	DockerHub `folioci`	`1.2.0-SNAPSHOT.123`
`X.Y.Z-SNAPSHOT.xxxxx` (5+ chars)	ECR	`1.2.0-SNAPSHOT.5dc446`
`X.Y.Z-SNAPSHOT` (bare)	ECR	`1.2.0-SNAPSHOT`
Custom module / `ui-bundle` / native	ECR	Any

3. Proposed Architecture: Custom Version Deployment Flow

4. Workstreams

WS1: Experimental Applications in platform-descriptor

Objective: Allow applications to appear unchecked by default in the Jenkins pipeline UI, excluded from interface validation during CI updates.

Schema change in platform-descriptor.json (snapshot branch only):

{
  "applications": {
    "required": [
      {"name": "app-platform-minimal", "version": "2.0.24"},
      {"name": "app-platform-complete", "version": "2.1.40"}
    ],
    "optional": [
      {"name": "app-acquisitions", "version": "1.0.22"}
    ],
    "experimental": [
      {"name": "app-new-feature", "version": "0.1.0-SNAPSHOT.100100000000123"}
    ]
  }
}

Pipeline UI: getApplicationsFromPlatformDescriptor() iterates experimental apps WITHOUT :selected suffix, so they appear unchecked in Jenkins PT_CHECKBOX.

CI update: check-apps.sh processes experimental apps for version updates from FAR but does NOT add them to app_ids[] array used for interface validation.

Affected files:

platform-lsp/platform-descriptor.json
platform-lsp/scripts/check-apps.sh
pipelines-shared-library/vars/folioStringScripts.groovy

WS2: Feature Build Support via Extended application-update-flow

Objective: Enable building application descriptors from feature branches using custom module registries, without publishing to FAR.

Approach: Extend existing application-update-flow.yml with new optional inputs:

Input	Purpose	Default

Input	Purpose	Default
`fallback_registries`	S3 fallback for custom module descriptors	`''`
`be_artifact_registries`	ECR for custom Docker image validation	`''`
`skip_far_publish`	Skip FAR publish for feature builds	`false`