Maven release steps - abelsromero/asciidoctor-maven-plugin GitHub Wiki

Release steps

This document explains the steps to complete the publication of the asciidoctor-maven-plugin from a local build to Maven Central.


This guide assumes that:

  • You already have a GPG key and GPG tool installed for signing.

  • You have SSH authentication enabled for Github (see This is required to push the new tag.

  • You have permissions to publish into Asciidoctor’s Maven Central repo and sync into Maven Central (requires OS Sonatype account).

  • Some familiarity with Maven configuration and commands.

Release preparation (to be done only once)

  1. MavenCentral setup

    Add your MavenCentral credentials (it’s recommended to use a token instead of user+password) to your Maven settings as in the example below. Usually found in $HOME/.m2/settings.xml.

    		<id>osshr</id> (1)
    1. The id must match exactly the id in the distributionManagement section of the project’s pom.xml. You can validate access try to login in

  2. GitHub setup

    This step is not mandatory. It depends on your local configuration, but doing it ensures a reproducible build without surprises. This is then, highly recommended.

    Add your GitHub credentials to your Maven settings ($HOME/.m2/settings.xml) as in the example below.

    		 <id>github</id> (1)
    		 <username>GITHUM_USERNAME</username> (2)
    1. The id must match exactly the id used in the command in later steps

    2. Note it’s the username, not the email account

  3. Maven’s GPG setup

    Add your GPG information to your Maven settings ($HOME/.m2/settings.xml) as a profile.

    The use of a profile is recommended to be able to use different signing configurations and keep configuration tidy, but it’s not mandatory.

    		<gpg.passphrase>GPG_PASSPHRASE</gpg.passphrase> (1)
    	<activeProfile>gpg</activeProfile> (2)
    1. Passphrase to your GPG keychain

    2. Profile activated by default

If you have more than one key, set <keyname> in the maven-gpg-plugin plugin configuration with the keu id.

Plugin release steps

Before continuing, please check that:

  • ✓ gpg maven profile is activated, or else it will fail when trying to sign

  • git and gpg (binary name may deppend on tool used) command is available in the shell path

  • ✓ Github credentials are available. If not cached, you need to add them in settings.xml, and use as seen in previous section

  • ✓ Signature works. You can test it with this command mvn verify -Prelease-profile -Pgpg -DskipTests -Dgpg.keyname={KEY_ID}. Use gpg --list-secret-keys --keyid-format SHORT to obtain the KEY_ID.

  • ✓ All tests pass! Remember to run mvn verify -Prun-its to execute integration tests

  1. Update documentation

    Last commit before release should leave everything ready since it will be the last in the tag. The following changes to documentations must be done:

    • Update :release-version: attribute in README.adoc.

    • Add reference to the old README in the proper tag in the README.adoc introduction note.

    • Update version and release version in antora.yml.

    • Assign version to Unreleased section in CHANGELOG.

    • Look for TODO’s in docs that need to be made availabel for next release

  2. Prepare the release

    If you want to test this in your own github repo, replace the owner (asciidoctor) with your GitHub username in the <scm> section.

    Execute the prepare goal of the maven-release-plugin. You’ll have to adjust developmentVersion, releaseVersion and tag.

    $ mvn -B release:prepare

    If something fails during this step:

    • Run mvn release:rollback: this will undo changes locally and remove remote tag if it has been already created. But it will create another commit restoring original version.

    • Reset commits made by the plugin in your local repo and push force to remote to restore if necessary.

    • Check all previous steps and restart.

      This command will automatically increase the minnor version and create a tag named asciidoctor-maven-plugin-${release-version} by default this is OK. If custom version or tag is required, these can be set passing -DreleaseVersion=${version} or -Dtag=${tag-name}.

  3. Deploy to Maven Central

    Execute Maven’s deploy goal to publish in Maven Central

    $ mvn release:perform -Darguments="-Prelease-profile -DskipTests"
    • Depending on the OS and key management during the process you’ll be asked for your gpg passphrase. The same set in settings.xml.

    • You can add -DskipTests to -Darguments if everything has been checked before to speed up this step. Add -Pgpg if the profile is not activated by default.

    If something fails during this step, tags and prepare commits will be already pushed to asciidoctor repo. Rollback as explained in previous step and re-start.
    However, (not recommended) if the error was punctual (e.g. network) and everything is fine. Check code is correct, clone the newly created tag and deploy directly with mvn deploy -Prelease-profile.

  4. Synchronize with Maven Central

    If everything went fine, artifacts will be in a Staging Repository in

    Login with your account and push the "Close" button . Validations happen during this moment, so error can still occur. Check the "Activity" tab below for any hint on errors.

    If ok, an email is sent account owner.

    Finally, push the "Release" button to complete the process. Files will be publicly available in a few minutes.

  5. Create the release in GitHub.

⚠️ ** Fallback** ⚠️