kotlin-update-release

name	kotlin_update_release
description	Integrates Kotlin version updates from Renovate and orchestrates release workflows via GitHub Actions. Triggers when updating Kotlin version, releasing a new version, or integrating Renovate PRs.
metadata	{"author":"rnett","version":"1.0"}

Kotlin Update & Release Workflow

A skill for integrating Kotlin updates from Renovate and releasing new versions via GitHub Actions.

Constitution (Critical Rules)

• NEVER commit directly to local main. All work must be done on the renovate branch, merged via GitHub PRs.
• NEVER push to main without going through the PR process for code changes. Version bumps and snapshot updates are the only exceptions.
• ALWAYS verify CI passes on the PR before merging.
• ALWAYS follow the exact commit message conventions from past releases (see Workflow step 5 and 8).
• ALWAYS ensure version.txt has no trailing newline and no UTF-8 BOM when writing it.
• DO NOT add co-author trailers to commits unless explicitly requested.

Prerequisites

• gh CLI authenticated with repo access
• Git configured with correct identity
• Push access to the repository (may need admin bypass for branch protection)

Workflow

1. Identify the Kotlin Update PR

# List open PRs from Renovate
gh pr list --state open --author renovate

# Check specifically for Kotlin PRs
gh pr list --head kotlin-update/kotlin --state open
gh pr list --head renovate/kotlin-monorepo --state open

There are typically two Kotlin update PRs:

• kotlin-update/kotlin — created by the custom branchPrefix in renovate.json. This is a draft PR with automerge disabled.
• renovate/kotlin-monorepo — created by Renovate's default behavior. This is an open (non-draft) PR with automerge enabled.

Use renovate/kotlin-monorepo (the non-draft one) as the primary PR for merging. Close the other after merging.

2. Check CI Status

gh pr checks <PR-NUMBER>

If CI passes, skip to step 5. If CI fails, continue to step 3.

3. Fix Build Failures on the Renovate Branch

Checkout the branch locally, fix the issues, and push back:

# Create a local branch from the remote
git checkout -b fix/kotlin-update origin/renovate/kotlin-monorepo

# Fix the build issues (see Common Breaking Changes below)
# ... make changes ...

# Verify locally — use the Gradle MCP `gradle` tool with commandLine: ["build"] to verify the build.

# Commit and push back to the PR branch
git add <changed-files>
git commit -m "<descriptive fix message>"
git push origin fix/kotlin-update:renovate/kotlin-monorepo

# Clean up - switch back to main
git checkout main
git branch -D fix/kotlin-update

4. Wait for CI to Pass

# Poll until CI completes (typically 3-5 minutes)
Start-Sleep -Seconds 120
gh pr checks <PR-NUMBER>

Repeat until CI shows pass.

5. Merge the PR via GitHub

# Merge with admin bypass if branch protection blocks
gh pr merge <PR-NUMBER> --merge --admin

# Close the duplicate draft PR
gh pr close <DRAFT-PR-NUMBER>

6. Pull Changes to Local Main

git checkout main
git pull origin main

7. Prep for Release

Update version.txt from X.Y.Z-SNAPSHOT to X.Y.Z:

[System.IO.File]::WriteAllText(
        (Join-Path $PWD "version.txt"),
        "X.Y.Z",
        (New-Object System.Text.UTF8Encoding($false))
)

git add version.txt
git commit -m "Prep for X.Y.Z release"
git push origin main

8. Trigger the Release Workflow

gh workflow run release.yaml

The release workflow will:

1. Run CI (build + test)
2. Verify version is NOT a SNAPSHOT (fails if it is)
3. Publish to Maven Central via publishAndReleaseToMavenCentral
4. Create a GitHub Release with auto-generated notes
5. Deploy docs to GitHub Pages

9. Wait for Release to Complete

# Get the run ID from the output of `gh workflow run`
# Or find it:
gh run list --workflow=release.yaml --limit 3

# Monitor the run
gh run view <RUN-ID> --json status,conclusion

Wait until conclusion is success. This typically takes 5-8 minutes.

10. Verify the Release

gh release list --limit 3
# Should show the new version as "Latest"

11. Bump to Next Snapshot

[System.IO.File]::WriteAllText(
        (Join-Path $PWD "version.txt"),
        "X.Y.(Z+1)-SNAPSHOT",
        (New-Object System.Text.UTF8Encoding($false))
)

git add version.txt
git commit -m "Bump version to X.Y.(Z+1)-SNAPSHOT"
git push origin main

Common Breaking Changes

abiValidation API (Kotlin 2.4.0+)

Error: 'val enabled: Property<Boolean>' is deprecated. Property was removed, to enable ABI validation call function abiValidation().

Fix in buildSrc/src/main/kotlin/build/public-abi.gradle.kts:

• Replace extensionIfPresent<AbiValidationExtension> { enabled = true } with abiValidation()
• Remove the unused import org.jetbrains.kotlin.gradle.dsl.abi.AbiValidationExtension
• Keep @OptIn(ExperimentalAbiValidation::class)

TestConfigurationBuilder Renamed (Kotlin 2.4.0+)

Error: cannot find symbol: class TestConfigurationBuilder in generated test files.

Fix: org.jetbrains.kotlin.test.builders.TestConfigurationBuilder was renamed to NonGroupingPhaseTestConfigurationBuilder. Update all references in:

• test-support/src/main/kotlin/.../generation/ — generation templates and builders
• test-support/src/main/kotlin/.../tests/ — abstract test base classes
• Regenerate test files by running the build (they are auto-generated from templates)

Project Configuration

• Version file: version.txt (single source of truth, read by CI and release workflows)
• Kotlin version: gradle/libs.versions.toml → [versions] kotlin = "X.Y.Z"
• Release workflow: .github/workflows/release.yaml (manual workflow_dispatch trigger)
• CI workflow: .github/workflows/ci.yaml (runs on push and workflow_call)
• Renovate config: renovate.json — Kotlin PRs are draft + no automerge, custom branchPrefix: "kotlin-update/"

Push Restrictions

This repository has a server-side pre-receive hook that rejects commits with timestamps before 4:00 PM on weekdays. If pushing fails with a "forbidden timestamp" error:

• Wait until after 4:00 PM local time to push, OR
• Amend commit dates: git rebase HEAD~N --exec "git commit --amend --no-edit --date=now" (for N unpushed commits)