Adopt GHA Scala Library Release Workflow

[rtyley]

This is the second library (after etag-caching), to adopt guardian/gha-scala-library-release-workflow . This is a new automated library release process, which means that a new library release can be published to Maven Central with the click of a button:

This replaces the old release process which had developers manually running sbt release on their own laptops - each developer had to obtain their own PGP key and Sonatype credentials, which was an elaborate setup process. Now, there is one single set of credentials, available through GitHub Organisation Secrets, like we already do with NPM.

Required changes

The changes required to adopt the automated workflow:

• No need to set sonatypeProfileName or ThisBuild / publishTo, that's now done by the workflow.
• Remove the sign, publish, release & push steps of sbt-release's releaseProcess configuration, because the workflow does those now, and the workflow only wants sbt release to create the versioning commits, and tag them appropriately. The workflow does the rest itself.
• Remove sbt-pgp plugin because it's no longer used - the workflow does the signing using gpg directly.
• GitHub administration: Grant this repo (play-secret-rotation) access to these two GitHub Organisation Secrets (probably requires Organisation Owner privileges):
  • AUTOMATED_MAVEN_RELEASE_PGP_SECRET &
  • AUTOMATED_MAVEN_RELEASE_SONATYPE_PASSWORD:

Additionally, we add automatic version numbering based on compatibility assessment performed by sbt-version-policy:

• Add the sbt-version-policy plugin, to allow it to do the compatibility assessment. This also sets the versionScheme for this library to early-semver, which is the recommended versioning for Scala libraries, and sbt-version-policy and correct sbt-eviction-issue-detection pretty much depend on the versionScheme being early-semver. Thus we also need to switch to using a new semver version number for our library version!
• Add the releaseVersion := fromAggregatedAssessedCompatibilityWithLatestRelease().value sbt setting, which will intelligently set the release version based on sbt-version-policy's compatibility assessment, thanks to Simplify integration with sbt-release scalacenter/sbt-version-policy#187 .
• Use publish / skip := true, rather than other hacks like publish := {} or publishArtifact := false, to tell sbt not to publish modules that we don't want published (typically, the 'root' module) - this is important because sbt-version-policy won't understand those hacks, but will understand publish / skip := true means that it doesn't need to assess compatibility there.

[DavidLawes]

Are we saying that, when we merge this change, we can run the release workflow and it will build/deploy version 1.0.0? I suppose this means that, in the case where we're using this new plugin, the version.sbt file is the source of truth for the next version?

[DavidLawes]

Also, I created this project, should I be updating it to use this new plugin? (it's configured with my own sonatype username and password at the moment....)

[rtyley]

we can run the release workflow and it will build/deploy version 1.0.0? I suppose this means that, in the case where we're using this new plugin, the version.sbt file is the source of truth for the next version?

That's right! Actually, I don't think that's a change from the existing behaviour for version numbers - the workflow hasn't changed things here. You can think of '-SNAPSHOT' as meaning '-SNAPSHOT-PREVIEW', so 1.0.0-SNAPSHOT is actually a 'preview' release of 1.0.0 before it's actually finished and released. This is standard Maven release versioning - we always work with the version number set to a snapshot of what the next release will be.

I created this project, should I be updating it to use this new plugin? (it's configured with my own sonatype username and password at the moment....)

Well, at the moment, gha-scala-library-release-workflow is in an early-feedback phase - I'd like it tried out on just a small number of repositories, so people can give me feedback to incorporate before we update all the Scala library repos at the Guardian!

If you'd like to try out updating https://github.com/guardian/mobile-apps-api-models to work with the new flow, that would be absolutely wonderful, you'd be being an awesome beta-tester!

[DavidLawes]

Thanks for the explanation - in the mapi-models project I discarded the use of version.sbt (in favour of the user defining this via the github release UI) so it's good to see how the release process can integrate with this file (which is a mechanism that feels neater).

[rtyley]

Yeah, it's an interesting choice to make, whether to initiate by creating a GitHub release, which is beautiful and elegant, but requires there to already be a tag, with some random human-chosen version number, or to initiate by running the workflow with workflow-dispatch, which is not quite as beautiful, but doesn't require there to be an already-existing tag... I've gone with the second one!

[DavidLawes]

Good to know we have org-wide secrets for maven releases now!

[rtyley]

Good to know we have org-wide secrets for maven releases now!

Yeah! Though those credentials should only be used with gha-scala-library-release-workflow, and not other setups which have less isolation between executing library code and the credentials!

[rtyley]

This did successfully do a release for this library!

However, it took a few attempts, because of two things I'd forgotten were also required:

• I had to add access to the two secrets (this will eventually be done using https://github.com/guardian/github-secret-access?tab=readme-ov-file#addingremoving-access-to-a-secret)
• I had to disable branch protection, which was blocking the workflow from pushing directly to main without the tests passing first :-( This might be best fixed by using a GitHub App bot user to make the push, and then specifically only allowing the bot user to bypass branch protection.