How do I actually tell the Portal what my plugin is called and what it does?

You can't just upload a JAR and hope for the best; the Gradle Plugin Portal needs specific metadata to make your plugin discoverable. This is handled by the gradle-plugin-publish plugin. I usually suggest adding this to your build script alongside maven-publish.

You'll need a gradlePlugin block in your build.gradle.kts. This is where you map your plugin ID—the string people actually put in their plugins {} block—to the implementation class. For our example, let's say we've built a license-checker plugin that ensures every file has a corporate header.

plugins {
    `kotlin-dsl`
    `maven-publish`
    id("com.gradle.plugin-publish") version "1.2.1"
}

gradlePlugin {
    plugins {
        create("licenseCheckerPlugin") {
            id = "com.yourname.license-checker"
            implementationClass = "com.yourname.license.LicenseCheckerPlugin"
            displayName = "Corporate License Header Checker"
            description = "Scans your src directory to ensure all Kotlin files have the standard legal header."
            tags.add("quality")
            tags.add("compliance")
        }
    }
}

Notice the id. That's the "public face" of your plugin. If you get this wrong, no one can use your plugin without manually specifying the coordinates, which is a pain they'll probably avoid.

Where do I put my API keys so I don't accidentally leak them on GitHub?

This is a classic mistake. Never, ever hardcode your Gradle Portal keys in the build script. I've seen too many engineers have to rotate their keys because they pushed a "quick fix" to a public repo. Instead, use your global gradle.properties file located in your user home directory (~/.gradle/gradle.properties).

The gradle-plugin-publish plugin looks for specific property names. Create these entries in that file:

gradlePluginsPublishingKey=your_api_key_here
gradlePluginsPublishingSecret=your_api_secret_here

By keeping these in the home directory, they stay local to your machine. When you move to a CI/CD pipeline like GitHub Actions, you'll inject these as environment variables. Gradle is smart enough to pick up ORG_GRADLE_PROJECT_gradlePluginsPublishingKey as an override.

Do I just run a 'publish' task, or is there more to it?

It's a bit of both. Because the Plugin Portal is essentially a proxy for a Maven repository, you first need a publication defined. The kotlin-dsl plugin usually handles the heavy lifting of creating the Maven publication for you, but you still need to trigger the specific upload task.

To push everything to the portal, you'll run:

./gradlew publishAllPublicationsToGradlePluginPortal

I'll be honest: the first time you run this, it'll probably fail. Usually, it's because of a missing pom.xml detail or a version conflict. If it does, check the logs for "400 Bad Request." That's usually a sign that your gradlePlugin block is missing a required field or your version string doesn't follow semantic versioning. I always recommend running publishToMavenLocal first. If it works on your machine's local cache, you know the packaging is fine and the issue is likely with your Portal credentials or metadata.

📋 Practical Task

Configuring the License-Checker Metadata and Local Publication

You have been given a skeleton project for the license-checker plugin. Your goal is to make it "publish-ready" without actually pushing it to the live portal yet.

• Add the com.gradle.plugin-publish plugin to the plugins block.
• Configure the gradlePlugin block so that the plugin ID is com.software.license-checker and the implementation class points to com.software.license.LicenseCheckerPlugin.
• Add at least two descriptive tags (e.g., "legal", "linting") to the metadata.
• Run the publishToMavenLocal task and verify that the artifact appears in your ~/.m2/repository folder.