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
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
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.
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.
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>
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.
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
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.
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.