configuration.md

Configuration

Start here if you're setting up a repo use gha-scala-library-release-workflow! If your organisation has never used gha-scala-library-release-workflow before, you'll need to follow the instructions in Organisation Setup first.

The release workflow needs a release.yml GitHub workflow in your repo, and specific updated sbt settings.

Example GitHub pull requests making these changes can be found further below.

Repo settings

• Ensure your GitHub App has access to your repo. Guardian developers: click Configure on the gu-scala-library-release app - so long as you have admin permissions on your repo, you should be able to add your repo to the list of selected repositories.
• Guardian developers: Comply with the repository requirements of guardian/github-secret-access, i.e. ensure the repository has a production Topic label.

Branch protection

Your GitHub App will need to push to directly to your default branch as part of the release, bypassing any branch protection. GitHub provides two different methods of branch protection:

• Branch protection rules - there is no mechanism to allow a GitHub App to bypass branch protection rules, so you'll need to remove any rules that apply to the default branch.
• Branch protection rulesets - rulesets can be configured to allow specified GitHub Apps (e.g. your GitHub app) to bypass branch protection - update your rulesets accordingly. Guardian developers: see recommended branch protection rulesets.

GitHub workflow

Example .github/workflows/release.yml

The functionality of gha-scala-library-release-workflow is provided in a reusable workflow called reusable-release.yml - don't copy-and-paste that big file, instead just make a small release.yml workflow to call it (as in the example file above).

Your repo will require access to release credentials to pass on those secrets to the workflow.

Java version

Example .tool-versions

Your repository must contain an asdf-formatted .tool-versions file in the root of the repository, specifying the Java version to be used by the workflow for building your project, eg:

java corretto-21.0.3.9.1

Note that although asdf requires a fully-specified Java version (eg 21.0.3.9.1 - use asdf list-all java to list all possible Java versions), currently the workflow will only match the major version of Java specified in the file (eg 21), and will always use the AWS Corretto distribution of Java. This is due to limitations in actions/setup-java.

As recommended below, you should also specify a -release flag in scalacOptions to ensure that your library is compiled for any older versions of Java you wish to support, even if you're taking advantage of a more recent version of Java for building the library.

sbt

Recommended sbt plugins

Example project/plugins.sbt

• sbt-version-policy - to supply automatic compatibility-based version-numbering that follows recommended Scala semver rules on your library, as well as automatically setting the versionScheme of your project to "early-semver" (essential).
• sbt-release
• sbt-sonatype - you currently need to have this in your project's plugins.sbt, as the 🎊 Create artifacts job expects it, but in the future, the workflow will probably supply this automatically.

Recommended sbt settings

Example version.sbt

• version - as specified by sbt-release, this should be the sole entry in your version.sbt file, and should define a semver version (major.minor.patch), which during normal dev has a -SNAPSHOT suffix (eg 1.4.7-SNAPSHOT). You can think of -SNAPSHOT as meaning 'a snapshot preview' - so when you're working on 1.4.7-SNAPSHOT, you're working on a preview of the forthcoming 1.4.7 release. The workflow will automatically update the version during each release, as appropriate.

Example build.sbt

• Artifact-producing modules
  • organization - this dictates the groupId of your artifacts, and can be either the same as your Sonatype account profile name (eg com.gu for the Guardian), or a dot-suffixed version of it (eg com.gu.foobar) if your project ('foobar') releases multiple artifacts (details)
  • licenses := Seq(License.Apache2) - or whatever license you're using. Specifying a license is required for submitting artifacts to Maven Central.
  • scalacOptions should include -release:11 (available with Scala 2.13.9 and above, also known as -java-output-version in Scala 3), or whatever minimum version of Java you want to support. The workflow will build your project with whatever Java version you declare in .tool-versions - but while this can be a relatively new version of Java, in order for your compiled code to support older versions of Java, and avoid UnsupportedClassVersionError errors, you'll need to set this flag. See also Scala/Java compatibility.
• Top-level 'release' module - if your project has a multi-module build this could be called 'root', or, if your project only has one module, it and your artifact-producing module could be the same thing, and just use top-level settings.
  • publish / skip := true (rather than other legacy hacks like publishArtifact := false) for sbt modules that don't generate artifacts (often, the 'root' project in a multi-project build). This setting is respected by sbt-version-policy - it won't attempt to calculate compatibility on a module that doesn't publish artifacts.
  • In releaseProcess, you'll want fewer steps than the old list specified by sbt-sonatype, now just: checkSnapshotDependencies, inquireVersions, runClean, runTest, setReleaseVersion, commitReleaseVersion, tagRelease, setNextVersion, commitNextVersion (if your tests require special privileges you may need to drop runTest)
  • releaseVersion := ReleaseVersion.fromAggregatedAssessedCompatibilityWithLatestRelease().value - to activate the automatic compatibility-based version-numbering provided by the sbt-version-policy plugin. This means your version can go up by more than just an x.x.PATCH increment in a release, if Scala semver rules say that it should. You'll need import sbtversionpolicy.withsbtrelease.ReleaseVersion at the top of your build.sbt to access this method.

Unnecessary sbt plugins

• sbt-pgp - the workflow 🔒 Sign job now handles PGP signing directly with GPG

Unnecessary sbt settings

These settings are now set by gha-scala-library-release-workflow and can be removed from your build.sbt or sonatype.sbt (sonatype.sbt can generally be deleted entirely):

• homepage
• developers
• pomExtra
• publishTo
• sonatypeProfileName
• scmInfo
• In releaseProcess, it's essential you remove steps that are now separately performed elsewhere in the workflow (ie sign, release, push):
  • releaseStepCommands like publishSigned and sonatypeBundleRelease
  • pushChanges

Examples

You can see a long list of example PRs updating repos to use gha-scala-library-release-workflow here.

See also all repos using Scala Library Release Workflow.