Making a Release

April 24, 2026 ยท View on GitHub

Once a project has been configured to use gha-scala-library-release-workflow, a release can be performed by any GitHub user with write access to the repo, simply by triggering the release workflow.

Here's a video of that in action (full-screen the video to see all details):

https://github.com/guardian/gha-scala-library-release-workflow/assets/52038/ec18f213-5d85-4eff-9742-2a158d79b04b

Walkthrough of steps

  • Click on the Actions tab in your repo:
    image
  • Select the Release workflow from the list of workflows on the left-hand side of the page:
    image
  • Click on Run workflow on the right-hand side of the blue "This workflow has a workflow_dispatch event trigger." bar:
    image

Choose release type

image

  • In the modal popup that appears, decide on your release type:
    • Normal full release : leave the branch set to the default (ie main)
    • Preview release (eg of an unmerged PR) : select the PR's branch from the Branch: dropdown
  • Click on the green Run workflow button

Monitor the release

You've started a release! However, the GitHub UI can be slow to update, so reload the page, and then click on the new workflow run to see its progress:
image

Why can't releases be triggered in another way?

One potentially elegant alternative way to trigger a release would be trigger the workflow when a GitHub Release is manually created by a developer.

Unfortunately that would require a Git release version tag to be previously created by the developer, and a primary motivation of gha-scala-library-release-workflow is to avoid humans choosing release version numbers - because humans are terrible at judging compatibility, and thus knowing what the correct semver version bump should be.

If a human has manually chosen a version number before automated workflow occurs, we've already lost. Better to let the workflow make automatic compatibility-based checks, and derive the new version number (and release tag) for itself.

The gha-scala-library-release-workflow automatically creates a GitHub Release, with automatically-generated release notes, as part of the release process, so a GitHub Release is still created with each release.

Troubleshooting

If the release fails after it's tagged the repo, or it's a new artifact, subsequent releases will search for that non existent version in maven central when trying to do the compatibility check.

If it's due to a failed release or a new artifact e.g. first scala 3 version:

  1. update the version.sbt manually to be a suitable SNAPSHOT version (usually a major version)
  2. comment out the version check in the build.sbt
  3. run the release action again
  4. add the version check back in to the build.sbt