Skip to content

The Central Repository

Jump to bottom
Brian Osborn edited this page Apr 4, 2024 · 7 revisions

This page documents the steps required to get your artifact into The Central Repository through Sonatype. The Sonatype guide is located here. Note that there is already an account set up for mil.nga, so you need to gain access to the existing project (instead of creating a new Sonatype project).

JIRA Account

Create a Sonatype JIRA Account

Sonatype Nexus Professional

After creating your account, you should be able to log into Sonatype Nexus Professional. This is where you will be able to see released and staged artifacts that you have uploaded. Note that when using Maven artifacts can be Released automatically. When using Gradle, artifacts must be pushed from the Staging Repository into Releases.

JIRA Ticket

Create a JIRA Ticket to gain access to the mil.nga group, noting that you need your account to be authorized to the existing project

PGP Key

Artifacts must be signed with a PGP key. Follow the Sonatype PGP page or the steps below:

  • Download and install GPG
  • Create Key, using defaults is fine. Use your name and email address, empty comment is fine:
    gpg --gen-key
  • List Keys to verify your key was created:
    gpg --list-keys
  • Note your key id using this example
  • Export key as armored ascii:
    gpg -a --export <email>@<address>.com > mykey.asc
  • Paste the full text key in mykey.asc to one or more keyserver sites trusted by Sonatype
    http://keyserver.ubuntu.com/
    https://pgp.mit.edu/
  • If you need to delete your key for some reason, delete the private and public key:
    gpg --delete-secret-key "Your Name”
gpg --delete-key "Your Name"

Build

POM

Your Maven or Gradle build should provide a POM file, either as a Maven pom.xml file or a generated pom through a Gradle build.gradle script. Your POM file must provide sufficient metadata

Source and Javadoc

You should configure your Maven or Gradle build to build and include the source code and Javadoc. See the example links below.

Maven

The Sonatype Maven guide is located here.

settings.xml

You will need a ~/.m2/settings.xml file with your GPG and JIRA information.

<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
                          http://maven.apache.org/xsd/settings-1.0.0.xsd">  
  <servers>
    <server>
      <id>gpg.passphrase</id>
      <passphrase>GPG_PASSWORD</passphrase>
    </server>
    <server>
      <id>ossrh</id>
      <username>JIRA_USERNAME</username>
      <password>JIRA_PASSWORD</password>
    </server>
  </servers>
</settings>

Example

For a Maven example, see one of the GeoPackage pom.xml files:
https://github.com/ngageoint/geopackage-wkb-java/blob/master/pom.xml
https://github.com/ngageoint/geopackage-core-java/blob/master/pom.xml
https://github.com/ngageoint/geopackage-java/blob/master/pom.xml

Publish

To publish the artifacts to the central repository, run the Maven deploy command

mvn clean deploy

Gradle

The Sonatype Gradle guide is located here.

gradle.properties

You will need properties in your ~/.gradle/gradle.properties file with your GPG and JIRA information.

ossrhUsername=JIRA_USERNAME
ossrhPassword=JIRA_PASSWORD

signing.keyId=GPG_KEY_ID
signing.password=GPG_PASSWORD
signing.secretKeyRingFile=/Users/USER_NAME/.gnupg/secring.gpg

Example

For a Maven example, see the GeoPackage Android build.gradle file:
https://github.com/ngageoint/geopackage-android/blob/master/geopackage-sdk/build.gradle

Publish

Using the example build.gradle, change the remotePublish variable to true. Then run the uploadArchives Gradle task.

Release

Follow the Sonatype releasing the deployment instructions or the steps below:

  • Log into Sonatype Nexus Professional and find the new repository under Staging Repositories.
  • Click on the repository and verify things look correct
  • Click Close when the repository is selected
  • Once the repository has successfully processed, click Release to release it

Post Release

From the Sonatype guide:

"Upon release, your component will be published to Central: this typically occurs within 10 minutes, though updates to "search:https://search.maven.org/ can take up to two hours."

Update your pom.xml or build.gradle versions as needed so the next release is correct and doesn't override the version in the repository.

Java Libraries

Recommended steps for releasing a Java Maven repository

  • Update any dependencies needed in pom.xml
  • Update CHANGELOG.md with release version, URL, date, and changes made
  • Update README.md with new release version
  • Update docs/index.html with new release version
  • Verify build and run tests
    • mvn clean install
  • Commit all changes to sub branch (such as develop)
  • Verify GitHub Actions workflows pass for sub branch
  • Merge sub branch to master branch
  • Verify GitHub Actions workflows pass for master branch
  • Publish the library
    • mvn clean deploy
  • Update the Javadoc
    • Grab the <library>-<version>-javadoc.jar from the deploy build or Maven Central Repository
    • Replace the Javadoc under docs/docs/api and commit to master
  • Create a new GitHub release for the version using previous versions as a template
    • Attach the Maven Central Repository artifacts to the release
      • <library>-<version>-javadoc.jar
      • <library>-<version>-sources.jar
      • <library>-<version>.jar
      • <library>-<version>.pom
    • If the library has standalone jar(s) and/or utilities, retrieve them from the GitHub Actions workflow and attach
      • <library>-<version>-standalone.jar
      • <name>.zip
  • Set up the next version
    • Update the pom.xml next version
    • Add the next version to CHANGELOG.md
    • Commit to master
    • Merge master down to development branch such as develop

Android Libraries

Recommended steps for releasing an Android Maven repository

  • Update any dependencies needed in build.gradle and <name>/build.gradle
  • Update CHANGELOG.md with release version, URL, date, and changes made
  • Update README.md with new release version
  • Update docs/index.html with new release version
  • Verify build and run tests in Android Studio
  • Commit all changes to sub branch (such as develop)
  • Verify GitHub Actions workflows pass for sub branch
  • Merge sub branch to master branch
  • Verify GitHub Actions workflows pass for master branch
  • Publish the library
    • Run the publish gradle task
    • Log into Sonatype
    • Go to Staging Repositories and Refresh
    • View and Close the published repository
    • Wait for the Repository to close and then Release it w/ Automatically Drop enabled
  • Update the Javadoc
    • Grab the <library>-<version>-javadoc.jar from Sonatype or Maven Central Repository
    • Replace the Javadoc under docs/docs/api and commit to master
  • Create a new GitHub release for the version using previous versions as a template
    • Attach the Maven Central Repository artifacts to the release
      • <library>-<version>-javadoc.jar
      • <library>-<version>-sources.jar
      • <library>-<version>.aar
      • <library>-<version>.pom
      • <library>-<version>.module
    • If the library has an apk, retrieve from the GitHub Actions workflow and attach
      • <name>.apk
  • Set up the next version
    • Update the <name>/build.gradle next version
    • Add the next version to CHANGELOG.md
    • Commit to master
    • Merge master down to development branch such as develop
Clone this wiki locally