Development CenterJava Product Release Process

Java Product Release Process

Please note, because of a bug in Java 11 and some versions of 12, build Site using a version of Java > 12 (see JPAR-162), otherwise the search bar of the API docs will not work correctly

Java Product Release Process

This document describes the process that the Shibboleth team uses to package up and release a new version of our Java software products.

Release Environment

All our Java products use Maven to perform the actual build of release artifacts. Those artifacts are then uploaded to our Nexus installation at Site builds, which importantly contain the API docs, are uploaded by SCP to, and served by apache at

Initial Configuration

Prior to performing any releases a few one-time configurations need to be done.

  1. Ensure that you have the proper data in your ~/.m2/settings.xml file.

  2. Generate an SSH key for both Git and Site deploys.

  3. Generate a PGP key and get it signed by the other developers. To avoid use of SHA-1 use the following in your gpg.conf file:

    personal-digest-preferences SHA512 cert-digest-algo SHA512 default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed
  4. Send the public SSH and PGP keys to committers email list with a request to be allowed to perform releases. 

A systems admin will then:

  1. Log in to Nexus and go the Security -> Users -> Add -> External User Role Mappingscreen

    1. Enter the user's LDAP uid as their user name (same userid they use for SVN)

    2. In the Role Management section, add the role Nexus Deployment and save the user account

  2. Add an account for you on the server, set your SSH key as an authorized key, and allow you to su to the Shibboleth website user.

    1. Add your key to the 'javasites' user, so that you can perform site releases. 

  3. Add your GPG key to the KEYS file on the download site

Parent POM Adjustment

In most cases, a major or minor release will involve tagging a new version of the parent POM and updating all projects to depend on it. The parent should not be updated for patch releases, this can cause Maven import confusion given that dependent projects (e.g. opensaml) will be referencing the older parent - see JPAR-175. Generally, for a given release, all projects should reference the same parent. If library updates are required for a patch release, you will need to override the dependencies in the appropriate project POMs. When in doubt, ask.

  1. Ensure that your working copy is in sync with the project repository (i.e., pull down any updates and commit any local changes).

  2. If not done, tag the parent POM to freeze the parent so it can be referenced by the subsequent steps. The tag version is a single, monotonically-increasing number.

    1. The tagging process for this is identical (bar the project and versions) to the release process described in the section below.

  3. Run the command java-parent-project-v3/bin/ (for a monolithic project} or java-parent-project-v3/bin/ (for a multi-module project). The arguments are the parent POM tag number, and the path to the project.

    # Lock java-support against tag version 11 of V4 parent java-parent-project-v3/bin/ 11 java-support


  4. After verifying the project's build using the newly referenced parent POM, commit the project changes.

Release Process

  1. Ensure you are using the correct Java version e.g. Amazon Corretto 11.

    1. If you are building the IdP, make sure you set MAVEN_HOME to the bin directory of your maven installation so the distribution-dependency-test runs correctly in idp-installer.

  2. Ensure that your working copy is in sync with the project repository (i.e., pull down any updates and commit any local changes). It can be useful to do this from scratch from a temporary folder, possibly inside a clean docker container. For example, into the temp directory, using a fresh maven repo location.


      # incase you get issues connecting to the GPG agent. export GPG_TTY=$(tty) # somewhere to store a fresh maven repo. If you want to preserve the transient release repo for archiving, etc, # use a permanent location for REPO, with the version in the name. export REPO=/tmp/repo cd /tmp git clone<project> cd <project> git checkout main
  3. Check that a non snapshot version of maven-dist-enforcer and maven-dist-enforcer-data are used.

  4. Check the .check-m2 file is in the projects distribution project.

  5. Check the project builds, all the test pass, and the artifacts are produced correctly (signed in their target directories):

    1. mvn -Dmaven.repo.local=$REPO -Prelease,sign clean verify
    2. OPTIONALLY: If you want to manually inspect the signature report on the contents of the populated m2 directory, you need to use the install phase e.g.

      1. mvn -Dmaven.repo.local=$REPO -Prelease,sign clean install then vi target/m2SignatureReport.txt . This is automatically checked on deploy, so is not required.

  6. Set the project version number in the POM to the release version number using the command below. Also, ensure you update versions of any dependencies on our own projects that should be shipped with the release.

    1. mvn -Dmaven.repo.local=$REPO -DgenerateBackupPoms=false -DnewVersion=4.Y.Z versions:set
  7. Once satisfied, tag the release using a name equal to the version number of the release (e.g., 4.1.4 etc.) and ensure the POM at the tip of the branch being released NEVER contains a non-SNAPSHOT version number.

    1. # Be sure there are SNAPSHOTs in the right places. So from the root directory of the project: find . -name 'pom.xml' -exec grep SNAPSHOT {} \; # Check status git status # Confirm changes manually git diff # Assume working copy is on branch 'main', with ONLY tag-specific changes pending # (e.g. non-SNAPSHOT version) # Add the changes git add -A # Confirm changes have been added git status # Commit the changes to be tagged to the HEAD of the branch git commit -m "Update files to be tagged for release" # Create a signed, annotated tag from HEAD git tag -s -m "Tag 4.Y.Z release" 4.Y.Z # Edit pom.xml to update the version to X.Y.Z+1-SNAPSHOT (in the example, 4.1.5-SNAPSHOT). mvn -Dmaven.repo.local=/tmp/repo-release versions:set -DnewVersion=4.Y.Z+1-SNAPSHOT -DgenerateBackupPoms=false # Commit the pom.xml change. git add -A git commit -m "Bump version after release" # Push the new commits. git push # Do not push the tag. Signature checking is more restrictive for non SNAPSHOT builds
  8. Checkout or export the tag to build the final release:

    1. git checkout 4.Y.Z mvn -Dmaven.repo.local=$REPO -DskipTests -Prelease,sign clean deploy
  9. After the build has completed push the tag

    # Push the new tag (no easy backout when the tag is pushed!) git push origin 4.Y.Z
  10. At this stage, DO NOT make any changes to fix errors without increasing the version again. This commits you to a release and you cannot go back.

  11. Mark the version as released in Jira.

Site Release Process

You MUST use a separate local repo for the site build and deploy step to avoid polluting the repo with jars that will not pass the enforcer check.

  1. Ensure you have your SSH key configured in your ~/.m2/settings.xml file for the site server element. The username must be javasites, and hence the public part of your key must be in the authorized keys of the javasites user on the server (as described in Initial Configuration above).


      <server> <id>site</id> <username>javasites</username> <privateKey>${user.home}/.ssh/id_rsa</privateKey> <passphrase>passphrase</passphrase> </server>
  2. Build and deploy the site image. Note, due to a bug in Java 11, you should build Site using a version of Java > 12 (see JPAR-162), otherwise the search bar of the API docs will not work correctly.


      # Checkout the branch (if you are not already on it) git checkout 4.Y.Z # Build and deploy site (currently uses SCP) mvn -Dmaven.repo.local=$REPO -DskipTests site site:stage site:deploy
  3. Site deploys via SCP to /home/javasites/staging/<project>/<version>. SNAPSHOTS remain in the staging directory, but RELEASES should be moved into the /home/javasites/release directory. You should not attempt to copy the directory manually as the releases directory uses squashfs to compress its content. Instead, log in to the Shibboleth webserver and run the following script:


      # this will unmount, squash, and remount the projects directory. sudo /usr/local/sbin/ <project> <version> # for example sudo /usr/local/sbin/ java-identity-provider 4.1.4
  4. The project remains in the /staging/ directory. If you are happy the script has run successfully, you can ‘purge’ all non-snapshots from the staging directory using:


      # Note, this purges all non-snapshots from the staging dir, and so could be run at the end of a multi-project # release to cleanup all staged releases. sudo /usr/local/sbin/

Final Steps

  1. For top-level projects (IdP): Place the product distribution in the download section of the website by:

    1. Log in to the Shibboleth webserver

    2. Copy and rename the distribution archives and PGP signatures from the Nexus work directory to a temporary location e.g. your home directory


        VERSION=4.X.Y cp -v /home/nexus/sonatype-work/nexus/storage/releases/net/shibboleth/idp/idp-distribution/$VERSION/idp-distribution-$VERSION.tar.gz shibboleth-identity-provider-$VERSION.tar.gz cp -v /home/nexus/sonatype-work/nexus/storage/releases/net/shibboleth/idp/idp-distribution/$VERSION/idp-distribution-$VERSION.tar.gz.asc shibboleth-identity-provider-$VERSION.tar.gz.asc cp -v /home/nexus/sonatype-work/nexus/storage/releases/net/shibboleth/idp/idp-distribution/$VERSION/idp-distribution-$ shibboleth-identity-provider-$ cp -v /home/nexus/sonatype-work/nexus/storage/releases/net/shibboleth/idp/idp-distribution/$VERSION/idp-distribution-$ shibboleth-identity-provider-$
    3. Create SHA256 checksums for both the zip and tar file


        sha256sum shibboleth-identity-provider-$VERSION.tar.gz > shibboleth-identity-provider-$VERSION.tar.gz.sha256 sha256sum shibboleth-identity-provider-$ > shibboleth-identity-provider-$ # Confirm the checksums are correct sha256sum -c shibboleth-identity-provider-$VERSION.tar.gz.sha256 sha256sum -c shibboleth-identity-provider-$
    4. Create a suitable version-named directory on the download site and copy in the distribution, signatures, and checksums:


        sudo mkdir -v -p /home/shibwww/html/downloads/identity-provider/.$VERSION sudo cp -v -p shibboleth-identity-provider-$VERSION* /home/shibwww/html/downloads/identity-provider/.$VERSION/ sudo chown -v -R shibwww:shibwww /home/shibwww/html/downloads/identity-provider/.$VERSION
    5. Copy in the Windows installers (which are created separately) - note these are being sources from Rod’s home directory, so the path needs checking.


        sudo sh -c "cp -v /home/rdw/shibboleth-identity-provider-$VERSION-x64/shibboleth-identity-provider-$VERSION-x64.msi* /home/shibwww/html/downloads/identity-provider/.$VERSION/" sudo chown -R shibwww:shibwww /home/shibwww/html/downloads/identity-provider/.$VERSION/ sudo chmod -R g-w /home/shibwww/html/downloads/identity-provider/.$VERSION/
    6. Adjust the latest sym-link to point to the new version.

  2. For top-level projects:

    1. Update the relevant product's ReleaseNotes topic with the new release, the date, a link to a JIRA issue filter that produces the appropriate list of issues, and any important information about issues addressed, advisories, special requirements during upgrades, etc.

    2. Send an announcement to Optionally sign the email with your PGP key.

    3. Update the "latest stable version" mentioned on the front page of the wiki space for the relevant product.

  3. For releases that include one or more Security Advisories:

    1. Finalize each advisory and fill in the date, double check any footnotes and URLs for correctness, and finalize the filename of the advisory based on the date and correct the self-referential link to the advisory in the text. See previous advisories for examples.

    2. Sign the advisory in text form with a PGP key that's in the project's PGP_KEYS file.

    3. Place the signed advisory on the server in /home/shibwww/html/community/advisories in a file named secadv_YYYYMMDD.txt and ensure appropriate ownership and 644 file mode.

    4. Send the PGP-signed advisory to (see previous examples in the archive).

    5. Update the relevant SecurityAdvisories page in the wiki space for an IdP advisory. The page includes a tabular display of all the advisories and links, and a table listing releases and how the advisories affect them.

Example using Docker

The attached script has been used to build a specific project inside the Shibboleth Docker Environment

Docker itself is started (this is on Windows) by this command

docker run -i -t --rm --name shibboleth-build --hostname amazon11 --volume=%userprofile%\shibboleth-build-docker\user:/home/user ianayoung/shibboleth-build-docker:amazon11

The %userprofile%\shibboleth-build-docker\user directory was configured as noted above and the the docker Docker Environment Documentation

Windows Installer


This is described separately.