luacheck

Composite action that runs luacheck with Lua 5.1 in Docker. Optionally runs a custom Lua script after luacheck.

Usage

jobs:
  luacheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Luacheck linter
        uses: BigWigsMods/luacheck@main
        with:
          args: -q

With a custom script

      - uses: BigWigsMods/luacheck@main
        with:
          args: -q
          custom_script: scripts/validate.lua
          custom_args: .

Custom script only (no luacheck)

      - uses: BigWigsMods/luacheck@main
        with:
          run_luacheck: false
          custom_script: scripts/validate.lua
          custom_args: .

With options

      - uses: BigWigsMods/luacheck@main
        with:
          args: --codes --ranges
          config: https://raw.githubusercontent.com/your-org/config/main/.luacheckrc
          annotate: warning

Job summary (optional)

Set job_summary: true to append a short summary to the workflow Summary tab (GITHUB_STEP_SUMMARY).

      - uses: BigWigsMods/luacheck@main
        with:
          args: -q
          job_summary: true

Inputs

Input	Default	Description
files	.	Paths passed to luacheck (default: whole repo)
path	.	Working directory (relative to workspace)
args	""	Extra luacheck CLI arguments (see below)
config	""	URL to custom .luacheckrc
annotate	none	none, warning, or error — show issues as PR annotations (incompatible with -qq/-qqq)
custom_script	""	URL or path (relative to path, or absolute) for a Lua script run after luacheck
custom_args	"."	Arguments passed to the custom script
run_luacheck	true	Set false to run only the custom script
fail_fast	false	If true, stop after the first failing step; if false, run luacheck and script (if set) and fail if either failed
job_summary	false	Markdown summary on the workflow Summary tab; includes command output when a step fails

Common args options

Arg	Description
-q	Suppress output for files with no issues
-qq	Suppress warning output (summary only)
-qqq	Summary line only
--codes	Show warning/error codes (e.g. W211)
--ranges	Show column ranges for issues
--no-cache	Disable luacheck’s cache

Full reference: luacheck CLI docs

File modifications

Custom scripts run with the workspace mounted; they can read/write repo files. Within a single job, the action pulls the container image once and reuses it for later invocations.

Repo structure

Path	Purpose
action.yml	Composite action: docker run the image with workspace + inputs
Dockerfile	Alpine image with luacheck, Lua 5.1, curl
entrypoint.sh	Luacheck and/or custom script; optional job_summary
test/	Fixtures and workflow job examples (test/README.md)

The Luacheck workflow self-tests the action.

Setup

Push the repo and run .github/workflows/build.yml to publish ghcr.io/BigWigsMods/luacheck.

Forks: change the image in action.yml (the docker pull / docker run lines) if you publish elsewhere.

Local use

Build and run the container locally (mounts current directory as workspace):

docker build -t luacheck .
docker run -v "$(pwd):/workspace" luacheck