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 guide 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.

What you’ll build

You will take an existing plugin project and configure it so that the plugin can be published to the Gradle Plugin Portal. You will then perform the publication.

What you’ll need

  • About

  • A text editor

  • A command prompt

  • The Java Development Kit (JDK), version 1.7 or higher

  • A Gradle distribution, version 4.10 or better

Start with an existing Gradle plugin project

You will need an existing plugin project for this tutorial. If you don’t have your own, then you should download the source code for the example Greeting Plugin project from GitHub. It’s based on the Greeting Plugin developed in the Writing Gradle Plugins guide.

If you have followed the Writing Gradle Plugins guide and want to use its project as the basis for this guide, then you will need to copy the contents of the buildSrc directory into its own project and add a build file. If you’re not sure how to do that, just use the example project from GitHub.

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.

registration page 552x432
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.

api keys 860x208
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
plugins {
    id 'java-gradle-plugin' (1)
    id 'com.gradle.plugin-publish' version '0.10.0' (2)
}
build.gradle.kts
plugins {
    `java-gradle-plugin` (1)
    id("com.gradle.plugin-publish") version "0.10.0"  (2)
}
1 This guide assumes you’re using the Java Gradle Plugin Development Plugin which comes with the Gradle distribution and is the recommended way of authoring Gradle plugins.
2 The latest version of the Plugin Publishing Plugin can be found on the Gradle Plugin Portal.

Configure the Plugin Publishing Plugin

Create a pluginBundle block in build.gradle and specify global information regarding your plugin. This helps other people browsing the portal find more information about your plugin and learn how to contribute to its development.

build.gradle
pluginBundle {
    website = '<substitute your project website>' (1)
    vcsUrl = '<uri to project source repository>' (2)
    tags = ['tags', 'for', 'your', 'plugins'] (3)
}
build.gradle.kts
pluginBundle {
    website = "<substitute your project website>" (1)
    vcsUrl = "<uri to project source repository>" (2)
    tags = listOf("tags", "for", "your", "plugins") (3)
}
1 Set the website for your plugin’s project.
2 Provide the source repository URI so that others can find it if they want to contribute.
3 Set the tags to be used for all plugins unless overridden in the plugins block.

Now specify the details of the plugin. This is done in a plugins block within the gradlePlugin block. The most important part is the id property, as that both uniquely identifies it on the Gradle Plugin Portal and prevents namespace clashes between different plugin authors.

As a convention, we recommend you use an ID based on the reverse-domain pattern used for Java packages, for example org.example.greeting. You can use this example ID for the Greeting Plugin project, but substitute the values for more appropriate ones if you’re working with your own plugin that you actually want published.

build.gradle
gradlePlugin {
    plugins { (1)
        greetingsPlugin { (2)
            id = '<your plugin identifier>' (3)
            displayName = '<short displayable name for plugin>' (4)
            description = '<Good human-readable description of what your plugin is about>' (5)
            implementationClass = '<your plugin class>'
        }
    }
}
build.gradle.kts
gradlePlugin {
    plugins { (1)
        create("greetingsPlugin") { (2)
            id = "<your plugin identifier>" (3)
            displayName = "<short displayable name for plugin>" (4)
            description = "<Good human-readable description of what your plugin is about>" (5)
            implementationClass = "<your plugin class>"
        }
    }
}
1 Each plugin in a bundle is specified in the plugins blocks. As you are only publishing a single plugin at this point there will only be one entry, but should your project publish a bundle in the future you will list each of them in here.
2 The name for each plugin block does not affect the plugin configuration, but needs to be unique for each plugin provided.
3 Set the unique id of the plugin.
4 Set the plugin name in human-readable form.
5 Set a description that will be displayed on the portal. Although this is optional, it provides useful information to people would might want to use your plugin. Please give careful thought to the value of this property.
If you are publishing multiple plugins, please note that it’s possible to use custom tags and a custom version per plugin using the pluginBundle block. Please refer to the reference documentation of the Plugin Publishing Plugin for an example.

Think about what would be the correct metadata for your plugin and fill in the template appropriately. Here is an example of the pluginBundle configuration that you can use for the Greeting Plugin example:

build.gradle
pluginBundle {
    website = 'http://www.gradle.org/'
    vcsUrl = 'https://github.com/gradle-guides/greeting-plugin-example'
    tags = ['example', 'template']
}

gradlePlugin {
    plugins {
        greetingsPlugin {
            id = 'org.example.greeting'
            displayName = 'Greeting Plugin'
            description = 'Template for people to start their own plugin adventure'
            implementationClass = 'org.example.greeting.GreetingPlugin'
        }
    }
}
build.gradle.kts
pluginBundle {
    // please change these URLs to point to your own website/repository
    website = "http://www.gradle.org/"
    vcsUrl = "https://github.com/gradle-guides/greeting-plugin-example"
    tags = listOf("example", "template")
}

gradlePlugin {
    plugins {
        create("greetingsPlugin") {
            id = "org.example.greeting"
            displayName = "Greeting Plugin"
            description = "Template for people to start their own plugin adventure"
            implementationClass = "org.example.greeting.GreetingPlugin"
        }
    }
}

As a second example of plugin configuration, consider the GradleTest plugin which is already published to the Gradle Plugin Portal.

build.gradle
pluginBundle {
    website = 'https://github.com/ysb33r/gradleTest'
    vcsUrl = 'https://github.com/ysb33r/gradleTest.git'
    tags = ['testing', 'integrationTesting', 'compatibility']
}
gradlePlugin {
    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'
            implementationClass = 'org.ysb33r.gradle.gradletest.GradleTestPlugin'
        }
    }
}
build.gradle.kts
pluginBundle {
    website = "https://github.com/ysb33r/gradleTest"
    vcsUrl = "https://github.com/ysb33r/gradleTest.git"
    tags = listOf("testing", "integrationTesting", "compatibility")
}
gradlePlugin {
    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"
            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.

org.ysb33r.gradletest 1299x354
Figure 3. GradleTest plugin metadata on the Gradle Plugin Portal

Publish your plugin

Publish the plugin by using the publishPlugin task.

$ ./gradlew publishPlugins

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 guide, 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

If your plugin is successfully published, 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.

Help improve this guide

Have feedback or a question? Found a typo? Like all Gradle guides, help is just a GitHub issue away. Please add an issue or pull request to gradle-guides/publishing-plugins-to-gradle-plugin-portal and we’ll get back to you.