Common Workflows

This repository provides common workflows to be used as GitHub Actions.

• Maven Build
  • Inputs
  • How to use it?
  • Troubleshooting the build
• Maven Central Deploy
  • Requirements
  • Inputs
  • How to use it?
• Maven Central Release
  • Requirements
  • Inputs
  • How to Use It?
  • Troubleshooting

Maven Build

The maven-build.yml workflow simply builds a Maven project with the mvn verify site phases. It's designed to be invoked on push on PRs, so that this action is considered as a Check on the PR, i.e. it will prevent the build from being merged if the build fails. Produced reports such as checkstyle, PMD and spotbugs will then be added as comments on pull-request.

Inputs

Input	Description	Default value
jdkVersion	Version of the JDK to setup to run Maven. See supported syntax.	17
nodeVersion	Version of the NodeJS to setup for this project. Optional (if not specified, NodeJS won't be installed). See supported syntax.	None
debug	Whether to run Maven in debug mode (with -X option)	`"false"
ssh	Whether to open a SSH session in the GitHub Actions runner, to let you interact with the system that performed the build. SSH session automatically closes after 10 minutes of inactivity.	"false"
uploadCheckstyleReport	Whether to upload any Checkstyle report created by Maven	"true"
uploadPMDReport	Whether to upload any PMD report created by Maven	"true"
uploadSpotbugsReport	Whether to upload any Spotbugs report created by Maven	"true"

How to use it?

To use this workflow, you must define a job that uses: sentrysoftware/workflows/.github/workflows/maven-build.yml@main.

Important

Instead of @main, it is recommended to use an actual version, to avoid breaking your build if the workflow required inputs change in the future, like @v1.

To run this workflow as an automatic check in the PRs or a repository, and also allow users to trigger the workflow manually (with debug options), create a .github/workflows/build.yml with the below content:

name: Maven Buildon:
# Run on all PRs to "main" (update to include the protected branches of your repository)pull_request:
branches: [ "main" ]# Run the workflow manuallyworkflow_dispatch:
inputs:
debug:
type: booleandescription: Maven debug moderequired: falsedefault: falsessh:
type: booleandescription: Open SSH session in the runnerrequired: falsedefault: falseuploadCheckstyleReport:
type: booleandescription: Upload Checkstyle report created by Mavenrequired: falsedefault: trueuploadPMDReport:
type: booleandescription: Upload PMD report created by Mavenrequired: falsedefault: trueuploadSpotbugsReport:
type: booleandescription: Upload Spotbugs report created by Mavenrequired: falsedefault: truejobs:
build:
# Call this shared workflow (use `@v1` to use a specific version, instead of the latest)uses: sentrysoftware/workflows/.github/workflows/maven-build.yml@mainwith:
jdkVersion: "17"nodeVersion: "20.x"debug: ${{ github.event_name == 'workflow_dispatch' && inputs.debug }}ssh: ${{ github.event_name == 'workflow_dispatch' && inputs.ssh }}uploadCheckstyleReport: ${{ inputs.uploadCheckstyleReport }}uploadPMDReport: ${{ inputs.uploadPMDReport }}uploadSpotbugsReport: ${{ inputs.uploadSpotbugsReport }}

Troubleshooting the build

In case of a build failure, the standard output of Maven may not be sufficient to troubleshoot the build.

Debug mode

To enable Maven's debug mode (-X or --debug option), simply re-run the workflow manually on the branch you need (typically the branch of your PR), with the Maven debug mode option set to true (check the corresponding box).

SSH in the Runner

Sometimes even the debug output of Maven is not enough to understand what is wrong with your build. You may want to check some files yourself, or execute some commands in the build Runner itself. This is possible with the Open SSH session in the runner option.

When enabled, this option starts an SSH daemon in the Runner at the beginning of the build. You can open a session either with your favorite SSH client, or using the built-in Web client. Instructions to connect to the Runner are provided in the output of the build, with repeated messages.

The SSH daemon prevents the build from completing, and wait for the user to open a session for 10 minutes. After a period of 10 minutes of inactivity (no session open, no interaction), the SSH daemon is automatically closed and the build completes.

Maven Central Deploy

The maven-central-deploy.yml workflow builds a Maven project and deploys its artifacts to Maven Central SNAPSHOT repository. It is designed to be invoked on push on the main branch of the repository, so the SNAPSHOT version built from the main branch can be used by other projects as a dependency. Basically, the project is built with the mvn deploy command.

Important

This workflow is NOT designed to deploy release versions of the artifact to Maven Central repositories, as it doesn't fulfill the requirements for Maven Central (signatures, etc.).

The workflow also updates the dependency tree for dependabot.

Requirements

The Maven Central SNAPSHOT repository must be specified in the <distributionManagement> section of the project's pom.xml, with <id>central</id>:

 <distributionManagement>
<snapshotRepository>
<id>central</id>
<url>https://central.sonatype.com/repository/maven-snapshots/</url>
</snapshotRepository>
</distributionManagement>

The below secrets must be declared in the repository or the GitHub organization:

Secret	Description
MAVEN_CENTRAL_USERNAME	Maven Central User Token name
MAVEN_CENTRAL_TOKEN	Corresponding User Token

Inputs

Input	Description	Default value
jdkVersion	Version of the JDK to setup to run Maven. See supported syntax.	17
nodeVersion	Version of the NodeJS to setup for this project. Optional (if not specified, NodeJS won't be installed). See supported syntax.	None

How to use it?

To use this workflow, you must define a job that uses: sentrysoftware/workflows/.github/workflows/maven-central-deploy.yml@main.

Important

Instead of @main, it is recommended to use an actual version, to avoid breaking your build if the workflow required inputs change in the future, like @v1.

To run this workflow automatically on the main branch, create a .github/workflows/deploy.yml with the below content:

name: Maven Deployon:
push:
branches: [ "main" ]jobs:
deploy:
uses: sentrysoftware/workflows/.github/workflows/maven-central-deploy.yml@mainwith:
jdkVersion: "17"nodeVersion: "20.x"secrets: inherit

Maven Central Release

The maven-central-release.yml workflow performs all the necessary actions to release a Maven project to Maven Central, hosted by Sonatype.

This workflow must be triggered manually and run from the main branch of the project, and will perform the below actions:

• Create and checkout a release/vX.Y.Z branch
• Prepare the release with maven-release-plugin:prepare, which itself will:
  • Check there are no SNAPSHOT dependencies
  • Update pom.xml with the release version (releaseVersion input, non-SNAPSHOT)
  • Build the project and site, and run all tests with mvn clean verify site
  • Commit and tag as vX.Y.Z
  • Update pom.xml again with the new development version (developmentVersion input, SNAPSHOT)
  • Build the project again
  • Commit the changes
• Perform the actual release with maven-release-plugin:perform
  • Checkout the vX.Y.Z in a temporary folder (target/release)
  • Build the project with mvn deploy
  • Note: The deploy phase is "enhanced" with the central-publishing-maven-plugin Maven plugin
  • Sign the artifacts with GPG
  • Deploy artifacts in Maven Central repository (the artifacts are not publicly available, at this stage, until the artifacts are manually published)
  • Publish the artifacts immediately only if autoRelease input is true
• Update the site (target/site/*) to GitHub Pages
• Create a GitHub Release with the produced artifacts
• Create a Pull Request from the release/vX.Y.Z branch to main
• Deploy the GitHub Pages

Requirements

The below secrets must be declared in the GitHub repository or the GitHub organization:

Secret	Description
MAVEN_CENTRAL_USERNAME	Maven Central User Token name
MAVEN_CENTRAL_TOKEN	Corresponding User Token
MAVEN_GPG_PRIVATE_KEY	The GPG private key to sign the artifacts
MAVEN_GPG_PASSPHRASE	The associated passphrase

Additionally, the pom.xml must declare a releaseprofile, to declare a few custom phases for the release, as below:

 <profile>
<id>release</id>
<build>
<plugins>
<!-- gpg to sign the released artifacts -->
<plugin>
<artifactId>maven-gpg-plugin</artifactId>
<executions>
<execution>
<id>sign-artifacts</id>
<phase>verify</phase>
<goals>
<goal>sign</goal>
</goals>
<configuration>
<updateReleaseInfo>true</updateReleaseInfo>
<gpgArguments>
<arg>--pinentry-mode</arg>
<arg>loopback</arg>
</gpgArguments>
</configuration>
</execution>
</executions>
</plugin>
<!-- nexus-staging (Sonatype) -->
<plugin>
<groupId>org.sonatype.central</groupId>
<artifactId>central-publishing-maven-plugin</artifactId>
<extensions>true</extensions>
<configuration>
<publishingServerId>central</publishingServerId>
<autoPublish>${env.AUTO_RELEASE_AFTER_CLOSE}</autoPublish>
<waitUntil>published</waitUntil>
</configuration>
</plugin>
<!-- release -->
<plugin>
<artifactId>maven-release-plugin</artifactId>
<configuration>
<tagNameFormat>v@{project.version}</tagNameFormat>
</configuration>
<executions>
<execution>
<id>default</id>
<goals>
<goal>perform</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>

Inputs

Input	Description	Default value
releaseVersion	Version to release (will be set in pom.xml for this release)	None
developmentVersion	Version of the new SNAPSHOT version (will be set in pom.xmlafter the release)	None
autoRelease	Whether to make the deployed artifacts publicly available on Maven Central immediately	false
jdkVersion	Version of the JDK to setup to run Maven. See supported syntax.	17
nodeVersion	Version of the NodeJS to setup for this project. Optional (if not specified, NodeJS won't be installed). See supported syntax.	None

How to Use It?

To use this workflow, you must define a job that uses: sentrysoftware/workflows/.github/workflows/maven-central-release.yml@main.

Important

Instead of @main, it is recommended to use an actual version, to avoid breaking your build if the workflow required inputs change in the future, like @v1.

To be able to trigger this workflow manually, create a .github/workflows/release.yml with the below content:

name: Release to Maven Centralrun-name: Release v${{ inputs.releaseVersion }} to Maven Centralon:
workflow_dispatch:
inputs:
releaseVersion:
description: "Release version"required: truedefault: ""developmentVersion:
description: "New SNAPSHOT version"required: truedefault: ""jobs:
release:
uses: sentrysoftware/workflows/.github/workflows/maven-central-release.yml@mainwith:
releaseVersion: ${{ inputs.releaseVersion }}developmentVersion: ${{ inputs.developmentVersion }}autoRelease: truejdkVersion: "17"nodeVersion: "20.x"secrets: inherit

To trigger the release workflow, select it in the Actions tab, and use the Run workflow button. You'll be required to manually enter:

• Release version: the version that will be released (pom.xml will be updated accordingly before the release)
• New SNAPSHOT version: the new development version, ending with -SNAPSHOT (pom.xml will be updated after the release in a dedicated Pull Request)

The workflow performs several builds (so it may take some time to complete).

If the workflow completes successfully, you will need to perform 2 additional tasks:

1. Login to Maven Central, and Publish the artifacts bundle that has been deployed by the workflow. This operation has already been performed if the workflow was called with autoRelease: true.
2. Approve and merge the Pull Request that has been created by the workflow (for the release/vX.Y.Z branch)

Troubleshooting

Failure during Prepare Release

If the workflow fails during the Prepare Release step, check the output of maven-release-plugin. While preparing the release, a few validation checks are performed (e.g. the presence of SNAPSHOT dependencies) and will fail the build if necessary.

Failure during Perform Release

If the workflow fails while trying to close the repository on Sonatype's Maven Central repository, it probably means the artifacts don't comply with the validation rules for Maven Central.

Failures with GitHub Pages

The GitHub repository must be configured to publish GitHub Pages through GitHub Actions.

Retrying a release

In case of a release failure that doesn't require updating the code, you can simply restart the workflow. The release/vX.Y.Z branch and the vX.Y.Z tag will be reset properly by the workflow, so you don't have to worry about these.

If the code needs to be updated, you will need to push changes to the main branch (from which the release workflow is executed). Don't use bugfix/ branches on the release/vX.Y.Z branch. Then re-execute the release workflow from the updated main branch.