# Publishing Plugins to the Gradle Plugin Portal

version 8.1

Publishing a plugin is the main way to make it available for others to use. One approach is to publish the plugin to a private repository, which is common when you want to restrict who can use it. But if you want the plugin to be available to anyone in the world, i.e. public, then you should publish it to the Gradle Plugin Portal, a centralized, searchable repository dedicated to Gradle plugins.

This section will show you how to use the Plugin Publishing Plugin to publish plugins to the Gradle Plugin Portal using a convenient DSL. Taking this approach eliminates a large number of configuration steps and provides a number of checks to validate that your plugin meets the criteria enforced by the Gradle Plugin Portal.

## Start with an existing Gradle plugin project

You will need an existing plugin project for this tutorial. If you don’t have your own, you may use the Greeting plugin sample.

Don’t worry about cluttering up the Gradle Plugin Portal with a trivial example plugin: trying to publish this plugin will safely fail with a permission error.

## Create an account on the Gradle Plugin Portal

If you have never published a plugin to the Gradle Plugin Portal before, you first need to create an account there. This consists of three steps:

1. Create an account

2. Create an API key

3. Add your API key to your Gradle configuration

Start by going to the registration page — which looks like the image below – and creating an account.

Figure 1. Registration page

Follow the instructions on that page. Once you have logged in, you can get your API key via the "API Keys" tab of your profile page.

Figure 2. API keys is the third tab

It is common practice to copy and paste the text into your $HOME/.gradle/gradle.properties file, but you can also place it in any other valid location. All that the plugin requires is that `gradle.publish.key` and `gradle.publish.secret` are available as project properties when the appropriate Plugin Portal tasks are executed.

If you are concerned about placing your credentials in `gradle.properties`, investigate use of Seauc Credentials plugin or the Gradle Credentials plugin.

Once you have the API key you can publish as many plugins as you like.

## Add the Plugin Publishing Plugin to the project

Add the Plugin Publishing Plugin to the `plugins` block.

build.gradle.kts

    plugins {
        id("com.gradle.plugin-publish") version "1.1.0"
    }

build.gradle

    plugins {
        id 'com.gradle.plugin-publish' version '1.1.0'
    }

The latest version of the Plugin Publishing Plugin can be found on the Gradle Plugin Portal.

| Since version 1.0.0 the Plugin Publish Plugin automatically applies the Java Gradle Plugin Development Plugin (assists with developing Gradle plugins) and the Maven Publish Plugin (generates plugin publication metadata). If using older versions of the Plugin Publish Plugin, these helper plugins need to be applied explicitly.

## Configure the Plugin Publishing Plugin

The first thing to do when configuring the publication of your plugins is to specify the common properties that apply to all of them. This includes their identity plus the sources and documentation related to them. This will help people browsing the portal find more information about your plugins and learn how to contribute to their development.

build.gradle.kts

    group = "io.github.johndoe" (1)
    version = "1.0" (2)

    gradlePlugin { (3)
        website.set("<substitute your project website>") (4)
        vcsUrl.set("<uri to project source repository>") (5)

        // ... (6)
    }

build.gradle

    group = 'io.github.johndoe' (1)
    version = '1.0'     (2)

    gradlePlugin { (3)
        website = '<substitute your project website>' (4)
        vcsUrl = '<uri to project source repository>' (5)

        // ... (6)
    }

1 | Make sure your project has a `group` set which is used to identify the artifacts (jar and metadata) you publish for your plugins in the repository of the Gradle Plugin Portal and which is descriptive of the plugin author or the organization the plugins belong too.
2 | Set the version of your project, which will also be used as the version of your plugins.
3 | Use the `gradlePlugin` block provided by the Java Gradle Plugin Development Plugin to configure further options of your plugin publication.
4 | Set the website for your plugin’s project.
5 | Provide the source repository URI so that others can find it, if they want to contribute.
6 | Set specific properties for each of the plugins you want to publish; see next section.

Next you need to define the specific plugins you intend to publish. Their most important property is their `id`, as that both uniquely identifies plugins on the Gradle Plugin Portal and prevents namespace clashes between different plugin authors.

| If you would like to associate your plugin with a particular organization, you also set the ID based on that organization’s domain using the reverse-domain pattern used for Java packages, for example `org.example.greeting`. If the plugin doesn’t belong to any specific organization, then the plugin ID should be associated with the author, for example by using the author’s GitHub ID in a reverse domain pattern, like `io.github.johndoe`. Remember that the plugin id and project group should match, i.e. have the same top level namespace.

build.gradle.kts

    gradlePlugin { (1)
        // ... (2)

        plugins { (3)
            create("greetingsPlugin") { (4)
                id = "<your plugin identifier>" (5)
                displayName = "<short displayable name for plugin>" (6)
                description = "<human-readable description of what your plugin is about>" (7)
                tags.set(listOf("tags", "for", "your", "plugins")) (8)
                implementationClass = "<your plugin class>"
            }
        }
    }

build.gradle

    gradlePlugin { (1)
        // ... (2)

        plugins { (3)
            greetingsPlugin { (4)
                id = '<your plugin identifier>' (5)
                displayName = '<short displayable name for plugin>' (6)
                description = '<human-readable description of what your plugin is about>' (7)
                tags.set(['tags', 'for', 'your', 'plugins']) (8)
                implementationClass = '<your plugin class>'
            }
        }
    }

1 | Plugin specific configuration also goes into the `gradlePlugin` block.
2 | This is where we previously added global properties.
3 | Each plugin you publish will have its own block inside `plugins`.
4 | The name of a plugin block needs to be unique for each plugin you are publishing; this is a property used only locally by your build and will not be part of the publication.
5 | Set the unique `id` of the plugin, as it will be identified in the publication.
6 | Set the plugin name in human-readable form.
7 | Set a description to be displayed on the portal. It provides useful information to people who might want to use your plugin.
8 | Specifies the categories your plugin covers. Makes the plugin more likely to be discovered by people needing its functionality.

As an example consider the configuration for the GradleTest plugin, which is already published to the Gradle Plugin Portal.

build.gradle.kts

    gradlePlugin {
        website.set("https://github.com/ysb33r/gradleTest")
        vcsUrl.set("https://github.com/ysb33r/gradleTest.git")
        plugins {
            create("gradletestPlugin") {
                id = "org.ysb33r.gradletest"
                displayName = "Plugin for compatibility testing of Gradle plugins"
                description = "A plugin that helps you test your plugin against a variety of Gradle versions"
                tags.set(listOf("testing", "integrationTesting", "compatibility"))
                implementationClass = "org.ysb33r.gradle.gradletest.GradleTestPlugin"
            }
        }
    }

build.gradle

    gradlePlugin {
        website = 'https://github.com/ysb33r/gradleTest'
        vcsUrl = 'https://github.com/ysb33r/gradleTest.git'
        plugins {
            gradletestPlugin {
                id = 'org.ysb33r.gradletest'
                displayName = 'Plugin for compatibility testing of Gradle plugins'
                description = 'A plugin that helps you test your plugin against a variety of Gradle versions'
                tags.addAll('testing', 'integrationTesting', 'compatibility')
                implementationClass = 'org.ysb33r.gradle.gradletest.GradleTestPlugin'
            }
        }
    }

If you browse the associated page on the Gradle Plugin Portal for the GradleTest plugin, you will see how the specified metadata is displayed.

Figure 3. GradleTest plugin metadata on the Gradle Plugin Portal

### Sources & Javadoc

The Plugin Publish Plugin automatically generates and publishes the Javadoc and sources JARs for your plugin publication.

### Sign artifacts

Starting from version 1.0.0 of Plugin Publish Plugin, signing of published plugin artifacts has been made automatic. To enable it, all that’s needed is to apply the `signing` plugin in your build.

### Shadow dependencies

Starting from version 1.0.0 of Plugin Publish Plugin, shadowing the dependencies of your plugin (ie. publishing it as a fat jar) has been made automatic. To enable it, all that’s needed is to apply the `com.github.johnrengelman.shadow` plugin in your build.

## Publish your plugin to a local repository

To check how the artifacts of your published plugin look, or to use it only locally or internal in your company, you can publish it to any maven repository, including a local folder. For that, you only need to configure repositories for publishing. Then you can run the `publish` task to publish your plugin to all repositories you have defined (but not the Gradle Plugin Portal).

build.gradle.kts

    publishing {
        repositories {
            maven {
                name = "localPluginRepository"
                url = uri("../local-plugin-repository")
            }
        }
    }

build.gradle

    publishing {
        repositories {
            maven {
                name = 'localPluginRepository'
                url = '../local-plugin-repository'
            }
        }
    }

To use the repository in another build, you have to add it to the repositories of the `pluginManagement {}` block in your `settings.gradle(.kts)` file.

## Publish your plugin to the Plugin Portal

Publish the plugin by using the `publishPlugin` task.

    $ ./gradlew publishPlugins

You can validate your plugins before actually publishing them using the `--validate-only` flag:

    $ ./gradlew publishPlugins --validate-only

If you have not configured your Gradle Plugin Portal key and secret values in your `gradle.properties` file, you can specify them on the command-line

    $ ./gradlew publishPlugins -Pgradle.publish.key=<key> -Pgradle.publish.secret=<secret>

| If you attempt to publish the example Greeting Plugin with the ID used in this section, you will encounter a permission failure. That’s expected and ensures that the portal won’t be overrun with multiple experimental and duplicate greeting-type plugins.

## Consume the published plugin

Once you successfully publish a plugin it won’t immediately appear on the Portal. It also needs to pass an approval process, which is manual and relatively slow for the initial version of your plugin, but is fully automatic for subsequent versions. For further details see here.

Once your plugin is approved, you’ll be able to find instructions for its use at a URL of the form https://plugins.gradle.org/plugin/<your-plugin-id>. For example, the Greeting Plugin example is already on the portal at https://plugins.gradle.org/plugin/org.example.greeting.