[[publishing_portal]]
= Publishing Plugins to the Gradle Plugin Portal
:portal: Gradle Plugin Portal
:plugin: Greeting Plugin
:publishplugin: Plugin Publishing Plugin
:plugin-reference-documentation: https://plugins.gradle.org/docs/publish-plugin[reference documentation of the {publishplugin}]

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 https://plugins.gradle.org[{portal}], a centralized, searchable repository dedicated to Gradle plugins.

This section will show you how to use the https://plugins.gradle.org/plugin/com.gradle.plugin-publish[{publishplugin}] to publish plugins to the {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 {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 link:../samples/sample_gradle_plugin.html[Greeting plugin sample].

Don't worry about cluttering up the {portal} with a trivial example plugin: trying to publish this plugin will safely fail with a permission error.

== Create an account on the {portal}

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

. Create an account
. Create an API key
. Add your API key to your Gradle configuration

Start by going to the https://plugins.gradle.org/user/register[registration page] — which looks like the image below – and creating an account.

.Registration page
image::plugin-portal-registration-page.png[]

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 is the third tab
image::plugin-portal-api-keys.png[]

It is common practice to copy and paste the text into your <<build_environment.adoc#sec:gradle_configuration_properties,$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
https://plugins.gradle.org/plugin/de.qaware.seu.as.code.credentials[Seauc Credentials plugin] or the
https://plugins.gradle.org/plugin/nu.studer.credentials[Gradle Credentials plugin].

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

[[plugin-publishing-plugin]]
== Add the {publishplugin} to the project

Add the {publishplugin} to the `plugins` block.

====
include::sample[dir="snippets/developingPlugins/publishingPlugins/groovy",files="build.gradle[tags=plugins_block]"]
include::sample[dir="snippets/developingPlugins/publishingPlugins/kotlin",files="build.gradle.kts[tags=plugins_block]"]
====
<1> Use the <<java_gradle_plugin.adoc#java_gradle_plugin,Java Gradle Plugin Development Plugin>>, which comes with the Gradle distribution, to author your Gradle plugin.
<2> Use the <<publishing_maven.adoc#publishing_maven, Maven Publish Plugin>> to generate the published metadata for your plugin
<3> The latest version of the {publishplugin} can be found on the https://plugins.gradle.org/plugin/com.gradle.plugin-publish[{portal}].

== Configure the {publishplugin}

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.

====
include::sample[dir="snippets/developingPlugins/publishingPlugins/groovy",files="build.gradle[tags=plugin_bundle]"]
include::sample[dir="snippets/developingPlugins/publishingPlugins/kotlin",files="build.gradle.kts[tags=plugin_bundle]"]
====
<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 {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.

You can use the below 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.

====
include::sample[dir="snippets/developingPlugins/publishingPlugins/groovy",files="build.gradle[tags=gradle-plugin]"]
include::sample[dir="snippets/developingPlugins/publishingPlugins/kotlin",files="build.gradle.kts[tags=gradle-plugin]"]
====
<1> Make sure your project has a `group` set which is used for the artifacts (jar and metadata) you publish in the repository of the {portal}
    and which is descriptive of the plugin author or the organization the plugin belongs too.
<2> Set the version for this publication. You need to increase the version, if you already published the plugin before.
<3> 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.
<4> The name for each plugin block does not affect the plugin configuration, but needs to be unique for each plugin provided.
<5> Set the unique `id` of the plugin.
<6> Set the plugin name in human-readable form.
<7> Set a description that will be displayed on the portal. it provides useful information to people would mightwant to use your plugin.
    Please give careful thought to the value of this property.

NOTE: 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 {plugin-reference-documentation} 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
[source.multi-language-sample,groovy]
----
pluginBundle {
    website = 'https://www.gradle.org/'
    vcsUrl = 'https://github.com/gradle/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
[source.multi-language-sample,kotlin]
----
pluginBundle {
    website = "https://www.gradle.org/"
    vcsUrl = "https://github.com/gradle/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 https://plugins.gradle.org/plugin/org.ysb33r.gradletest[GradleTest plugin] which is already published to the {portal}.

.build.gradle
[source.multi-language-sample,groovy]
----
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
[source.multi-language-sample,kotlin]
----
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 {portal} for the https://plugins.gradle.org/plugin/org.ysb33r.gradletest[GradleTest plugin], you will see how the specified metadata is displayed.

.GradleTest plugin metadata on the {portal}
image::plugin-portal-plugin-page.png[]

[[custom-plugin-repositories]]
== 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 <<publishing_maven.adoc#publishing_maven:repositories,configure repositories for publishing>>.
Then you can run the `publish` task to publish your plugin to all repositories you have defined (but not the {portal}).

====
include::sample[dir="snippets/developingPlugins/publishingPlugins/groovy",files="build.gradle[tags=local_repository]"]
include::sample[dir="snippets/developingPlugins/publishingPlugins/kotlin",files="build.gradle.kts[tags=local_repository]"]
====

To use the repository in another build, you have to add it to <<plugins.adoc#sec:custom_plugin_repositories,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.

[listing]
----
$ ./gradlew publishPlugins
----

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

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

NOTE: 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]]
== 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.
