Application and Platform Update Flows

1. Overview

The Eureka CI system has two levels of automated updates that work together:

• Application-level — updates individual app-* repositories with latest module versions from the FOLIO registry

• Platform-level — updates platform-lsp with the latest application versions from the FOLIO Application Registry (FAR)

Each level has its own update schedule, validation gates, and commit strategy.

2. End-to-End Flow

The two levels form a pipeline: modules flow into applications, and applications flow into the platform. Each application repository runs its own independent update scheduler — all 30+ app-* repos update in parallel, with no coordination between them.

Each app-* repository has its own update-scheduler.yml (from folio-app-template) that triggers independently every 20 minutes. Repositories do not wait for or depend on each other's updates. This means that at any point in time, multiple application updates may be running concurrently, each resolving its own modules, validating, and publishing to FAR independently.

Timing: A module version change propagates through the full pipeline within ~80 minutes: up to 20 min for the app-level update, then up to 60 min for the platform-level update.

Key Components

3. Application-Level Update Flow

Source code: kitfox-github (reusable workflows and actions), folio-app-template (per-repo scheduler).

Trigger: update-scheduler.yml runs every 20 minutes in each app-* repository. It reads .github/update-config.yml to determine which branches to update and how.

3.1. Snapshot Flow (direct commit)

The snapshot flow is the primary continuous integration path. It runs on branches configured with need_pr: false and pre_release: "only".

Key characteristics:

• No PR required — commits directly to snapshot branch

• Pre-release versions only (SNAPSHOT, alpha, beta)

• Build offset creates unique version numbers: X.Y.Z-SNAPSHOT.{offset+runNumber}

• Publishes to FAR BEFORE commit (unpublishes on commit failure to prevent orphaned descriptors)

3.2. Release Flow (via PR)

The release flow is used for stable release branches. It runs on branches configured with need_pr: true and pre_release: "false".

Key characteristics:

• PR required — team reviews before merge

• Stable versions only (no pre-release)

• Merge queue enforces CI validation before merge

• Post-merge re-validation ensures published descriptor matches committed state

4. Platform-Level Update Flow

Source code: platform-lsp repository (workflows, actions, and shell scripts).

The platform descriptor (platform-descriptor.json) lists all applications and their versions that compose the FOLIO platform. It also includes Eureka infrastructure components (eureka-components).

4.1. Snapshot (Hourly Check)

Trigger: ci-hourly-check.yaml runs every hour on the snapshot branch.

Key behavior: platform-descriptor.json is NOT updated if interface validation fails. This is the platform-level safety gate — even if an app publishes an incompatible descriptor to FAR, platform-lsp refuses to reference it until interfaces are consistent across all apps.

4.2. Release (release-update-flow)

Trigger: Manual workflow_dispatch or automated via update-config.yml (currently R1-2025-ci branch is enabled with need_pr: true).

Key difference from snapshot: The release flow does NOT perform the validate-interfaces call. It relies on the app-level validation that already ran before apps were published to FAR.

5. Validation Architecture

Three distinct validation checkpoints exist across the two levels:

Overlap Between Type 2 and Platform Validation

• Type 2 runs BEFORE the app descriptor is committed — it is preventive, blocking the app from publishing an incompatible descriptor

• Platform validation runs AFTER app descriptors are published to FAR — it is a gate, blocking the platform descriptor from referencing incompatible apps