How-To Create a New Application Repository

This page explains how to create a new app-* repository using the GitHub template repository. The template provides all standard files and CI configuration pre-configured across both the snapshot and master branches, so teams only need to customize application-specific values. For an overview of the repository structure and CI system, see Working with Application Repositories.

Prerequisites

Access to the folio-org GitHub organization
Your GitHub team slug (e.g., erm, spitfire, acquisitions)
List of backend modules (mod-*) for the application
List of UI modules (folio_*) for the application (if any)
Known dependencies on other applications (app-*)
Coordination with the CI/CD infrastructure team for repository setup

Step 1: Create Repository from Template

There are several ways to create a new repository from the template. All methods lead to the same result — choose whichever is most convenient.

Option A: From the template repository page

Navigate to the template repository: folio-org/folio-app-template
Click “Use this template” → “Create a new repository”

Set Owner to folio-org
Set Repository name to app-{name} (e.g., app-agreements, app-bulk-edit)
Important: Check “Include all branches” — this copies both the snapshot and master branches into the new repository. Without this, only the default branch is copied.
Choose visability “Public”
Click “Create repository”

Option B: From the new repository page

Click “+” → “New repository” in the GitHub header (or navigate to github.com/new)
Under “Repository template”, select folio-org/folio-app-template

Set Owner to folio-org
Set Repository name to app-{name}
Important: Check “Include all branches”
Choose visability “Public”
Click “Create repository”

Option C: Using GitHub CLI

gh repo create folio-org/app-{name} --template folio-org/folio-app-template --include-all-branches --public --clone

The --include-all-branches flag is the CLI equivalent of the “Include all branches” checkbox.

Clone the repository

If you used Option A or B, clone the new repository:

git clone git@github.com:folio-org/app-{name}.git
cd app-{name}

If you used Option C with --clone, the repository is already cloned.

Step 2: Configure the `snapshot` Branch

git checkout snapshot

Edit `pom.xml`

Replace the placeholder values:

Placeholder	Replace with	Example

Placeholder	Replace with	Example
`__APPNAME__`	Application name without `app-` prefix	`agreements`
`__APP_DESCRIPTION__`	Brief description	`Application descriptor for the FOLIO Agreements application`

The placeholders appear in <artifactId>, <description>, and <project.name>. Do not change any other fields — the Maven plugin configuration, repository URLs, and SCM section must stay as-is.

Edit `application.template.json`

Replace the placeholder module entries with your actual application composition. On the snapshot branch, modules use "version": "latest" and "preRelease": "only" to resolve the newest pre-release builds:

{
  "name": "${project.name}",
  "version": "${project.version}",
  "description": "${project.description}",
  "dependencies": [
    {
      "name": "app-platform-complete",       // Required application dependency
      "version": "^3.0.0-SNAPSHOT",          // Constraint with -SNAPSHOT suffix
      "preRelease": "only"                   // Match pre-release dependencies only
    }
  ],
  "modules": [
    {
      "name": "mod-my-backend",              // Backend module name
      "version": "latest",                   // Any available version
      "preRelease": "only"                   // Pre-release builds only
    }
  ],
  "uiModules": [
    {
      "name": "folio_my-frontend",           // Frontend module name
      "version": "latest",
      "preRelease": "only"
    }
  ]
}

Key points:

name, version, description use Maven variable substitution — do not hardcode them
Remove the dependencies array entirely if your application has no dependencies
Remove the uiModules array if your application has no UI modules
Dependency version constraints use -SNAPSHOT suffix on the snapshot branch (e.g., ^1.0.0-SNAPSHOT)
For the full version constraint reference, see Understanding Application Repository Files — Version Constraints

Edit `README.md`

Replace __APPNAME__ and __APP_DESCRIPTION__. Update the module tables with your actual module names.

Commit and push

git add pom.xml application.template.json README.md
git commit -m "Configure app-{name} for snapshot branch"
git push

Step 3: Configure the `master` Branch

git checkout master

Edit `pom.xml` and `README.md`

Same __APPNAME__ and __APP_DESCRIPTION__ replacements as the snapshot branch.

Edit `application.template.json`

Same modules and dependencies as the snapshot branch, but with release-specific version settings. On the master branch, modules use semver constraints and "preRelease": "false" to resolve stable release versions:

{
  "name": "${project.name}",
  "version": "${project.version}",
  "description": "${project.description}",
  "dependencies": [
    {
      "name": "app-platform-complete",
      "version": "^3.0.0",                  // Caret range, stable only
      "preRelease": "false"
    }
  ],
  "modules": [
    {
      "name": "mod-my-backend",
      "version": "^1.0.0",                  // Caret range constraint
      "preRelease": "false"                  // Release versions only
    }
  ],
  "uiModules": [
    {
      "name": "folio_my-frontend",
      "version": "^1.0.0",
      "preRelease": "false"
    }
  ]
}

Edit `.github/update-config.yml`

Replace __TEAM_NAME__ with your GitHub team slug in the pr_reviewers section:

  pr_reviewers:
    - folio-org/your-infra-team
    - folio-org/your-team-name               # Replace with your team slug

The enabled field is set to false by default. Do not change it until the CI/CD infrastructure team completes infrastructure setup (Step 4).

Edit `.github/CODEOWNERS`

Replace __TEAM_NAME__ with your GitHub team slug:

* @folio-org/your-team-name

Commit and push

git add pom.xml application.template.json README.md .github/update-config.yml .github/CODEOWNERS
git commit -m "Configure app-{name} for master branch"
git push

Step 4: Request Infrastructure Setup

Contact the CI/CD infrastructure team to configure the repository:

Set snapshot as the default branch
Configure branch rulesets (required checks, merge queue)
Set up GitHub App integration (EUREKA_CI_APP_ID / EUREKA_CI_APP_KEY secrets)
Enable merge queue

Set up Slack notifications: navigate to the repository on GitHub → Settings → Secrets and variables → Actions → Variables. Create the SLACK_NOTIF_CHANNEL variable with your team’s Slack channel ID. For more details, see the Slack Notifications section in Working with Application Repositories.

Step 5: Enable Automated Updates

Once the CI/CD infrastructure team confirms infrastructure setup is complete:

On the master branch, edit .github/update-config.yml
Change enabled: false to enabled: true
Commit and push the change

The update scheduler runs every 20 minutes and will automatically resolve module versions, generate application.lock.json, and publish the application descriptor to FAR. For details on how the automated update cycle works, see How-To Release Application Updates.

Step 6: Request Platform Inclusion

If this is a new application that needs to be included in FOLIO environments:

Request inclusion in the snapshot environment build cycle — see Environment Inclusion Instructions
Coordinate with the CI/CD infrastructure team for platform-lsp/platform-descriptor.json updates

Step 7: Clean Up

Delete the SETUP.md file from the master branch — it is only needed during initial setup.

Placeholder Reference

Placeholder	Branch(es)	Files	Description	Example

Placeholder	Branch(es)	Files	Description	Example
`__APPNAME__`	both	pom.xml, README.md	Application name without `app-` prefix	`agreements`
`__APP_DESCRIPTION__`	both	pom.xml, README.md	Human-readable description	`Application descriptor for the FOLIO Agreements application`
`__TEAM_NAME__`	master	update-config.yml, CODEOWNERS	GitHub organization team slug	`erm`
`__DEPENDENCY_APP_NAME__`	both	application.template.json	Dependency application name	`app-platform-complete`
`__^SEMVER__`	both	application.template.json	Semver version constraint	`^1.0.0` (master) or `^1.0.0-SNAPSHOT` (snapshot)
`__MODULE_NAME__`	both	application.template.json	Backend module name	`mod-agreements`
`__UI_MODULE_NAME__`	both	application.template.json	Frontend module name	`folio_agreements`

Verification Checklist

After completing all steps:

Check GitHub Actions — the update-scheduler workflow should trigger within 20 minutes on the snapshot branch
Verify application.lock.json — the CI should generate this file with resolved module versions
Check FAR — the application descriptor should be published to https://folio-registry.dev.folio.org
Verify CI status — the eureka-ci / validate-application check should pass
Verify Slack notifications — notifications should arrive in your team channel after the first successful update

Troubleshooting

Problem	Possible Cause	Resolution

Problem	Possible Cause	Resolution
Only one branch exists after creating from template	“Include all branches” was not checked	Create the missing branch manually by copying the template’s branch content, or re-create the repository with the checkbox enabled
Update scheduler not running	`enabled: false` in update-config.yml	Complete infrastructure setup (Step 4) first, then enable updates (Step 5)
Scheduler runs but no modules resolved	Placeholder module names still in template	Replace `__MODULE_NAME__` and `__UI_MODULE_NAME__` with actual module names in application.template.json
CI validation failing — module not found	Module name is incorrect or not published	Verify the module name exists in the FOLIO Module Registry. Module names are case-sensitive
CI validation failing — dependency not found	Dependent application not yet published to FAR	Wait for the dependent application to complete its update cycle, or verify the dependency name and version constraint
Merge queue not working	Branch ruleset not configured	Verify the CI/CD infrastructure team has completed infrastructure setup. Check Settings → Rules for the branch ruleset
Slack notification not received	`SLACK_NOTIF_CHANNEL` not set or incorrect	Check the repository variable in Settings → Secrets and variables → Actions → Variables. If the variable is correct, request assistance in `#folio-rancher-support`

Related Pages

Working with Application Repositories — overview of repository structure and CI system
Understanding Application Repository Files — field-by-field reference for all repository files
How-To Adding, Removing, or Moving Modules — modify the application’s module composition
How-To Release Application Updates — the automated PR flow for release branches
How-To Create Application Release Branch — creating release branches

How-To Create a New Application Repository

Prerequisites

Step 1: Create Repository from Template

Option A: From the template repository page

Option B: From the new repository page

Option C: Using GitHub CLI

Clone the repository

Step 2: Configure the snapshot Branch

Edit pom.xml

Edit application.template.json

Edit README.md

Commit and push

Step 3: Configure the master Branch

Edit pom.xml and README.md

Edit application.template.json

Edit .github/update-config.yml

Edit .github/CODEOWNERS

Commit and push

Step 4: Request Infrastructure Setup

Step 5: Enable Automated Updates

Step 6: Request Platform Inclusion

Step 7: Clean Up

Placeholder Reference

Verification Checklist

Troubleshooting

Related Pages

Step 2: Configure the `snapshot` Branch

Edit `pom.xml`

Edit `application.template.json`

Edit `README.md`

Step 3: Configure the `master` Branch

Edit `pom.xml` and `README.md`

Edit `application.template.json`

Edit `.github/update-config.yml`

Edit `.github/CODEOWNERS`