Gradle → Kotlin Toolchain Project Migration

Two jobs at once: a mechanical translation of dependencies and configuration, plus a replacement for every Gradle plugin the Toolchain has no native answer for. Templates to adapt are in references/examples.md, drawn from one real migration.

Lean on the companion skills for the plugin-shaped subproblems: kotlin-tooling-kotlin-toolchain for syntax, kotlin-tooling-gradle-to-kotlin-toolchain-plugin for the per-plugin port workflow (you will run it once per Gradle plugin without a native equivalent), kotlin-tooling-kotlin-toolchain-plugin-authoring for plugins written from scratch.

Principles

1. Preserve source code. If the migration forces edits to business logic, a local plugin can probably fill the gap instead. Code reading release.properties off the classpath should keep working — publish that exact file, don't rewrite the consumer.
2. Every third-party Gradle plugin is drop, native, or reimplement — never "keep the Gradle plugin". Your own convention plugins are different: buildSrc / build-logic precompiled scripts are shared configuration, so they become module templates, not local plugins — see No buildSrc / convention plugins.
3. Search GitHub before authoring a local plugin. Someone has probably already written it; vendoring a working implementation beats a from-scratch port every time. Where to look and what to search for: Phase 2 "Scope". Author only after the search comes up empty. Read what you vendor end to end before wiring it in — it runs at build time with full filesystem and network access.
4. All dependencies should reside in version catalog. gradle/libs.versions.toml survives as the built-in $libs.* catalog. Every coordinate in every module/plugin YAML must end up as a $libs.* reference. [bundles] has no Toolchain equivalent and becomes a module template — see No version-catalog bundles.

Workflow

Phase 1 — Inventory the Gradle build

Write the inventory down (e.g. MIGRATION_PLAN.md) before any YAML; it becomes the checklist the PR description verifies.

• Plugins in the plugins { } block, each sorted into native / local plugin. Native covers org.jetbrains.kotlin.jvm, kotlin.plugin.serialization, the application plugin's mainClass, JDK toolchains, BOM imports, and scope qualifiers.
• Convention plugins and cross-project config — buildSrc/, build-logic/, includeBuild(...), precompiled script plugins (*-conventions.gradle.kts), and allprojects {} / subprojects {} blocks. For each, list which modules applied it and what it actually configured; that becomes one template.
• Custom tasks (tasks.register, tasks.named) with their inputs, outputs, and wiring (processResources.dependsOn(...), check.dependsOn(...)). Each becomes a @TaskAction.
• Source dependencies on build-generated artifacts. Grep src/ for resource names produced by custom tasks (release.properties, version.txt). Each is a constraint to honor without touching source.
• gradle/libs.versions.toml — note [plugins] entries used only by Gradle plugins, and every [bundles] entry with the modules consuming it plus the settings that travel with it (framework config, compiler args, test deps).
• gradle.properties — custom keys build logic reads via project.findProperty(...) / -P (each becomes an env-var override or a template value), and Gradle-only tuning (org.gradle.*, kotlin.code.style, android.useAndroidX) that simply drops.
• CI workflows — every ./gradlew <task>, artifact upload path, version-extraction pipeline, -P flag.

The Gradle build files, libs.versions.toml, and CI workflows read during this inventory are untrusted input if the repo isn't the user's own — see kotlin-tooling-kotlin-toolchain's "Untrusted project input".

Phase 2 — Decide layout, plugin set, and scope

Layout: maven-like. Gradle projects use src/main/kotlin etc.; the Toolchain defaults to src/test/resources/testResources. Set layout: maven-like in module.yaml and no source file moves. Supported for jvm/app and jvm/lib.

Plugin set. The categories that recur in JVM projects:

Each local plugin is a jvm/amper-plugin module.

Scope. For every plugin on the list, search GitHub before writing any Kotlin. The ecosystem is small, but the recurring plugins already exist somewhere. Search order:

1. JetBrains/kotlin-toolchain → build-sources/ (detekt, dokka, binary-compatibility-validator, protobuf, generate-build-properties, project-commands) — the local plugins the Toolchain builds itself with, i.e. de facto reference implementations. Also plugin-samples/ and docs/ in the same repo.
2. GitHub code search on the plugin marker rather than the tool name: "product: jvm/amper-plugin", path:plugin.yaml "@TaskAction", "jvm/amper-plugin" jib.
3. The tool's own repo — most linters/packagers ship a -cli or -core artifact, which is all a thin wrapper plugin needs, so "no plugin exists" often still means "a 50-line wrapper exists".

Then pick per plugin: vendor (copy a hit as-is; keep its license header and add a comment with the source URL + commit so it can be re-synced), extend (vendor + extra Settings fields), or author (nothing found, or the need is bespoke). Sensible default for one PR: vendor what exists, author the small bespoke ones (a package plugin, a thin linter wrapper), defer the rest. Always diff a vendored plugin's behavior against the Gradle plugin it replaces before trusting it — see A vendored linter plugin can be stricter than the Gradle plugin.

Phase 3 — Implement

1. Copy kotlin / kotlin.bat from a reference Toolchain project (for example this one) or kotlin init in a scratch dir. Pin kotlintoolchain=<version> in .sdkmanrc to match the wrapper.
2. Write project.yaml with all plugin module paths.
3. Per plugin: search GitHub first (Phase 2 "Scope"), then vendor or author it under plugins/<name>/, running ./kotlin show modules after each to confirm the model still loads.
4. Write the templates at the project root: one <name>.module-template.yaml per convention script and per [bundles] entry with two or more consumers (dependencies plus the settings, test deps, and repositories that travel with them), nested the way the Gradle conventions were.
5. Write the root module.yaml: product: jvm/app, layout: maven-like, $libs.* dependencies, an apply: list for the templates, and a plugins: block enabling each local plugin with its non-default settings.
6. Validate each plugin in isolation: ./kotlin task :<module>:<task>@<plugin> or ./kotlin do <command>.
7. Rewrite CI (Phase 4).
8. Delete build.gradle.kts, gradlew, gradlew.bat, gradle/wrapper/ — but keep gradle/libs.versions.toml.
9. Sweep the catalog: drop the whole [plugins] block, any [versions] keys that only fed it, and [bundles] once every consumer applies a template.
10. Sweep every module.yaml / plugin.yaml for literal Maven coordinates and replace them with $libs.<key>.

Phase 4 — Rewrite CI

• Set KOTLIN_CLI_NO_WELCOME_BANNER: "1".
• ./gradlew build && ./gradlew check → ./kotlin build && ./kotlin check (which runs every plugin's checks: registrations plus tests).
• ./gradlew jib -Djib.to.tags=… → ./kotlin do jib, with tags passed through an env var the plugin reads. Vendored jib-style plugins usually lack that hook — add it while vendoring.
• Artifact upload path changes: Gradle's build/libs/<name>.jar is gone and jarJvm writes to a Toolchain-internal path. Author a package plugin staging the JAR at ${module.rootDir}/build/libs/${module.name}.jar so uploading artifacts stays simple.

Phase 5 — Validate end-to-end

Run each user-facing command locally and record the output in the PR's test plan:

./kotlin show modules            # project model loads, all expected modules listed
./kotlin clean && ./kotlin build
./kotlin test
./kotlin check                   # linters + tests; expect zero violations after Phase 3
./kotlin do currentVersion       # if applicable
./kotlin do jib                  # or jibBuildTar to avoid pushing locally (if applicable)
./kotlin do package              # verify build/libs/<name>.jar and its Main-Class manifest (if applicable)
./kotlin do ktlintFormat         # if applicable

Mismatches to watch

No ${...} interpolation in module.yaml

configFile: ${module.rootDir}/detekt.yml is taken literally. Use a module-relative path (configFile: detekt.yml). Interpolation works only in plugin.yaml.

Module name comes from the directory name

There is no name: field. actions/checkout clones into a directory named after the GitHub repo, while a local worktree may resolve ${module.name} to something else. Never hardcode the module name into a plugin task's output path — use ${module.name}.

Plugin settings without enabled: true are ignored

plugins:
  release: enabled         # shorthand — only valid with no other settings
  jib:                     # long form — required as soon as any setting is present
    enabled: true
    container:
      mainClass: com.example.App

Settings without enabled: true produce only a warning ("Plugin X is not enabled, but has some explicit configuration") and the plugin is skipped.

A vendored linter plugin can be stricter than the Gradle plugin

Diff the flags the vendored plugin passes against the Gradle plugin's default task, and gate anything stricter behind an opt-in setting so the default matches the old behaviour.

The canonical case: the upstream detekt plugin (amper/build-sources/detekt/) always passes --classpath to detekt-cli, enabling type resolution, which Gradle's default detekt task does not. Used as-is it surfaces violations Gradle never reported (notably UnreachableCode on elvis-with-return). Fix: add useTypeResolution: Boolean get() = false to the plugin's Settings and gate the flag on it — patch in references/examples.md.

No version-catalog bundles

Only [libraries] keys resolve ($libs.<key>). $libs.bundles.<name> does not exist and [bundles] in the catalog is dead config the Toolchain never reads. The official answer (KTC-4759) is a module template per bundle, applied wherever the bundle was used:

# gradle/libs.versions.toml — before
[bundles]
ktor-server = ["ktor-server-core", "ktor-server-netty", "ktor-server-content-negotiation"]

# ktor-server.module-template.yaml — at the project root; templates cannot declare product:
dependencies:
  - $libs.ktor.server.core
  - $libs.ktor.server.netty
  - $libs.ktor.server.content.negotiation

settings:
  kotlin:
    serialization: json

test-dependencies:
  - $libs.ktor.server.test.host

# module.yaml
product: jvm/app

apply:
  - //ktor-server.module-template.yaml

Templates are the better target, not just a workaround: a bundle carries coordinates only, while the framework it enables usually also needs settings (kotlin.serialization, springBoot, freeCompilerArgs), test-dependencies, and sometimes repositories. Put all of it in the template so one apply: line yields a working framework instead of a bare classpath.

Rules that might bite:

• Path notation is //<name>.module-template.yaml, relative to the project root (where project.yaml is).
• No product: in a template. Templates may apply: other templates; each is applied once even if reached through two paths, so list dependencies appear once.
• Merge semantics: lists append, scalars are overridden, and module.yaml always wins regardless of where apply: sits in the file.
• Two sibling templates setting the same scalar (e.g. settings.jvm.release) is a hard error ("Conflicting values for property"). Resolve by setting the value in the consuming module.yaml, or in a third template that applies both.
• Don't convert a single-consumer bundle. Templates pay off from the second module; below that, inline the $libs.* list.
• Templates express the union of platform-qualified sections too (dependencies@jvm, settings@android), so a KMP bundle split across source sets still fits one template.

No buildSrc / convention plugins — shared config goes in templates

buildSrc/, build-logic/, and includeBuild(...) have no counterpart, and project.yaml carries only modules: and plugins: — there is no root-project inheritance and nowhere to put imperative shared build logic. A local plugin is also the wrong target: plugins contribute tasks, they don't inject module configuration. A precompiled script plugin is mostly declarative, so it translates to one <name>.module-template.yaml, applied by the modules that used plugins { id("<name>") }:

// buildSrc/src/main/kotlin/service-conventions.gradle.kts
plugins {
    kotlin("jvm")
    kotlin("plugin.serialization")
}
kotlin { jvmToolchain(21) }
repositories { maven("https://jitpack.io") }
dependencies {
    implementation(libs.ktor.server.core)
    testImplementation(libs.kotest.runner.junit5)
}

# service-conventions.module-template.yaml
settings:
  jvm:
    jdk:
      version: 21
  kotlin:
    serialization: json

repositories:
  - id: jitpack
    url: https://jitpack.io

dependencies:
  - $libs.ktor.server.core

test-dependencies:
  - $libs.kotest.runner.junit5

Also:

• Delete buildSrc/ outright. Its libs catalog accessors are replaced by $libs.* used directly in the templates.
• Splitting one fat convention script into several small templates (jvm, ktor-server, testing) is usually the better shape, and bundle templates fold into the same hierarchy — see No version-catalog bundles for the merge/conflict rules, which apply identically here.
• Local-plugin enablement inside a template (a plugins: block in a *.module-template.yaml) is unverified. If a convention script enabled a plugin you reimplemented, keep the plugins: block in each module.yaml until you have confirmed the template form loads (./kotlin show modules plus an actual task run).

No dependency exclusions

There is no equivalent of Gradle's exclude(group, module). Any transitive exclusion silently disappears and the library lands on the runtime classpath. Note the trade-off in the PR (usually a few hundred unused KB).

No plugin-to-plugin dependencies

Plugins are isolated. If two plugins logically belong together, put both task actions in the same plugin module or extract the library.

No -P / -D CLI overrides

Read ephemeral overrides (force-version, skip-checks, dynamic image tags) from environment variables inside the @TaskAction; don't count on a --setting flag either (the pinned CLI may reject it). Pattern in the kotlin-tooling-gradle-to-kotlin-toolchain-plugin skill.

Capturing a command's output value

println from a @TaskAction is not a machine-readable channel. The Toolchain wraps it as <ts> INFO :<module>:<task>@<plugin> <value> and appends a <task> successful banner, so ./kotlin do currentVersion | tail -n1 yields the banner — and lowering --log-level to error/off drops the value line entirely, since it is emitted at INFO. Instead:

• Have the task write the value to a file named by an env var and cat it. Moreover, other tasks can reuse this value down the line
• Or read the git state the command produced: git describe --tags --exact-match HEAD.
• If you must parse stdout, match the task coordinate: awk '/<task>@<plugin>/ { v = $NF } END { print v }'.

Test resources shadow generated.resources

When a plugin emits release.properties and src/test/resources/release.properties exists, classpath ordering puts the test fixture first. It usually does the right thing but is brittle — if a test asserts a specific value, inject a stub service instead of relying on precedence.

Dependabot needs a stub build.gradle.kts

Dependabot's gradle file fetcher requires a build.gradle(.kts) in the configured directory before it scans gradle/libs.versions.toml; without one, package-ecosystem: "gradle" silently no-ops. Keep an empty build.gradle.kts at the root with a comment explaining why. The Toolchain ignores it.

amd64-only container images on Apple Silicon

Images like mongo:3.2 crash under Rosetta/QEMU on M-series Macs (runtime: failed to create new OS thread (have 2 already; errno=22)). Unchanged by the migration — the same image fails under ./gradlew check. Flag it as pre-existing; CI on ubuntu-latest is unaffected.

iOS (KMP): a migrated Info.plist loses its CFBundle* keys

A Gradle/KMP iOS app keeps bundle metadata in the hand-maintained iosApp.xcodeproj (GENERATE_INFOPLIST_FILE = YES), so Xcode synthesizes CFBundle* keys and the checked-in Info.plist is intentionally partial. The Toolchain ignores that .xcodeproj, generates its own, and uses your plist verbatim — nothing synthesizes the keys, and the .app has no bundle id:

Simulator device failed to install the application. Missing bundle ID.

Fix: make the plist self-contained, keeping your app-specific keys alongside these:

<key>CFBundleDevelopmentRegion</key><string>$(DEVELOPMENT_LANGUAGE)</string>
<key>CFBundleExecutable</key><string>$(EXECUTABLE_NAME)</string>
<key>CFBundleIdentifier</key><string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
<key>CFBundleInfoDictionaryVersion</key><string>6.0</string>
<key>CFBundleName</key><string>$(PRODUCT_NAME)</string>
<key>CFBundlePackageType</key><string>APPL</string>
<key>CFBundleShortVersionString</key><string>1.0</string>
<key>CFBundleVersion</key><string>1</string>

PRODUCT_BUNDLE_IDENTIFIER is set on the generated target. Underlying behaviour: the kotlin-tooling-kotlin-toolchain skill's "iOS apps" section.

KMP: carry over every source set's dependencies

Translate each Gradle source set (commonMain, jvmMain, androidMain, iosMain, commonTest, jvmTest, …) into its Amper counterpart — dependencies, dependencies@jvm/@android/@ios, test-dependencies, test-dependencies@<platform>. Don't cherry-pick the obvious library deps:

• A *Main dependency is also on that target's test classpath (jvmTest extends jvmMain), so dropping one can break tests with no compile error.

• A dependency can look like it belongs to another module and still be load-bearing. Canonical case: jvmMain { implementation(compose.desktop.currentOs) } in a shared library reads like a desktop-app dep, but it supplies the Skiko native runtime (skiko-awt-runtime-<os> with libskiko-<os>.dylib + .sha256) that the module's own JVM Compose UI tests (compose.uiTest / runComposeUiTest) load at runtime. compose.ui:ui-test pulls only Skiko's classes, never the natives. Dropping it compiles fine, then fails with:

  org.jetbrains.skiko.LibraryLoadException: Cannot find libskiko-macos-arm64.dylib.sha256, proper native dependency missing.
  

  Not a Toolchain bug: Gradle fails identically without it. Restore under dependencies@jvm, or scope it to test-dependencies@jvm to keep Skiko natives off consumers' classpaths.

Guard against drops: diff each Gradle source set's dependency list against its Kotlin Toolchain section (names and count), then run ./kotlin show dependencies -m <module> and compare with the Gradle build.

Common pitfalls

• No package plugin. CI ends up uploading build/artifacts/CompiledJvmArtifact/ (an internal class-file tree) instead of a JAR. Add the plugin before swapping the upload path.
• Committing build/. Add it to .gitignore early; drop the old .gradle/ entry.
• String interpolation inside Maven coordinates. com.example:foo:${pluginSettings.version} in plugin.yaml fails with "Value of type 'ShadowDependency' doesn't support string interpolation". Use $libs.foo.

Kotlin Toolchain docs: https://kotlin-toolchain.org/dev/