Branch Ruleset Automation

This page describes how branch rulesets are automatically created and managed for release branches in FOLIO Eureka application repositories.

Purpose

Branch rulesets enforce CI validation and merge queue requirements on release branches. They ensure that every change to a release branch passes the eureka-ci / validate-application check and is processed through the merge queue before merging.

Rulesets are configured declaratively in update-config.yml and applied automatically by the branch-ruleset-automation workflow in the kitfox-github repository. Application maintainers do not need to configure GitHub branch protection rules manually.

What a Branch Ruleset Enforces

Each release branch ruleset applies three types of protection:

Required status checks — the check eureka-ci / validate-application must pass before a pull request can be merged. This check validates module interface integrity and dependencies integrity.

Merge queue — pull requests are queued and squash-merged only after all checks pass. The merge queue uses the ALLGREEN grouping strategy, meaning all queued PRs must pass checks together. This prevents incompatible changes from being merged simultaneously.

Bypass actors — the Eureka CI GitHub Application is configured as a bypass actor with always bypass mode. This allows the CI system to push automated commits (such as version updates on pre-release branches) without triggering the ruleset checks.

How Rulesets Are Applied

The ruleset automation follows this sequence:

1. Configuration update — during release preparation (or when a branch configuration is manually added), the update-config.yml file on the default branch is updated with a ruleset section for the new branch. The ruleset section includes the required checks, merge queue settings, and bypass actor configuration.

2. Webhook trigger — the push to the default branch that updates update-config.yml triggers the Eureka CI GitHub Application webhook. The webhook detects that the configuration file was modified and dispatches the branch-ruleset-automation.yml workflow in kitfox-github.

3. Matrix preparation — the automation reads update-config.yml from the target repository, extracts the branch configurations, and builds a matrix of branches that need ruleset updates. Each branch entry includes the enforcement level (active or disabled based on ruleset.enabled).

4. Ruleset creation or update — for each branch in the matrix, the branch-ruleset-management action:

   • Checks whether the branch exists in the repository

   • Searches for an existing ruleset matching the naming pattern (e.g., R1-2025-eureka-ci)

   • If the ruleset exists — updates it with the current configuration

   • If the ruleset does not exist — creates a new one

   • Configures required_status_checks, merge_queue, and bypass_actors rules based on the values in update-config.yml

5. Notification — a Slack notification is sent to the team channel (from the SLACK_NOTIF_CHANNEL repository variable) and the general notification channel, reporting the ruleset ID, enforcement status, and a link to the workflow run.

Open

Open

Ruleset Naming Convention

Each ruleset follows the naming pattern {branch}-eureka-ci, where {branch} is the release branch name. For example:

• Branch R1-2025 → ruleset R1-2025-eureka-ci

• Branch R2-2025 → ruleset R2-2025-eureka-ci

The naming pattern is configurable via the ruleset.pattern field in update-config.yml (default: "{0}-eureka-ci").

Ruleset Configuration in update-config.yml

The ruleset section in update-config.yml controls all ruleset behavior. Here is a summary of the configuration fields:

Individual branches can override the global ruleset.enabled setting via a per-branch ruleset.enabled field. Typically, rulesets are disabled for the pre-release branch (e.g., snapshot) and enabled for release branches.

For the complete field reference with types and defaults, see Understanding Application Repository Files — ruleset Section.

Viewing and Verifying Rulesets

To verify that a ruleset has been applied correctly:

1. Navigate to the application repository on GitHub

2. Open Settings → Rules → Repository rules

3. Locate the ruleset named {branch}-eureka-ci (e.g., R1-2025-eureka-ci)

4. Expand the ruleset to verify:

   • The target branch pattern matches the release branch

   • Required status checks include eureka-ci / validate-application

   • Merge queue is enabled with the expected settings

   • The Eureka CI GitHub Application appears as a bypass actor

Open

Open

Open

When Rulesets Are Updated

Rulesets are updated automatically in the following situations:

• Release preparation — when a new release branch is created, the automation adds the branch configuration to update-config.yml, and the ruleset is created

• Configuration changes — when the ruleset section in update-config.yml is modified on the default branch (e.g., changing the merge method or adding a required check), the webhook triggers an update to all affected rulesets

• Manual re-trigger — the branch-ruleset-automation.yml workflow can be dispatched manually if a ruleset needs to be re-applied

Troubleshooting

Related Pages

• Understanding Application Repository Files — ruleset Section — complete field reference for ruleset configuration

• Managing Release Branch Updates — Merge Queue — how the merge queue processes PRs

• Creating a Release Branch — release preparation, which triggers ruleset creation