keycloak-nordix-maintenance

Files (1)

• SKILL.md

SKILL.md (first lines)

# Keycloak Nordix Release Skill

This skill handles the complete workflow for creating and maintaining nordix fork release branches of Keycloak, including backporting features, security fixes, and managing version control.

## When to Use This Skill

- **Creating new nordix release branches** for new upstream Keycloak versions (e.g., 26.2.14-nordix from 26.2.14 base)
- **Backporting features** from previous nordix release branches to newer
- **Backporting security fixes** and CVEs from newer upstream Keycloak versions to older nordix branches
- **Cherry-picking** commits while managing merge conflicts
- **Version tagging** and tracking nordix releases
- **Evaluating** which backports are needed vs. already in base release

## Prerequisites

- Access to Keycloak repository with nordix remote and upstream as origin configured

## Key Concepts

### Nordix Branching Pattern

Nordix maintains forked branches for specific Keycloak versions with strategic backports:

- **Base releases**: Official Keycloak versions (e.g., `26.2.14`)
- **Nordix branches**: Fork branches with additional features/fixes (e.g., `26.2.14-nordix`)
- **Version tags**: Track patch releases (e.g., `26.2.14-nordix-1`, `26.2.14-nordix-2`)

## Step-by-Step Workflow

### Phase 0: Preparation

1. **Fetch latest branches and tags** from both remotes
   ```bash
   git fetch nordix --tags --force
   git fetch origin --tags --force
   ```

### Phase 1: Planning & Analysis

1. **Identify versions** - ALWAYS execute this step first, before asking user for input
   - If user provided version in advance:
     1. Verify it exists in upstream releases: `git tag -l | grep "^{version}$"`
     2. Verify it does not have nordix release yet: `git tag -l | grep "^{version}-nordix-"`
     3. Proceed to step 2 if both checks pass
   - If user did not provide version:
     1. Execute version discovery command:
        ```bash
        echo "=== Upstream releases (latest 15) ===" && git tag -l --sort=-creatordate | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | head -15 && echo -e "\n=== Nordix releases (latest 15) ===" && git tag -l --sort=-creatordate | grep -E '^[0-9]+\.[0-9]+\.[0-9]+-nordix-[0-9]+$' | head -15
        ```
     2. Analyze results to find candidates:
        - Extract all upstream versions from the list (e.g., 26.5.5, 26.4.10, 26.2.14, 26.5.4, ...)
        - Extract all nordix versions from the list (e.g., 26.2.13-nordix-1, 26.5.2-nordix-1, ...)
        - For each upstream version, extract its major.minor part (e.g., 26.5 from 26.5.5)
        - Group upstream versions by major.minor series
        - For each series, find the highest patch version (latest in that series)
        - For each latest version in a series, check if ANY nordix release exists for that version (e.g., check if 26.5.5-nordix-* exists in nordix releases)
        - Keep only those latest versions that have NO nordix release yet
        - Sort these candidates by version descending (newest first)
     3. Present candidates using this template:
        ```
        Available candidates for new nordix fork:
        1) {latest-version-in-series-1} (latest in {series-1}, no nordix release yet)
        2) {latest-version-in-series-2} (latest in {series-2}, no nordix release yet)
        ...

        Select version number (1-N) or provide custom version:
        ```
     4. Wait for user to pick one of the suggested versions or provide their own

2. **Compare versions** - Check what changed between base versions and identify backports needed from previous nordix
   ```bash
    echo "=== Changes between {old-base} and {new-base} ===" && git --no-pager log {old-base}..{new-base} --oneline && echo -e "\n=== Backports in {old-nordix} (from {old-base}) ===" && git --no-pager log {old-base}..{old-nordix} --oneline
   ```

3. **Check if any are already in the new base release**
   - Note which commits are already in the new base release (these will be omitted when creating the new nordix branch)

4. **Summarize findings**
   - Create a list of commits to cherry-pick, with commit id and description.
   - **IMPORTANT**: Reverse the order from git log output (oldest first for cherry-picking)

### Phase 2: Branch Creation

1. **Create new branch** from target base version tag
   ```bash
   git checkout -b {version}-nordix {version}
   git --no-pager log --oneline -3  # Verify
   ```

### Phase 3: Cherry-pick Backports

1. **Cherry-pick backports**
   ```bash
   git cherry-pick <commit1> <commit2> <commit3> ...
   ```
   - IMPORTANT: the commits must be in chronological order (oldest first)
   - NOTE: `git log` output is in reverse chronological order (newest first), so reverse the list from git log output when cherry-picking
   - Resolve any conflicts that arise (see Common Scenarios: Conflict Resolution)

### Phase 4: Backport Specific Fixes

This phase applies to any explicit backport request: a CVE/security fix, a commit hash given directly, or any other targeted patch.

1. **Locate the commit** to backport
   - If a commit hash is given directly, proceed directly to step 2
   - If a CVE ID is given, find the fix commit using these methods in order:

   **Method 1: Search GitHub advisories by CVE ID**
   ```bash
   gh api "advisories?cve_id={CVE-XXXX-XXXXX}"
   ```
   If results are returned, extract the commit ID from the advisory data.

   **Method 2: Search commit messages for CVE ID**
   ```bash
   git --no-pager log --all --oneline --grep="CVE-XXXX-XXXXX" origin/main
   ```

   **Method 3: Search upstream release notes**

From tsaarni/agent-skills, Apache-2.0.

More from tsaarni/agent-skills