Sharing a plugin with others means publishing the artifact, along with specific metadata and in most cases the pom.xml, to any type of repository that is supported by Gradle. Sharing a plugin on a global scale requires using a well-known repository. The Gradle Plugin Portal provides a centralized repository that is dedicated to Gradle plugins and which is also easily searchable.

The Plugin Publishing Plugin provides a convenient DSL to publish to the Gradle Plugin Portal and thereby eliminating a large number of configuration steps that might otherwise be needed when publishing to different Maven repository. It also provides a number of checks to validate that your plugin meets the criteria for publishing to the Gradle Plugin Portal.

What you’ll build

You will take an existing plugin project and configure it so that the plugin is publishable to the Gradle Plugin Portal.

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 3.5 or better

  • Source code for an existing Gradle plugin. (Preferably your own).

If you have never written a plugin, you can use the Greeting Plugin example. Also see Writing Gradle Plugins for other plugin ideas.

Create an account on the Gradle Plugin Portal

If you never published a plugin before you need to create a account on the Gradle Plugin Portal. This consists of three steps:

  1. Create an account.

  2. Create an API key.

  3. Add your API key to your Gradle configuration.

First go to the registration page and create 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-paste the text into your $HOME/.gradle/gradle.properties file, but if you wish you can place it elsewhere. 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 'com.gradle.plugin-publish' version '0.9.7' (1)
}
1 The latest version can be found on the 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 { (1)
    website = '<substitute your project website>' (2)
    vcsUrl = '<uri to project source repository>' (3)
}
1 Everything for the plugin is configured in the pluginBundle extension block.
2 Set the website for your plugin’s project.
3 Provide the source repository URI so that others can find it if they want to contribute.

Now specify the details of the plugin. This is done in a plugins block within the pluginBundle block. The most important part is the id, as that both uniquely identifies it on the Gradle Plugin Portal and prevents namespace clashes between different plugin authors. It should follow a domain namespace pattern i.e. org.samples.greeting. Substitute the values from this example with ones specific to your plugin. Take your time to think about good entries, as this information contributes to a better experience for people looking for specific plugins.

build.gradle
pluginBundle {
  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)
          tags = ['individual', 'tags', 'per', 'plugin'] (6)
          version = '1.2' (7)
      }
  }
}
1 Each plugin in a bundle is specified in the plugins block. 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 Must be the same identifier as specified in the plugin properties filename, the latter to be located in the src/main/resources/META-INF/gradle-plugins directory.
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.
6 Set tags that build script authors might use to search for plugin types. This can make your plugin easier to locate.
7 By default the version from project.version will be used, but you can set your own version if required.

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 for the the Greeting Plugin example:

build.gradle
pluginBundle {
    website = 'http://www.gradle.org/'
    vcsUrl = 'https://github.com/gradle-guides/greeting-plugin-example'

    plugins {
        greetingsPlugin {
            id = 'org.samples.greeting'
            displayName = 'Gradle Guides Example Greeting Plugin'
            description = 'The Greeting plugin is used as a template for people to start their own plugin adventure'
            tags = ['example','template','greeting']
            version = '1.2'
        }
    }
}

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

build.gradle (for GradleTest project)
pluginBundle {
    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 = ['testing','integrationTesting','compatibility']
        }
    }
}

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 publish the example GreetingPlugin as-is, it will be rejected. That will keep the portal from being overrun with too many experimental and duplicate greeting-type plugins. In this case the following Consume the publish plugin section will not be applicable.

Consume the published plugin

Once your plugin has been published, the instructions for others to use it will automatically appear on the plugin under a URL of the form https://plugins.gradle.org/plugin/<your-plugin-id>.

Next steps

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.