skip to content

How do you publish a plugin to the Gradle Plugin Portal, and what does the publish-plugin tooling generate?

level: seniorimportance: should knowfreq 33%

answer

  1. com.gradle.plugin-publish + java-gradle-plugin
  2. gradlePlugin { } metadata: id, implementationClass, website, vcsUrl, tags
  3. publishPlugins task
  4. API key + secret, not in VCS
  5. marker generated, append-only versions

basics

~10 s

Apply the com.gradle.plugin-publish plugin, declare your plugin id/implementation/display metadata in gradlePlugin {}, configure portal API key+secret, then run publishPlugins to upload the jar, marker, and metadata to plugins.gradle.org.

solid answer

~40 s

To publish to the portal you apply the **`com.gradle.plugin-publish`** plugin alongside **`java-gradle-plugin`**. In `gradlePlugin { plugins { ... } }` you declare each plugin's **id**, `implementationClass`, plus display name, description, tags, and website/VCS URLs. You authenticate with a portal **API key and secret** (from your plugins.gradle.org account), supplied via `gradle.properties` or env vars — never committed. Running `./gradlew publishPlugins` validates the metadata, builds the implementation jar, generates the **plugin marker** publication, signs/uploads everything, and the portal then indexes the new version so others can apply it by id. First-time ids go through portal approval. The tooling enforces required metadata (you'll get validation errors for missing website/vcsUrl/tags), and `--validate-only` lets you dry-run. After publishing, the new version appears on the plugin's portal page with copy-paste snippets.

code

bash · 5 lines
bash
# CI: validate, then publish using env-provided portal credentials
export GRADLE_PUBLISH_KEY=$PORTAL_KEY
export GRADLE_PUBLISH_SECRET=$PORTAL_SECRET
./gradlew publishPlugins --validate-only
./gradlew publishPlugins

go deeper

for a junior

Recognize that publishing exists and uses a publish plugin with credentials; details not expected.

for a middle

Name com.gradle.plugin-publish, the gradlePlugin {} metadata, and the publishPlugins task.

for a senior

Explain marker generation, required metadata validation, credential handling, and id-ownership approval.

for a principal

Own release governance: immutable versions, CI credential management, namespace ownership, and dual internal/portal distribution strategy.

## The publishing toolchain Publishing to the **Gradle Plugin Portal** uses two plugins together: - **`java-gradle-plugin`** — declares your plugin(s) and auto-generates the **plugin marker** publication that maps the plugin id to the implementation jar. - **`com.gradle.plugin-publish`** — adds the `publishPlugins` task and the portal-specific metadata and upload logic. ```kotlin plugins { `java-gradle-plugin` id("com.gradle.plugin-publish") version "1.2.1" } group = "com.acme" version = "1.0.0" gradlePlugin { website = "https://github.com/acme/awesome-plugin" vcsUrl = "https://github.com/acme/awesome-plugin.git" plugins { create("awesome") { id = "com.acme.awesome" implementationClass = "com.acme.AwesomePlugin" displayName = "Acme Awesome Plugin" description = "Does awesome build things" tags = listOf("acme", "codegen") } } } ``` ## Authentication The portal issues an **API key + secret** per account (from the website's API-keys page). Gradle reads them as `gradle.publish.key` and `gradle.publish.secret`, typically from `~/.gradle/gradle.properties` or CI secrets/env vars. These credentials grant publish rights for your namespace, so they must stay out of VCS. ## What publishPlugins does Running `./gradlew publishPlugins`: 1. validates the declared metadata (id, implementationClass, website, vcsUrl, tags — missing required fields fail the task), 2. builds the implementation jar (and sources/javadoc), 3. generates the **plugin marker** artifact `<id>:<id>.gradle.plugin:<version>`, 4. uploads jar + marker + POM to the portal, 5. the portal indexes and serves the new version. Use `./gradlew publishPlugins --validate-only` for a dry run that checks metadata without uploading. ## Id ownership and approval The first time you publish a **new plugin id**, the portal requires approval and ties the id's namespace to your account so others can't hijack it. Subsequent versions of an owned id publish without re-approval. ## Versioning rules The portal is **append-only**: a published `id:version` is immutable — you cannot overwrite or delete it, you publish a new version. This is why CI must never republish the same version. ## Relation to internal publishing The same `java-gradle-plugin`-generated marker is what you publish to an **internal** Maven repo via `maven-publish` when distributing company plugins privately — only the upload target differs (portal vs Artifactory/Nexus).

  • Can you overwrite an already-published plugin version on the portal?
    No — published id:version pairs are immutable. You must publish a new version; this is why CI must guard against re-publishing the same version.
  • What metadata does publishPlugins require?
    At minimum the plugin id and implementationClass, plus website, vcsUrl, display name/description and tags; missing required fields fail validation.
  • What's different about publishing the same plugin to an internal repo?
    The same java-gradle-plugin marker is reused; you publish it via maven-publish to Artifactory/Nexus instead of the portal — only the target and credentials change.

saying these in an interview costs you the question

  • Committing the portal API key/secret to the repository.
  • Assuming you can re-publish or delete an existing portal version.
  • Forgetting java-gradle-plugin, so no marker is generated and the id can't be applied.

context

resolving links…