Scala GitHub Actions

Scala Release workflow (v3 - v4)

Setup

To use Scala Release workflow have to set up project:

• add latest sbt-dynver plugin
• add Evolution's artifactory plugin sbt-artifactory-plugin
• defined command alias check which runs code quality checks, for example: scalafmt and scalafix, and binary compatibility check by sbt-version-policy:

  addCommandAlias("fmt", "all scalafmtAll scalafmtSbt; scalafixEnable; scalafixAll") // optional: for development
  addCommandAlias("check", "all versionPolicyCheck Compile/doc scalafmtCheckAll scalafmtSbtCheck; scalafixEnable; scalafixAll --check")
  addCommandAlias("build", "all compile test") // optional: for development

  as very minimum "no-op" placeholder:

  addCommandAlias("check", "show version")

• direct publishTo to Evolution's artifactory (for publishing artifacts using sbt-artifactory-plugin):

  publishTo := Some(Resolver.evolutionReleases)

• create release.yml file with content:

    name: Publish Release
    
    on:
      push:
        tags:
          - 'v*'
    
    jobs:
      release:
        uses: evolution-gaming/scala-github-actions/.github/workflows/release.yml@v4
        secrets: inherit

Usage

In project's repo:

• push tag as separate activity
• crate new version tag, like git tag v1.2.3 -a -m "release v1.2.3"
• push the tag, git push origin tag v1.2.3

The above sequence will start Release workflow, which will:

• run SBT commands +clean; +check; +all test package to verify the build
• run SBT command +publish to publish packaged artifacts
• if any of above steps will fail, the workflow will remove git tag - improve code and push fix, later tag again
• workflow will auto-generate release notes and will publish them
• go to Code and navigate to Releases
• review release notes and amend, if required

The v4 version additionally allows overriding SBT commands used by the release job. It is especially useful for projects which have mixed Scala versions in submodules and for which the +, +all SBT features might not work properly:

jobs:
  release:
    uses: evolution-gaming/scala-github-actions/.github/workflows/release.yml@v4
    secrets: inherit
    with:
      # override sbt commands so they don't use "+" because the project uses mixed Scala versions with sbt-projectmatrix
      verify_sbt_command: 'clean; check; all test package'
      publish_sbt_command: 'publish'

Scala Release workflow (v2)

Replaced by v3 because GitHub excluded SBT from ubuntu-latest (details).

Scala Release workflow (v1)

Setup

To use Scala Release workflow have to set up project:

• add latest sbt-release plugin
• add Evolution's artifactory plugin sbt-artifactory-plugin
• defined command alias check which runs code quality checks, for example: scalafmt and scalafix, and binary compatibility check by sbt-version-policy:

  addCommandAlias("fmt", "all scalafmtAll scalafmtSbt; scalafixEnable; scalafixAll") // optional: for development
  addCommandAlias("check", "all versionPolicyCheck Compile/doc scalafmtCheckAll scalafmtSbtCheck; scalafixEnable; scalafixAll --check")
  addCommandAlias("build", "all compile test") // optional: for development

  as very minimum "no-op" placeholder:

  addCommandAlias("check", "show version")

• direct publishTo to Evolution's artifactory (for sbt-release using sbt-artifactory-plugin):

  publishTo := Some(Resolver.evolutionReleases)

• create release.yml file with content:

    name: Publish Release
    
    on:
      release:
        types: [published]
        branches: [main]
    
    jobs:
      release:
        uses: evolution-gaming/scala-github-actions/.github/workflows/release.yml@v1
        secrets: inherit

Usage

On GitHub:

• go to Releases page
• press Draft a new release button
• make sure that version.sbt file in root of project have correct version string, like 1.2.3
• in Choose a tag create a new tag (v1.2.3)
• set Release title to the same string (v1.2.3)
• press Generate release notes and review them
• press Publish release button
• navigate to Actions - there it is possible to follow build's progress

The above sequence will start Release workflow, which will:

• validate consistency of git tag and version
• run SBT commands clean; +all check test package to make sure that code quality is good
• run SBT command +publish to publish packaged artifacts
• if any of above steps will fail, the workflow will remove git tag and GitHub will mark release notes as draft and it will be possible to adjust code on main branch and attempt publishing again by navigating to drafted release and pressing Publish release button again

When release is published, make sure to amend version.sbt file with next version string.

Recommended Scala project setup

scalafmt

Minimal configuration requires usage of plugin like:

addSbtPlugin("org.scalameta" % "sbt-scalafmt" % "<latest version>")

scalafix

Minimal configuration requires usage of plugin like:

addSbtPlugin("ch.epfl.scala" % "sbt-scalafix" % "<latest version>")

binary compatibility

Requires usage of sbt-version-policy plugin like:

addSbtPlugin("ch.epfl.scala" % "sbt-version-policy" % "<latest version>")

scalac options

Evolution's plugin with very strict settings for Scala 2.12 and 2.13 projects

addSbtPlugin("com.evolution" % "sbt-scalac-opts-plugin" % "<latest version>")