How-To Create Application Release Branch

This page provides step-by-step instructions for running the release preparation workflows that create release branches for FOLIO Eureka applications.

Purpose

Release preparation workflows automate the creation of release branches across application repositories. There are two levels of execution:

Platform-wide release preparation — the platform repository maintainer triggers a single orchestrator workflow in platform-lsp that processes all applications in parallel. This is the standard approach for regular release cycles (e.g., Sunflower, Tulip)
Single-application release preparation — an application maintainer or the platform repository maintainer triggers the workflow directly in one application repository. This is used for adding new applications mid-release or re-creating a branch after issues

For a detailed explanation of what the automation does during release preparation, see Creating a Release Branch.

When to Use Each Mode

Scenario	Recommended Mode

Scenario	Recommended Mode
Regular platform release cycle (e.g., Sunflower → Tulip)	Platform-wide orchestrator
New application being added to an existing release	Single-application
Re-creating a branch after a failed preparation	Single-application
Application not included in the platform but needs its own release branch	Single-application
Testing release preparation with `dry_run` for one application	Single-application
Testing release preparation with `dry_run` for the full platform	Platform-wide orchestrator with `dry_run: true`

Platform-Wide Release Preparation

This section describes how to run the release-preparation-orchestrator.yml workflow in the platform-lsp repository.

Step 1: Navigate to GitHub Actions

Open the platform-lsp GitHub Actions page and select the Release preparation orchestrator workflow from the left sidebar.

Step 2: Open the Run Workflow Dialog

Click the Run workflow button on the right side of the workflow page.

Step 3: Fill Input Parameters

The dialog presents the following input parameters:

Parameter	Required	Description	Example

Parameter	Required	Description	Example
`previous_release_branch`	Yes	The source release branch that serves as the baseline for the new release. The orchestrator reads this branch's `platform-descriptor.json` to determine which applications to process	`R1-2025`
`new_release_branch`	Yes	The name of the release branch to create across all application repositories and in `platform-lsp` itself	`R2-2025`
`new_applications`	No	Comma-separated list of application repositories to include that were not part of the previous release. These are processed alongside the existing applications	`app-new-feature`
`use_snapshot_fallback`	No	When enabled, if the `previous_release_branch` does not exist in an application repository, the workflow falls back to the default pre-release branch as the source	`false`
`use_snapshot_version`	No	When enabled, uses the pre-release branch version (rather than the previous release branch version) as the base for version increment	`false`
`branch_name`	No	Display name for the release, used in platform metadata and notifications	`FOLIO Tulip Release`
`branch_description`	No	Description text for the release branch metadata	(default provided by workflow)
`need_pr`	No	Whether the new release branches should require pull requests for module version updates. Almost always `true` for release branches	`true`
`prerelease_mode`	No	Module version filter for the new branches: `"false"` (stable releases only), `"true"` (both), or `"only"` (pre-release only). Standard release branches use `"false"`	`false`
`dry_run`	No	Simulates the entire orchestration without making any actual changes. Useful for verifying parameters before a real run	`false`

Step 4: Execute the Workflow

Click the green Run workflow button at the bottom of the dialog.

Step 5: Monitor Execution

The orchestrator runs in sequential phases. Each phase must complete before the next begins:

Authorize — verifies the identity of the user who triggered the run (see Authorization Process below)
Initial check — extracts the application list from the previous release's platform-descriptor.json and merges with any new_applications
Check applications — performs a dry-run validation for all applications in parallel to detect issues before making changes
Update applications — creates the release branch in each application repository (parallel execution across all applications)
Collect results — aggregates the results from all application preparations
Prepare platform template — updates platform.template.json with ^VERSION constraints for all applications
Update platform config — adds the new branch configuration to platform-lsp's update-config.yml
Commit platform changes — creates the release branch in platform-lsp with the updated template
Commit platform config — commits the config changes to the default branch
Slack notification — sends a notification announcing the new release

The entire process typically takes 10–20 minutes depending on the number of applications.

Authorization Process

The workflow verifies the identity of the user who triggered the run through a two-path process:

Path 1 — Authorized team member: If the initiator is a member of the authorized GitHub team (configured for the organization), the workflow proceeds immediately without any manual intervention.

Path 2 — Non-team member: If the initiator is not a member of the authorized team, the workflow pauses at an Environment approval gate. A yellow "Waiting" badge appears on the workflow run. The run remains paused until a member of the authorized team navigates to the workflow run in GitHub Actions and clicks Approve in the Environment approval dialog. If the run is rejected or not approved within the timeout period, the workflow terminates.

What Happens If a Single Application Fails

The orchestrator includes a pre-check phase (step 3 above) that performs a dry-run validation for all applications before making any actual changes. This catches most issues — such as missing source branches or version conflicts — before branch creation begins. Individual application failures during the actual creation phase are rare edge cases. When they do occur, the failed application is marked in the results but the orchestrator continues processing all other applications. Failed applications can be re-processed individually using the single-application workflow described below.

Single-Application Release Preparation

This section describes how to run the release-preparation.yml workflow in an individual application repository.

Step 1: Navigate to GitHub Actions

Open the GitHub Actions page for the target application repository (e.g., https://github.com/folio-org/app-acquisitions/actions) and select the Release preparation workflow from the left sidebar.

Step 2: Open the Run Workflow Dialog

Click the Run workflow button on the right side of the workflow page.

Step 3: Fill Input Parameters

Parameter	Required	Description

Parameter	Required	Description
`previous_release_branch`	Yes	Source release branch to base the new branch on (e.g., `R1-2025`)
`new_release_branch`	Yes	Name of the release branch to create (e.g., `R2-2025`)
`use_snapshot_fallback`	No	Fall back to the pre-release branch if the previous release branch does not exist in this repository
`use_snapshot_version`	No	Use the pre-release branch version as the base for version increment
`need_pr`	No	Whether the new branch should require PRs for updates (default: `true`)
`prerelease_mode`	No	Module version filter: `"false"` (default), `"true"`, or `"only"`
`dry_run`	No	Simulate without making changes

Step 4: Execute and Monitor

Click the green Run workflow button. The workflow completes in approximately 2–5 minutes for a single application. The workflow log shows each step: source branch resolution, version increment, template update, branch creation, and config update.

Troubleshooting

Problem	Possible Cause	Resolution

Problem	Possible Cause	Resolution
Workflow does not appear in the Actions list	Workflow file missing or disabled	Verify `.github/workflows/release-preparation.yml` exists in the repository. Check the Actions settings for disabled workflows
"Branch already exists" error	The target release branch already exists in the repository	Delete the existing branch first (if safe) or choose a different branch name
Workflow paused at "Authorize" step	Initiator is not a member of the authorized team	A member of the authorized team must navigate to the workflow run and click "Approve" in the Environment approval dialog
Version increment produces unexpected result	Fallback to pre-release branch with different version	Review the Version Increment Logic section. Consider using `use_snapshot_version` parameter
Orchestrator fails at "Check applications"	One or more applications cannot be validated	Review the failed job logs. Fix the issue in the affected repository and re-run, or exclude the application and process it separately
Slack notification not received	Notification channel misconfigured	Check the `SLACK_NOTIF_CHANNEL` repository variable in the application repository's Settings → Secrets and variables → Actions → Variables. If it is missing or incorrect, update it with the correct Slack channel ID. If the variable is correct, request assistance in the `#folio-rancher-support` Slack channel

Related Pages

Creating a Release Branch — what the automation does during release preparation
Releasing Applications on a Release Branch — managing the application after the branch is created
Understanding Application Repository Files — Workflow Files — detailed reference for both CI workflows