JetBrains/intellij-platform-plugin-template: a Gradle scaffold for IntelliJ plugin projects

What the template actually removes from your setup work

The problem is not writing a plugin. It is the two days before that: a Gradle build that runs the IDE with your plugin loaded, a settings file pointing at the right repositories, a CI workflow, a changelog plugin, and a publish task that talks to JetBrains Marketplace. The README states the main goal plainly: to speed up the setup phase for both new and experienced developers by preconfiguring the project scaffold and CI, linking to the proper documentation pages, and keeping everything organized. That is the whole product. There is no runtime code you import.

It is aimed at people who already know they want to ship an IntelliJ Platform plugin and do not want to assemble the build themselves. The README points newcomers at an introduction article, What is the IntelliJ Platform, which suggests the template assumes some familiarity with the platform rather than teaching it. If you have never written a plugin, the scaffold removes friction but not the learning curve.

How the scaffold is put together

Three files carry most of the design. build.gradle.kts holds the build, written in Gradle Kotlin DSL, and integrates the intellij-platform-gradle-plugin, which the README describes as the way to run the IDE with your plugin and publish it to Marketplace. settings.gradle.kts holds repository configuration, moved there through the IntelliJ Platform repositories extension rather than sitting in the build script. gradle.properties holds the values the README expects to differ between repositories made from the template: group, version in SemVer format, and pluginRepositoryUrl, which the Gradle Changelog Plugin uses to generate URLs.

The source tree is deliberately small. The README lists three samples: a startup activity triggered on project open, a project-level service, and a tool window as a sample UI entry point. Each one exists to show a registration path, not to be useful on its own. The changelog plugin patches release notes from CHANGELOG.md automatically, so the changelog file is an input to the build rather than documentation you maintain by hand.

Kotlin is the primary language of the repository, but the build supports Java implementation as well. The README notes that to use Java in your plugin you create the /src/main/java directory; it is not there by default.

Installing from the template and running the sample plugin

There is nothing to install as a dependency. You create a repository from the template on GitHub, using the Use this template button while logged in. The README notes that this gives you a project with no history or reference to the original repository, which is the point: no manual history clearing.

Creating the repository triggers the Template Cleanup workflow, which the README says overrides or removes template-specific configuration such as the plugin name and the current changelog. After it finishes, one GitHub setting has to be changed by hand. The README is explicit about it: open the new project's Settings | Actions | General page and enable Allow GitHub Actions to create and approve pull requests.

Clone the result and open it in IntelliJ IDEA. The README suggests the Get from VCS action on the welcome screen. Then set the Java SDK to version 21 in Project Structure settings:

# In IntelliJ IDEA: File | Project Structure | Project SDK
# Select a Java 21 SDK for the project

Before writing feature code, review the metadata in gradle.properties and plugin.xml, and optionally move the generated sources into a package that suits you. The README gives no command for the cleanup itself and no rollback if the workflow misfires; the source of truth for what it deletes is the workflow file in .github/, which the README links as template_cleanup.yml.

Once the SDK is set, the predefined run configurations in the .run directory let you start a sandboxed IDE with the plugin loaded, which is how you would exercise the sample startup activity, service and tool window.

Where the template gets in your way

The cleanup workflow is the sharpest edge. It rewrites files in your new repository as its first action, and the README describes it in one sentence without listing what it touches. If you start editing before it runs, or if it fails silently, you are left with a plugin name and changelog that still refer to the template. The README points at the workflow file rather than documenting the behaviour, so reading that file is part of setup, not an optional extra.

The template also encodes opinions you may not share. Repository configuration lives in settings.gradle.kts through an extension rather than in the build script. The changelog plugin expects CHANGELOG.md to be maintained in a format it can patch. Publishing goes through the publishPlugin task and GitHub Actions workflows. Each of these is a reasonable default and each is work to undo.

If you already have a plugin project with a working build, this is the wrong tool. There is no migration path described in the README; adopting the template means starting a new repository and moving your sources into it. For a mature plugin with custom build logic, that trade is rarely worth it.

Template scaffold versus the Gradle plugin underneath

The real comparison is between starting from this template and starting from an empty repository with the intellij-platform-gradle-plugin added by hand. That plugin is the engine: it runs the IDE with your plugin and publishes to Marketplace, and the README advises always upgrading to its latest version. The template is the wiring around it.

Starting empty gives you full control over the build file and no cleanup workflow to reason about, at the cost of writing the settings, the CI workflows, the changelog integration and the run configurations yourself. Starting from the template gives you all of that immediately, at the cost of inheriting the template's choices and one automated rewrite of your repository on creation.

A second option is the IntelliJ Platform Plugin SDK documentation itself, which the README links for Kotlin integration and for using Gradle. That is reference material, not a scaffold: it explains the build you would otherwise assemble. The template's value is that it has already assembled one and keeps it current. The release history supports that reading: versions 2.6.0, 2.5.0 and 2.4.1 landed between March and May 2026, so the scaffold is being revised rather than left frozen.

Maintenance, releases and the Apache-2.0 licence

The repository is not archived, and the last push was on 2026-05-04, which is recent enough that the template is still being updated. The three most recent releases, 2.6.0, 2.5.0 and 2.4.1, all fall in 2026, and the README tells you to watch the repository to be notified about releases containing new features and fixes.

That creates a maintenance obligation most templates do not have. Because a project created from the template has no history or reference to this repository, you do not receive those updates automatically. The README's instruction to always upgrade to the latest version of the IntelliJ Platform Gradle Plugin is the practical mitigation: keep the underlying plugin current in your own build, and treat the template as a starting point you have already diverged from.

The licence is Apache-2.0. The template cleanup workflow removes template-specific configuration, but the README does not state whether the licence file is among the files it rewrites, so check the LICENSE file in your generated repository and confirm which licence you actually want to ship under. This is a description of what the repository contains, not legal advice.

Choosing between the sample code and your own

The three samples are the part most likely to be deleted first, and the README treats them that way: they illustrate a startup activity, a project-level service and a tool window, and the section is titled Sample code. They are registrations you can copy the shape of, not components to build on.

The service sample is the one worth reading closely, because project-level services are where plugin state usually lives and the registration pattern is easy to get subtly wrong. The tool window sample shows the UI entry point, which is the piece most plugins need and the piece with the most platform-specific ceremony. The startup activity sample runs on project open, which is also the easiest place to slow down IDE startup if you put real work in it.

Keep the samples until your first real feature compiles and runs in the sandboxed IDE, then remove them. Leaving them in place means shipping registrations you do not need, and the plugin.xml entries that declare them are the ones you must remember to delete alongside the source files.

Editorial conclusion

Adopt it if you are starting a plugin from zero and want the Gradle, CI and publishing wiring already in place, and you are willing to read gradle.properties and plugin.xml before writing feature code. Do not adopt it if you already have a working build you do not want to migrate, or if you need a library to depend on rather than a repository to copy. Before the first commit, verify that the Template Cleanup workflow ran, that Actions is allowed to create and approve pull requests, and that the Java SDK is set to 21.

Frequently asked questions

Official sources

1. Issues
2. JetBrains/intellij-platform-plugin-template on GitHub
3. License: Apache-2.0
4. README
5. Releases