gh-actions-lux

GitHub action for installing lux-cli bundled with lux-lua.

Feel free to consult the documentation on how to get started with Lux! It features a tutorial and several guides to make you good at managing Lua projects.

Inputs

version

• Default: latest
• Example: 0.19.0

Important

Lux, while generally functional, is a work in progress and does not have a 1.0 release yet. For this reason, we recommend pinning the version. Please check the latest release, as the examples in this readme may be outdated.

Examples

Minimal setup

name: Lux
on:
  pull_request:
  push:
    branches: [main]

jobs:
  lux-action:
    name: Example
    runs-on: ubuntu-24.04
    steps:
      - name: Checkout repository
        uses: actions/checkout@v5

      - name: Install Lux
        uses: lumen-oss/gh-actions-lux@v1
        with:
          version: 0.19.0

      - name: Use lux-cli
        run: |
          lx --version

Matrix (multiple targets)

name: Lux
on:
  pull_request:
  push:
    branches: [main]

jobs:
  lux-action:
    name: ${{ matrix.job.target }}
    runs-on: ${{ matrix.job.os }}
    strategy:
      fail-fast: false
      matrix:
        job:
          - { os: ubuntu-24.04, target: x86_64-linux }
          - { os: ubuntu-24.04-arm, target: aarch64-linux }
          - { os: macos-14, target: aarch64-darwin }
          - { os: windows-2025, target: x86_63-windows-msvc }
    steps:
      - name: Checkout repository
        uses: actions/checkout@v5

      - name: Install MSVC Compiler Toolchain
        uses: ilammy/msvc-dev-cmd@v1
        if: endsWith(matrix.job.target, '-msvc')

      - name: Install Lux
        uses: lumen-oss/gh-actions-lux@v1
        with:
          version: 0.19.0

      - name: Use lux-cli
        run: |
          lx --version

Matrix (multiple targets + Lua versions)

Because Lux can handle installing Lua for you, you do not need a step for installing Lua.

name: Tests
on:
  pull_request:
  push:
    branches: [main]

jobs:
  test:
    name: ${{ matrix.job.target }} - Lua ${{ matrix.lua_version }}
    runs-on: ${{ matrix.job.os }}
    strategy:
      fail-fast: false
      matrix:
        job:
          - { os: ubuntu-24.04, target: x86_64-linux }
          - { os: ubuntu-24.04-arm, target: aarch64-linux }
          - { os: macos-14, target: aarch64-darwin }
          - { os: windows-2025, target: x86_63-windows-msvc }
        lua_version:
          - 5.1
          - 5.2
          - 5.3
          - 5.4
    steps:
      - name: Checkout repository
        uses: actions/checkout@v5

      - name: Install MSVC Compiler Toolchain
        uses: ilammy/msvc-dev-cmd@v1
        if: endsWith(matrix.job.target, '-msvc')

      - name: Install Lux
        uses: lumen-oss/gh-actions-lux@v1
        with:
          version: 0.19.0

      - name: Type checks
        run: |
          lx --lua-version ${{ matrix.lua_version }} check --warnings-as-errors

      - name: Run tests
        run: |
          lx --lua-version ${{ matrix.lua_version }} test

Matrix (Neovim plugin)

To test a Neovim plugin that uses the busted-nlua test backend:

name: Tests
on:
  pull_request:
  push:
    branches: [main]
jobs:
  test:
    name: ${{ matrix.job.target }} - Lua ${{ matrix.nvim-version }}
    runs-on: ${{ matrix.job.os }}
    strategy:
      fail-fast: false
      matrix:
        job:
          - { os: ubuntu-24.04, target: x86_64-linux }
          - { os: ubuntu-24.04-arm, target: aarch64-linux }
          - { os: macos-14, target: aarch64-darwin }
          - { os: windows-2025, target: x86_63-windows-msvc }
        nvim-version:
          - stable
          - nightly
    steps:
      - name: Checkout repository
        uses: actions/checkout@v5

      - name: Install MSVC Compiler Toolchain
        uses: ilammy/msvc-dev-cmd@v1
        if: endsWith(matrix.job.target, '-msvc')

      - name: Setup Neovim
        uses: rhysd/action-setup-vim@v1
        with:
          neovim: true
          version: ${{ matrix.nvim-version }}

      - name: Install Lux
        uses: lumen-oss/gh-actions-lux@v1
        with:
          version: 0.19.0

      - name: Type checks
        run: |
          lx --nvim check --warnings-as-errors
        env:
          # See the .luarc.json below
          VIMRUNTIME:
            /home/runner/nvim-${{ matrix.nvim-version }}/share/nvim/runtime

      - name: Run tests
        run: |
          lx --nvim test

With the following .luarc.json:

{
  "diagnostics": {
    "enable": true
  },
  "runtime": {
    "version": "Lua 5.1"
  },
  "workspace": {
    "library": ["$VIMRUNTIME"]
  }
}

Note

lx check will automatically add dependencies to your .luarc.json's workspace.library.

Uploading a package to luarocks.org

To use lx upload, you need to provide an API key for luarocks.org.

Tip

We recommend combining this workflow with conventional commits and release-please.

name: Lux upload
on:
  push:
    tags: # Will upload to luarocks.org when a tag is pushed
      - '*'
  workflow_dispatch:
jobs:
  luarocks-upload:
    runs-on: ubuntu-22.04
    steps:
      - name: Checkout repository
        uses: actions/checkout@v5

      - name: Install Lux
        uses: lumen-oss/gh-actions-lux@v1
        with:
          version: 0.19.0

      - name: Upload
        run: |
          lx upload
        env:
          LUX_API_KEY: ${{ secrets.LUX_API_KEY }}