fivem-lua-lint-action

This GitHub Action runs luacheck on your Lua codebase against known FiveM natives for any GitHub repository!

Now supports FiveM Lua backtick syntax.

---

Using

To use this in your GitHub repository, create the following file:

.github/workflows/lint.yml

name: Lint
on: [push, pull_request]
jobs:
  lint:
    name: Lint Resource
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lint
        uses: Red40-Development/fivem-lua-lint-action@v3

This will automatically run luacheck for both commits and pull requests!

Runtime Inputs

You can customize behavior per-run without rebuilding the action image:

• paths: Which files/folders to lint.
• args: Extra luacheck args.
• config_path: Optional custom config file. If omitted, the embedded default config is used.
• extra_libs: Extra standards suffixes (format: a+b+c) injected at runtime.

Example with custom path/config/extras:

name: Lint
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lint
        uses: Red40-Development/fivem-lua-lint-action@v3
        with:
          paths: "client/ server/"
          extra_libs: "ox_lib+qbox"

Running Locally on Linux

Download the helper script into a location on your path and run it. On its first run it installs Lua/LuaRocks/LuaCheck when needed, downloads the current definitions into ~/.cache/fivem-lua-lint-action, and lints the current directory:

curl --fail --location \
  https://raw.githubusercontent.com/Red40-Development/fivem-lua-lint-action/main/fivem-lua-lint.sh \
  --output fivem-lua-lint
chmod +x fivem-lua-lint
./fivem-lua-lint

The helper uses the checked-in .luacheckrc.default and .luacheckrc.generated.template files from this repository. The cache is stored in the user’s home directory at ~/.cache/fivem-lua-lint-action.

To explicitly refresh the cached native/library definitions later:

./fivem-lua-lint update

To lint selected paths or add standards:

./fivem-lua-lint lint -t client server
./fivem-lua-lint lint --extra-libs ox_lib+qbox -t .

The script can also be configured with FIVEM_LUA_LINT_REF to pin a branch or tag and FIVEM_LUA_LINT_CACHE_DIR to change the cache location.

Manual installation

If you prefer to install LuaCheck separately, the helper’s install command clones Red40-Development/luacheck on the fivem-lua branch and runs luarocks make from that checkout. The source and isolated LuaRocks tree are kept under ~/.cache/fivem-lua-lint-action, and the executable is exposed as $HOME/.local/bin/luacheck-fivem so it does not conflict with another LuaCheck installation.

The .luacheckrc.default file is the library of FiveM globals generated by the native refresh workflow.

1) Install Lua, LuaRocks, and LuaCheck

On Debian or Ubuntu:

sudo apt update
sudo apt install -y lua5.3 luarocks git
./fivem-lua-lint install
export PATH="$HOME/.local/bin:$PATH"

Verify the installation:

luacheck-fivem --version

2) Run against a resource

From the resource directory, point LuaCheck at this action repository’s generated config:

ACTION_REPO="$HOME/src/fivem-lua-lint-action"
RESOURCE="$PWD"

luacheck-fivem \
  --operators "+=" \
  --default-config "$ACTION_REPO/.luacheckrc.default" \
  -t \
  "$RESOURCE"

You can lint selected directories instead:

luacheck-fivem \
  --operators "+=" \
  --default-config "$ACTION_REPO/.luacheckrc.default" \
  -t \
  client server shared.lua

3) Add extra library definitions

extra_libs are Luacheck standard names, not Lua packages to install. Use the repository’s generated template to create a temporary config with those standards:

ACTION_REPO="$HOME/src/fivem-lua-lint-action"
sed 's/%%EXTRA%%/+ox_lib+qbox/g' \
  "$ACTION_REPO/.luacheckrc.generated.template" > .luacheckrc.local

luacheck-fivem \
  --operators "+=" \
  --default-config .luacheckrc.local \
  -t \
  .

Do not commit .luacheckrc.local; it is generated for the local run. Replace ox_lib+qbox with the standards required by your project.

The action’s default config and generated template are refreshed from the native sources by this repository’s scheduled workflow. If you pull this repository before linting, your local definitions will stay current.

Running Locally with Docker

You can run this action image locally against a resource folder to validate lint behavior before pushing.

1) Build or use a local image

If you are developing this repository locally:

docker build -t ghcr.io/red40-development/fivem-lua-lint-action .

2) Run lint (no extra libs)

docker run --rm \
  -v "$PWD:/work" \
  -w /work \
  ghcr.io/red40-development/fivem-lua-lint-action \
  "-t" "." "" "" "false" ""

3) Run lint with extra libs

docker run --rm \
  -v "$PWD:/work" \
  -w /work \
  ghcr.io/red40-development/fivem-lua-lint-action \
  "-t" "." "" "" "false" "ox_lib+qbox"

The positional arguments map to action inputs in this order:

1. args
2. paths
3. config_path
4. capture
5. fail_on_warnings
6. extra_libs

Notes:

• Leave config_path empty ("") to use the embedded default config.
• Use extra_libs in the format a+b+c (example: ox_lib+mysql+qbox).
• Set fail_on_warnings to true if you want non-zero exit on lint warnings.

---

JUnit Reporting (Getting Fancy)

If you would like to display fancy results in the GitHub action job, you can try the following configuration, which outputs a JUnit results file:

.github/workflows/lint.yml

name: Lint
on: [push, pull_request]
jobs:
  lint:
    name: Lint Resource
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Lint
        uses: Red40-Development/fivem-lua-lint-action@v3
        with:
          capture: "junit.xml"
          args: "-t --formatter JUnit"
      - name: Generate Lint Report
        if: always()
        uses: mikepenz/action-junit-report@v3
        with:
          report_paths: "**/junit.xml"
          check_name: Linting Report
          fail_on_failure: false