Publishing HSC Releases

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

Additionally, the Gradle plugin can be published to Gradle Plugin Portal (GPP).

Prerequisites

Maven Central (Sonatype) account

Make yourself familiar with the publishing process.

Maven Central 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[1].

Check out JReleaser Credentials / Environment Settings how to inject these credentials in your environment for publication activities.

Gradle Plugin Portal

It is possible to publish new versions of the Plugin to the Gradle Plugin Portal.

Unique publisher required

Only one person at a time can take responsibility for publishing of plugins (Or new versions) to GPP. Currently, this is Gerd Aschemann (following Gernot Starke). Only the current maintainer can change the ownership (by creating a new ownership transformation request at https://github.com/gradle/plugin-portal-requests).

After creating a user, you need to login to GPP:

./gradlew -Pprofile=gpp :htmlSanityCheck-gradle-plugin:login

This will put the respective key and secret to your ~/.gradle/gradle.properties file. Alternatively, you can set these as environment variables:

export GRADLE_PUBLISH_KEY=...
export GRADLE_PUBLISH_SECRET=...

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

JReleaser Credentials / Environment Settings

You will have to set the following environment variable to perform misc. JReleaser actions.

export JRELEASER_MAVENCENTRAL_STAGE=UPLOAD (1)
export JRELEASER_GITHUB_TOKEN=... (2)
export JRELEASER_DEPLOY_MAVEN_MAVENCENTRAL_USERNAME=... (3)
export JRELEASER_DEPLOY_MAVEN_MAVENCENTRAL_PASSWORD=... (3)
export JRELEASER_ANNOUNCE_MASTODON_ACCESS_TOKEN=... (4)
1 Maven Central publications require two steps. This variable setting enables upload to the staging area, perform the final publication interactively.
2 Get an appropriate GitHub token (needs write access to the repository).
3 Follow the steps above to get the required Maven credentials. Create a deployment user and password in your Maven Central (Sonatype) account.
4 Access token for your Mastodon Account (on https://mastodon.social[2]).

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 / Stage to Maven Central

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

./gradlew jreleaserDeploy -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 jreleaserDeploy 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.

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 Gradle Plugin Portal

Set the respective credentials (cf. GPP Prerequisites). Then publish on GPP:

./gradlew -Pprofile=gpp :htmlSanityCheck-gradle-plugin:publishPlugins (1)
1 An additional --validate-only allows to check credentials

Performing this for the first time after a Change of the maintainer may take some time as the Gradle team will perform some checks.

You can delete the published version if you fail with one of the other steps.

Publish Release

Publish to GitHub

./gradlew jreleaserRelease

The jreleaserRelease task will release the current state to GitHub and tag the current version accordingly.

Publish on Maven Central

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

Once published, you cannot roll back the release on Maven Central as releases are immutable. Hence, run this step as the very last one if everything else ran smoothly.

Announce new release on Social Media

Finally, announce the new release on Social Media, i.e., Mastodon (Social).

./gradlew jreleaserAnnounce
1. This is a different user/password than your login user.
2. Publishing to a different Mastodon server requires more changes.