Publishing HSC Releases

HSC (Core and Gradle plugin) can be published to Maven Central (MC) for retrieval by its consumers.

Traditional retrieval as Gradle plugin from Gradle Plugin Portal is still possible, as they are redirecting plugin downloads automatically to Maven Central.

Only note that newer versions (>= 2.0.0) currently do not show up in the web interface.

Prerequisites

Maven Central (Sonatype) account

Make yourself familiar with the publishing process.

Credentials needed

You need respective credentials to upload files to Maven Central for the org.aim42.htmlSanityCheck namespace. Talk to Gernot Starke to get these permissions.

You will need to sign up for Maven Central (or, to be more precise, to its provider, Sonatype). Additionally, you need to create a portal token.

Artifact signing

To successfully upload artifacts and other files (POM etc.), a valid PGP signature is required. A proper GPG (agent) setup is beyond the scope of this tutorial. Therefore, you need to set up GnuPG in your local ${HOME}/.gradle/gradle.properties, according to the Gradle Signatory documentation.

Add the following entries:

signing.keyId=24875D73 (1)
signing.secretKeyRingFile=/Users/me/.gnupg/secring.gpg (2)
signing.password=<SECRET> (3)
1 You have to provide the id of your key (of course).
2 Note that you need to specify the literal path to your home directory; it is not possible to refer to system properties like ${user.home} here.
3 Instead of putting the clear text password into the file, you should provide it on the command line when calling Gradle 
./gradlew -Psigning.password=... <task>
Use GPG Agent

Alternatively, you may use the GPG Agent of your GnuPG installation to cache the secret in memory, thereby reducing the risk of accidentally exposing the clear text passphrase in your command line or environment.

You can make use of it by setting the flag useGpgCmd to true:

./gradlew -PuseGpgCmd=true <task>

Note that the (native) gpg command is used in background and that it cannot request the passphrase when executed. This may lead to errors like

gpg: Sorry, we are in batchmode - can't get input

FAILURE: Build failed with an exception.

In this case, you have to make sure the agent is started and the password is cached, e.g., by executing

echo empty | gpg --clearsign -o /dev/null

Publishing actions

Adjust version number

Set the version number in ../../../gradle.properties to the next value.

Maintain ChangeLog

Add the respective changes to ../../../CHANGELOG.md

Build / Test

Clean, check (test), and perform integration tests:

./gradlew clean check integrationTest
Sign / Upload to Maven Central

Sign artifacts and load them up to Maven Central via JReleaser.

./gradlew jreleaserRelease -PenableSigning=true -Psigning.password=... # <1> <2>
1 Checkout Artifact signing for more information.
2 The enableSigning flag is necessary to enforce signing (which is not necessary for local installations, integration testing, etc.)

The jreleaserRelease task will

  • Implicitly call the task signAll which signs and pushes all required files for publication to a local repository.

  • Then pick them up from there and load them up to the Maven Central staging area as a new version.

  • Release current state to GitHub and tag the current version accordingly.

Use GPG Agent (command) in practice

If you have GPG configured properly, you may use the GPG-Agent.

./gradlew jreleaserDeploy -PenableSigning=true -PuseGpgCmd=true
Publish on Maven Central

Finally, publish the staged version on Maven Central, i.e., Sonatype Central.