setup-beam GitHub Action

The action provides three types of versioning tags to balance convenience and stability:

• @v1: The latest in the 1.y.z series (movable tag).
• @v1.8: The latest in the 1.8.z series (movable tag).
• @v1.8.0: A specific release (immutable tag).

To prevent unexpected CI failures caused by updates, it is recommended to use an exact version with the @vx.y.z syntax.

When using self-hosted runners, you must set the ImageOS environment variable so the action can correctly identify the operating system for downloading assets.

Mapping examples:

• ubuntu24 maps to ubuntu-24.04
• win25 maps to windows-2025
• macos15 maps to macOS-15

jobs:
  test:
    runs-on: self-hosted
    env:
      ImageOS: ubuntu24 # equivalent to runs-on ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - uses: erlef/setup-beam@v1

The setup-beam GitHub Action installs an Erlang/OTP environment and can optionally install Elixir, Gleam, rebar3, local.hex, and local.rebar. It also supports problem matchers to show warnings and errors directly on pull requests.

- uses: erlef/setup-beam@v1
  with:
    otp-version: '26'

The erlef/setup-beam@v1 action supports Windows and macOS runners for installing Erlang/OTP and rebar3.

# Erlang/OTP + rebar3, on Windows
jobs:
  test:
    runs-on: windows-2025
    steps:
      - uses: actions/checkout@v4
      - uses: erlef/setup-beam@v1
        with:
          otp-version: '24'
          rebar3-version: '3.16.1'
      - run: rebar3 ct

# Erlang/OTP + rebar3, on macOS
jobs:
  test:
    runs-on: macos-15
    steps:
      - uses: actions/checkout@v4
      - uses: erlef/setup-beam@v1
        with:
          otp-version: '28'
          rebar3-version: '3.25'
      - run: rebar3 ct

Use erlef/setup-beam@v1 in your GitHub Actions workflow to install Erlang/OTP along with Elixir or rebar3. This is commonly used for testing Elixir projects or Erlang projects using rebar3 on Ubuntu runners.

# Erlang/OTP + Elixir, on Ubuntu
steps:
  - uses: actions/checkout@v4
  - uses: erlef/setup-beam@v1
    with:
      otp-version: '27.3.3'
      elixir-version: '1.18.3'
  - run: mix deps.get
  - run: mix test

# Erlang/OTP + rebar3, on Ubuntu
steps:
  - uses: actions/checkout@v4
  - uses: erlef/setup-beam@v1
    with:
      otp-version: '27.3.3'
      rebar3-version: '3.24.0'
  - run: rebar3 ct

When performing matrix testing where specific dependency versions must match exactly, use the version-type: strict input. This ensures that the versions provided are used precisely as requested.

steps:
  - uses: actions/checkout@v4
  - uses: erlef/setup-beam@v1
    with:
      otp-version: '26.2.5.5'
      rebar3-version: '3.22.1'
      version-type: strict
  - run: rebar3 eunit

You can use erlef/setup-beam@v1 to install Gleam. If you are installing Gleam in an environment where Erlang/OTP is not required, set otp-version: false.

# Gleam on Ubuntu with OTP
steps:
  - uses: actions/checkout@v4
  - uses: erlef/setup-beam@v1
    with:
      otp-version: '27'
      gleam-version: '1.9.0'
  - run: gleam test

# Gleam on Ubuntu without OTP
steps:
  - uses: actions/checkout@v4
  - uses: erlef/setup-beam@v1
    with:
      otp-version: false
      gleam-version: '1.9.0'
  - run: gleam check

Instead of defining versions in YAML, you can use the version-file input. The action infers the format from the filename:

• .toml files are parsed as mise configuration.
• All other filenames are parsed as asdf .tool-versions.

Note: If using a version file, version-type must be set to strict or the action will exit with an error. You cannot use both a version file and individual YML version inputs simultaneously.

Key Mapping:

If builds.hex.pm is unavailable, you can provide alternative mirrors using the hexpm-mirrors option. Mirrors are used in the order they are declared.

To use cdn.jsdelivr.net/hex as a fallback, list both mirrors in a multi-line string.

- uses: erlef/setup-beam@v1
  with:
    otp-version: '26'
    hexpm-mirrors: |
      https://builds.hex.pm
      https://cdn.jsdelivr.net/hex

When running on Windows, you can specify the OTP architecture (e.g., 32 or 64) using the otp-architecture option.

- uses: erlef/setup-beam@v1
  with:
    otp-version: '26'
    otp-architecture: '32'

The action exports environment variables containing the base installation folders for each tool. These are useful for tasks like fetching headers for NIFs. The binaries are located in the bin subdirectory of these paths.

• INSTALL_DIR_FOR_OTP
• INSTALL_DIR_FOR_ELIXIR
• INSTALL_DIR_FOR_GLEAM
• INSTALL_DIR_FOR_REBAR3