lpil / setup-beam

Set up your BEAM-based GitHub Actions workflow (Erlang, Elixir, Gleam, ...)

setup-beam

This action sets up an Erlang/OTP environment for use in a GitHub Actions workflow by:

• installing Erlang/OTP
• optionally, installing Elixir
• optionally, installing Gleam
• optionally, installing rebar3
• optionally, installing hex
• optionally, having problem matchers show warnings and errors on pull requests

Note: currently, this action only supports Actions' ubuntu- and windows- runtimes.

Usage

See action.yml for the action's specification.

Note: the Erlang/OTP release version specification is relatively complex. For best results, we recommend specifying exact versions, and setting option version-type to strict. However, values like 22.x, or even >22, are also accepted, and we attempt to resolve them according to semantic versioning rules. This implicitly means version-type is loose, which is also the default value for this option.

Additionally, it is recommended that one specifies versions using YAML strings, as these examples do, so that numbers like 23.0 don't end up being parsed as 23, which is not equivalent.

For pre-release versions, such as v1.11.0-rc.0, use the full version specifier (v1.11.0-rc.0) and set option version-type to strict. Pre-release versions are opt-in, so 1.11.x will not match a pre-release.

Compatibility between Operating System and Erlang/OTP

This list presents the known working version combos between the target operating system and Erlang/OTP.

Operating system	Erlang/OTP	Status
ubuntu-18.04	17 - 25	✅
ubuntu-20.04	20 - 25	✅
ubuntu-22.04	24.2 - 25	✅
windows-2019	21* - 25	✅
windows-2022	21* - 25	✅

Note *: prior to 23, Windows builds are only available for minor versions, e.g. 21.0, 21.3, 22.0, etc.

Self-hosted runners

Self-hosted runners need to set env. variable ImageOS to one of the following, since the action uses that to download assets:

ImageOS	Operating system
ubuntu18	ubuntu-18.04
ubuntu20	ubuntu-20.04
ubuntu22	ubuntu-22.04
win19	windows-2019
win22	windows-2022

as per the following example:

...

jobs:
  test:
    runs-on: self-hosted
    env:
      ImageOS: ubuntu20 # equivalent to runs-on ubuntu-20.04
    steps:
      - uses: actions/checkout@v2
      - uses: erlef/setup-beam@v1
        ...

Example (Erlang/OTP + Elixir, on Ubuntu)

# create this in .github/workflows/ci.yml
on: push

jobs:
  test:
    runs-on: ubuntu-latest
    name: OTP ${{matrix.otp}} / Elixir ${{matrix.elixir}}
    strategy:
      matrix:
        otp: ['20.3', '21.3', '22.2']
        elixir: ['1.8.2', '1.9.4']
    steps:
      - uses: actions/checkout@v2
      - uses: erlef/setup-beam@v1
        with:
          otp-version: ${{matrix.otp}}
          elixir-version: ${{matrix.elixir}}
      - run: mix deps.get
      - run: mix test

Example (Erlang/OTP + rebar3, on Ubuntu)

# create this in .github/workflows/ci.yml
on: push

jobs:
  test:
    runs-on: ubuntu-latest
    name: Erlang/OTP ${{matrix.otp}} / rebar3 ${{matrix.rebar3}}
    strategy:
      matrix:
        otp: ['20.3', '21.3', '22.2']
        rebar3: ['3.14.1', '3.14.3']
    steps:
      - uses: actions/checkout@v2
      - uses: erlef/setup-beam@v1
        with:
          otp-version: ${{matrix.otp}}
          rebar3-version: ${{matrix.rebar3}}
      - run: rebar3 ct

Example (Erlang/OTP + rebar3, on Windows)

# create this in .github/workflows/ci.yml
on: push

jobs:
  test:
    runs-on: windows-2022
    steps:
      - uses: actions/checkout@v2
      - uses: erlef/setup-beam@v1
        with:
          otp-version: '24'
          rebar3-version: '3.16.1'
      - run: rebar3 ct

Example (Gleam on Ubuntu)

# create this in .github/workflows/ci.yml
on: push

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: erlef/setup-beam@v1
        with:
          otp-version: '24'
          gleam-version: '0.19.0-rc3'
      - run: gleam test

Example (Gleam on Ubuntu without OTP)

# create this in .github/workflows/ci.yml
on: push

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: erlef/setup-beam@v1
        with:
          otp-version: false
          gleam-version: '0.19.0-rc3'
      - run: gleam check

Note: the otp-version: false input is only applicable when installing Gleam.

Environment variables

Base installation folders (useful for e.g. fetching headers for NIFs) are available in the following environment variables:

• INSTALL_DIR_FOR_OTP: base folder for Erlang/OTP
• INSTALL_DIR_FOR_ELIXIR: base folder for Elixir
• INSTALL_DIR_FOR_GLEAM: base folder for Gleam
• INSTALL_DIR_FOR_REBAR3: base folder for rebar3

Elixir Problem Matchers

The Elixir Problem Matchers in this repository are adapted from here. See MATCHER_NOTICE for license details.

Action versioning

setup-beam has three version paths, described below, for example version 1.8.0:

• @v1: the latest in the 1.y.z series (this tag is movable),
• @v1.8: the latest in the 1.8.z series (this tag is movable),
• @v1.8.0: release 1.8.0 (this tag is not movable).

We make a real effort to not introduce incompatibilities without changing the major version number. To be extra safe against changes causing issues in your CI you should specify an exact version with @vx.y.z.

License

The scripts and documentation in this project are released under the MIT license.

Contributing

Check out this doc.

Current Status

This action is in active development.