Understanding Application Repository Files

This page provides a detailed field-by-field reference for every file in an app-* repository. For an overview with annotated examples, see the parent page Working with Application Repositories.

application.template.json

This is the primary configuration file that defines the application's module composition. The CI system reads this file to resolve module versions and generate the final application descriptor.

Top-Level Fields

Field	Type	Description

Field	Type	Description
`name`	string	Application name. Use `${project.name}` for Maven substitution from pom.xml
`version`	string	Application version. Use `${project.version}` for Maven substitution from pom.xml
`description`	string	Brief description. Use `${project.description}` for Maven substitution from pom.xml
`dependencies`	array	Other applications this app depends on (optional)
`modules`	array	Backend modules (`mod-*`)
`uiModules`	array	Frontend modules (`folio_*`)

Module Entry Fields

Each entry in modules and uiModules arrays has:

Field	Type	Required	Description

Field	Type	Required	Description
`name`	string	Yes	Module name (e.g., `mod-agreements` or `folio_agreements`)
`version`	string	Yes	Version constraint — see Version Constraints below
`preRelease`	string	Yes	Pre-release filter: `"false"`, `"only"`, or `"true"` — see Version Constraints below

Pre-release branch example:

{
  "name": "mod-agreements",
  "version": "latest",
  "preRelease": "only"
}

Release branch example:

{
  "name": "mod-agreements",
  "version": "^2.1.0",
  "preRelease": "false"
}

Dependency Entry Fields

Entries in the dependencies array follow the same format as module entries:

{
  "name": "app-licenses",
  "version": "^1.0.0",
  "preRelease": "false"
}

On pre-release branches, dependency versions include a -SNAPSHOT suffix:

{
  "name": "app-licenses",
  "version": "^1.0.0-SNAPSHOT",
  "preRelease": "only"
}

Legacy File: app-{name}.template.json

The app-{name}.template.json file (e.g., app-agreements.template.json) is a legacy file. It is not referenced in pom.xml and is not used by the Maven build. Do not edit it. It may be removed in the future.

Version Constraints

Version constraints control which module versions the CI system resolves from the FOLIO module registry.

Version constraint syntax (supported operators):

Constraint	Meaning	Example

Constraint	Meaning	Example
`latest`	Any version (equivalent to `>=0.0.0`)	Resolve the newest available version
`^X.Y.Z`	Compatible with major version	`^2.0.0` matches `2.0.0` through `2.x.x`
`~X.Y.Z`	Compatible with minor version	`~2.1.0` matches `2.1.0` through `2.1.x`
`>=X.Y.Z`	Greater than or equal	`>=2.0.0` matches `2.0.0` and above
`>X.Y.Z`	Greater than	`>2.0.0` matches above `2.0.0`
`<=X.Y.Z`	Less than or equal	`<=3.0.0` matches up to `3.0.0`
`<X.Y.Z`	Less than	`<3.0.0` matches below `3.0.0`
`=X.Y.Z`	Exact version	`=2.1.3` matches only `2.1.3`

Constraints can include a -SNAPSHOT suffix for pre-release dependency resolution (e.g., ^1.0.0-SNAPSHOT).

preRelease field controls which module builds are considered:

Value	Behavior

Value	Behavior
`"only"`	Only pre-release versions — used on pre-release branches (e.g., snapshot)
`"false"`	Only stable (release) versions — used on release branches
`"true"`	Both pre-release and release versions

Typical branch patterns:

Pre-release branch: "version": "latest" + "preRelease": "only" — resolves the newest pre-release build
Release branch: "version": "^X.Y.Z" + "preRelease": "false" — resolves the newest stable release within the caret range

application.lock.json (State File)

The application.lock.json is an auto-generated file that contains the fully resolved application descriptor — the same descriptor that is published to FAR. Never edit it manually.

Purpose:

Holds the latest version of the application descriptor with pinned module versions
Used by the folio-application-generator as the baseline to produce an updated descriptor and determine whether any module versions have changed
Tracked in git — committed alongside template changes

Contents:

Field	Description

Field	Description
`id`	Resolved application identifier (e.g., `app-agreements-1.0.0-SNAPSHOT.100200000005244`)
`name`	Application name
`version`	Resolved application version (with build offset for pre-release)
`description`	Application description
`modules`	Array of backend modules with resolved `id`, `name`, `version`
`uiModules`	Array of frontend modules with resolved `id`, `name`, `version`
`dependencies`	Application dependencies (with version constraints, not resolved)
`moduleDescriptors`	Full backend module descriptors (interfaces, permissions, launch descriptors)
`uiModuleDescriptors`	Full frontend module descriptors

When it changes: Every time the update scheduler runs and resolves new module versions, this file is updated automatically (committed directly on branches with need_pr: false, included in PRs on branches with need_pr: true).

pom.xml

The Maven build configuration file. Key elements for application repositories:

Element	Purpose	Example

Element	Purpose	Example
`<version>`	Application version (source of truth)	`1.0.0`
`<artifactId>`	Application identifier	`app-agreements`
`<name>`	Display name (used for `${project.name}` substitution)	`app-agreements`
`<description>`	Application description (used for `${project.description}` substitution)	`Agreements application`
`<templatePath>`	Path to the active template	`${basedir}/application.template.json`

Plugin configuration:

Element	Value

Element	Value
Plugin	`org.folio:folio-application-generator`
Version	`1.4.1-SNAPSHOT`
Goal	`generateFromJson`
Registry URL	`https://folio-registry.dev.folio.org`

Note: Application versions do not use -SNAPSHOT suffix. The version is a plain semver (e.g., 1.0.0, 2.0.0). During release preparation, the version is incremented automatically.

.github/update-config.yml

This file controls how the CI automation updates the application across different branches.

update_config Section

Field	Type	Description	Example

Field	Type	Description	Example
`enabled`	boolean	Enable/disable automated updates globally	`true`
`update_branch_format`	string	Branch naming template for update PRs. `{0}` = target branch name	`version-update/{0}`
`labels`	array	Labels applied to automated PRs	`["version-update"]`
`pr_reviewers`	array	GitHub teams/users for PR review. Format: `folio-org/{team-name}`	`["folio-org/kitfox"]`

ruleset Section

Controls GitHub branch protection rulesets applied automatically. The ruleset section contains several sub-sections described below. For a guide on how rulesets are applied in practice, see Branch Ruleset Automation.

Field	Type	Description	Example

Field	Type	Description	Example
`enabled`	boolean	Enable branch protection ruleset	`true`
`pattern`	string	Ruleset name pattern (`{0}` = branch name)	`"{0}-eureka-ci"`
`required_checks`	array	Status checks that must pass	See below

Each required_checks entry:

Field	Description

Field	Description
`context`	Check name (typically `"eureka-ci / validate-application"`)

merge_queue Sub-Section

The merge_queue configuration is part of the ruleset section and controls how the merge queue operates for release branches:

Field	Type	Description	Default

Field	Type	Description	Default
`enabled`	boolean	Enable merge queue	`true`
`check_response_timeout_minutes`	number	Timeout for CI checks	`60`
`grouping_strategy`	string	How PRs are grouped: `"ALLGREEN"` (all must pass)	`"ALLGREEN"`
`max_entries_to_build`	number	Max concurrent builds in queue	`5`
`max_entries_to_merge`	number	Max concurrent merges	`5`
`merge_method`	string	Merge method: `"SQUASH"`, `"MERGE"`, or `"REBASE"`	`"SQUASH"`
`min_entries_to_merge`	number	Min entries before merging starts	`1`
`min_entries_to_merge_wait_minutes`	number	Wait time for batching	`5`

bypass_actors Sub-Section

The bypass_actors configuration is part of the ruleset section and defines which actors can bypass the ruleset checks:

Field	Type	Description	Example

Field	Type	Description	Example
`actor_type`	string	Type of actor that can bypass	`"Integration"`
`bypass_mode`	string	When bypass applies	`"always"`

This allows the Eureka CI GitHub Application to commit directly without triggering ruleset checks.

branches Section

Array of branch-specific configurations:

Field	Type	Description

Field	Type	Description
`enabled`	boolean	Toggle updates for this branch
`need_pr`	boolean	`false` = direct commits, `true` = create PRs
`pre_release`