Maven: signing artifacts for release to maven central

maven gpg instructions.md

These instructions cover the following topics

• Generating/updating GPG keys
• Publishing GPG keys
• Adding GPG keys to GitHub
• Using GPG keys to sign git commits
• Using GPG keys to sign maven artifacts
• Publishing maven artifacts to OSSRH (Open Source Software Repository Hosting)

It's recommended to also read the following documentation

• https://central.sonatype.org/publish/publish-guide/
• https://central.sonatype.org/publish/requirements/gpg/

It's presumed the reader has already registered and has access to both https://oss.sonatype.org and https://github.com

Aligning you publicly used email

Your email will be used in multiple places throught this journey. It makes sense to have a single valid email address that can be used accross all of the following:

• GitHub account (primary email)
• git commits (either global default or set for any projects that will be published)
• developer details in maven pom.xml for any published projects
• gpg key
• sonatype account

Generating a GPG key

note that depending on the system used the command could be gpg or gpg2

Get started by generating a new key (note that if you've previously done this you may want to renew existing rather than create a new one):

gpg2 --gen-key

enter your name/email and use defaults for the rest.

Update an existing key

Using gpg --list-keys you can view esiting keys and then edit a particular key by it's id:

gpg --edit-key <YOUR KEYS ID HERE>

You will be promted to enter the passphrase for the key, then you'll be able to extend the time left on the key and save it. After updating a GPG key it will need to be published again and you'll need to update it on GitHub.

Publishing GPG keys

You'll need to know the ID for the key you wish to publish. Once published it can take time for your public key to be propergated. It's worth publishing to multiple servers:

gpg2 --send-keys <YOUR KEYS ID HERE>
gpg2 --keyserver keyserver.ubuntu.com --send-keys <YOUR KEYS ID HERE>
gpg2 --keyserver keys.openpgp.org --send-keys <YOUR KEYS ID HERE>
gpg2 --keyserver hkp://pgp.mit.edu --send-keys <YOUR KEYS ID HERE>
gpg2 --keyserver hkp://pgp.surf.nl --send-keys <YOUR KEYS ID HERE>

Adding GPG keys to GitHub

To view public key in ASCII (for adding to github) use:

gpg --armor --export <YOUR KEYS ID HERE>

then in github settings copy the output and paste it into the text box in GitHub. If you need to update an existing key simply delete the relevant key from GitHub and add the output of the export command in the same way you would a new key.

Using GPG keys to sign git commits

Now, assuming your email address in ~/.gitconfig is the same as the email in your GPG key, you can configure git globally to sign all your commits:

git config --global commit.gpgsign true

You'll need to enter the passphrase for your GPG key when creating a commit. You can also sign an individual commit using the -S option. See: https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits

Using GPG keys to sign maven artifacts

Make sure the maven-gpg-plugin is in the build > plugins section of your pom.xml (potentially under a profile for release or ossrh). Make sure that your ~/.m2/settings.xml, or equivelant for GitHub actions, has the passphrase for your key configured:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      https://maven.apache.org/xsd/settings-1.0.0.xsd">

  <servers>
    <server>
      <id>ossrh</id>
      <username>**********</username>
      <password>************************************</password>
    </server>
  </servers>

  <profiles>
        <profile>
            <id>ossrh</id>
            <activation>
                <activeByDefault>false</activeByDefault>
            </activation>
            <properties>
                <gpg.executable>gpg2</gpg.executable>
                <gpg.passphrase>***************</gpg.passphrase>
            </properties>
        </profile>
  </profiles>

</settings>

You can specify the ID for the key to use in the configuration of the maven-gpg-plugin but it's worth using a variable as the GPG key could be different depending on whether you have multiple machines/users publishing artifacts.

Publishing maven artifacts to OSSRH (Open Source Software Repository Hosting)

Assuming everything else is configured correctly you can do a maven deploy using the profile, eg: mvn clean deploy -Possrh. Remember, if you intend to support multiple JDK versions (and for artifacts on maven central you should), the artifact should be built with the minimum support JDK (I typically use the latest stable JDK but build my releases with Java 1.8 or 11 for greater compatibility).

After the artifact has uploaded go to the staging repo at https://oss.sonatype.org/#stagingRepositories, find the artifact then click "close" (not very intuitive) and wait for it to be releasable (this could be 20 minutes). Eventually you will have a new option for "release", click this then wait again. Sometimes this can take significantly longer, I've waited about an hour at times to be able to pull artifacts that I've published to the central repo.