How-To Release Application Updates

This page describes the automated module update cycle on release branches — from the moment new module versions are detected to the point where the pull request is merged, published, and the update branch is cleaned up. For a broader overview of managing an application on a release branch, see Releasing Applications on a Release Branch.

Purpose

On release branches, module version updates are delivered through automated pull requests rather than direct commits. This ensures that every change is validated, reviewed, and merged in a controlled manner. The update scheduler creates these PRs, and the merge queue processes them after approval.

How the Update Cycle Works

The following sequence describes the end-to-end flow from module version detection to published application descriptor:

1. Scheduler runs (every 20 minutes) → resolves module versions from the FOLIO registry

2. Changes detected → new versions satisfy the template constraints

3. PR created or updated → changes committed to the update branch, PR opened

4. CI validation runs → module interface integrity and dependencies integrity checks

5. Application maintainer reviews and approves → PR enters the merge queue

6. Merge queue processes → validates against current branch state, squash-merges

7. Post-merge flow → publishes descriptor to FAR, deletes update branch, sends notification

8. Tag the release version (manual) → application maintainers tag the merge commit

Step 1: Update Scheduler Detects New Module Versions

The update scheduler runs on a cron schedule (every 20 minutes) for each enabled branch in update-config.yml. For release branches, the process:

• Reads application.template.json and resolves each module's version constraint against the FOLIO module registry

• Compares the resolved versions with the current application.lock.json state file

• If any module version has changed, proceeds to create or update a pull request

• If no changes are found, the run completes with no action

The scheduler respects the preRelease configuration for each branch — filtering for stable release versions ("false"), pre-release versions only ("only"), or both ("true"). On release branches, preRelease is typically set to "false", meaning only stable module versions are considered. The version constraints in the template control which versions match (e.g., ^2.0.0 matches any 2.x.x stable release).

Step 2: Pull Request Is Created or Updated

When version changes are detected, the scheduler commits them to the update branch and opens a PR:

• Update branch: version-update/{release-branch-name} (e.g., version-update/R1-2025)

• PR title: Follows the pattern "Release: Update to {version}"

• PR body: Contains a module change summary generated by the compare-state-files action:

  • + New modules added

  • → Modules upgraded (old version → new version)

  • ← Modules downgraded

  • − Modules removed

If an existing open PR already exists for the same update branch, it is updated with the latest changes rather than creating a duplicate.

Open

Step 3: CI Validation Runs

The required check eureka-ci / validate-application runs automatically on the PR. This check performs two validations:

Module Interface Integrity

• Verifies all module versions exist in the FOLIO module registry

• Validates that module interfaces are compatible (provided vs. required interfaces match)

• Endpoint: FAR POST /applications/validate

Dependencies Integrity

• Validates the application's dependency chain against other published applications

• Fetches dependency descriptors from FAR

• Verifies no missing or conflicting cross-application dependencies

• Endpoint: FAR POST /applications/validate-descriptors

Both checks must pass for the PR to be merge-eligible. For detailed information on validation behavior, including when dependency checks are skipped, see Dependency Validation Behavior.

Open

Open

Step 4: PR Approval

Reviewers are assigned automatically based on the pr_reviewers configuration in update-config.yml. The review process:

• Review the module change summary in the PR description

• Verify that the version changes are expected (e.g., a new patch release of a module, not an unexpected major bump)

• Confirm that CI validation has passed

• Approve the PR

Once approved, the PR automatically enters the merge queue.

Open

Open

Open

Open

Step 5: Merge Queue Processes the PR

After approval, the merge queue takes over. No manual merge action is required.

Merge queue behavior:

What happens during merge queue processing:

1. The PR enters the queue

2. The queue validates the PR against the current branch state (re-runs CI checks if needed)

3. If multiple PRs are queued, they are validated together

4. Once all checks pass, the PR is squash-merged automatically

5. The merged changes update the release branch with new module versions

How the merge queue is configured: The merge queue behavior is controlled by the branch ruleset for the release branch. The ruleset is configured declaratively in update-config.yml and applied automatically by the CI system. To verify the merge queue configuration, navigate to the application repository on GitHub → Settings → Rules → locate the {branch}-eureka-ci ruleset (e.g., R1-2025-eureka-ci). For full details on ruleset configuration, see Branch Ruleset Automation.

Open

Open

Open

Step 6: Post-Merge Processing

After the merge queue squash-merges the PR, the post-merge flow is triggered automatically by the Eureka CI GitHub Application. This flow performs several critical operations in sequence:

The post-merge flow runs automatically when a version-update PR is merged on a release branch. No manual action is required.

Publish to FAR — reads application.lock.json from the release branch (now containing the merged changes) and publishes the application descriptor to the FOLIO Application Registry (FAR) via the publish-app-descriptor action. This makes the new application version available for dependency validation by other applications.

Cleanup update branch — deletes the update branch (e.g., version-update/R1-2025) via the GitHub API. This deletion is intentional — it ensures the next scheduler cycle starts fresh with a new branch and a new version increment. See Update Branch Lifecycle for the full create–use–delete–recreate pattern.

Slack notification — sends a notification to the team channel (configured via the SLACK_NOTIF_CHANNEL repository variable) and the general notification channel, reporting:

• Release branch name

• PR number and link

• Published descriptor ID

• Commit SHA

• Branch cleanup status

Open

Open

Step 7: Tag the Release Version

Application maintainers may choose to perform a manual release at any point during the release cycle. This is a manual step — it is not automated by the CI system. The manual release process involves:

1. Tag the current version on the release branch (e.g., v2.0.1) using the GitHub Releases UI or the mvn deploy command

2. Bump the application minor version in pom.xml on the release branch (e.g., 2.0.1 → 2.1.0) to prepare for the next update cycle

Tagging ensures that the released version is traceable and identifiable in the repository history. The minor version bump signals the start of a new release iteration, and subsequent automated update cycles will increment the patch version from the new baseline (e.g., 2.1.0 → 2.1.1).

Common Scenarios

Multiple Module Updates at Once

When several modules publish new versions simultaneously, the scheduler bundles all changes into a single PR. If a PR already exists and new changes arrive before it is merged, the existing PR is updated.

Manual Changes Needed on the Release Branch

Manual changes to the application composition are made by editing application.template.json on the release branch. The template is the primary tool for controlling which modules and versions belong to the application. Common scenarios include:

• Pinning a specific module version — change the version constraint to an exact version (e.g., "version": "=7.1.2") to prevent the scheduler from upgrading beyond that version

• Adjusting a version constraint — broaden or narrow the range (e.g., change ^7.0.0 to ~7.1.0)

• Adding or removing a module — add a new entry to or remove an entry from the modules or uiModules array

After editing application.template.json, commit and push the changes directly to the release branch. The update scheduler detects the template changes on the next 20-minute cycle and creates a new PR reflecting the combined effect of the manual changes and any pending module updates.

For detailed instructions on adding, removing, or moving modules between applications, see Adding, Removing, or Moving Modules.

Temporarily Pausing Updates

To pause automated updates for a release branch:

1. Edit .github/update-config.yml on the default branch

2. Set enabled: false for the specific branch in the branches section

3. Commit and push the change

4. Re-enable when ready by setting enabled: true

Troubleshooting

Configuration Reference

For detailed field-by-field documentation of update-config.yml, including merge queue settings, bypass actors, and branch-specific configuration, see Understanding Application Repository Files — .github/update-config.yml.

Related Pages

• Releasing Applications on a Release Branch — broader lifecycle guide for applications on release branches

• Creating a Release Branch — how release branches are created

• Understanding Application Repository Files — Workflow Files — detailed reference for both CI workflows