Command Line Interface¶

GH-Lint comes as an executable .jar file that can be run from the command line.

Installation¶

GitHub Releases¶

Download the latest "CLI executable" from the GitHub Releases page.

GitHub pre-releases¶

Most commits to the repository are built with GitHub Actions with a ready to use artifact. To get the latest -SNAPSHOT version, download the "CLI Application" artifact from one of the workflow runs on main. It's possible to download the same artifacts for individual PR commits as well.

Execution¶

Regardless of where you downloaded the .jar file, you can run it from the command line.

Cross-platform¶

The .jar file can be run with Java on all operating systems:

java -jar ghlint.jar

Mac, Linux, Unix¶

On Unix systems (Linux, Mac), you can make the .jar executable and run it directly:

mv ghlint.jar ghlint
chmod +x ghlint
./ghlint --version

Windows¶

On Windows, you can simulate the same behavior with a batch file (ghlint.bat in the same folder as the .jar file):

@echo off
java -jar "%~dp0\ghlint.jar" %*

Productivity tip (all platforms)¶

If you put the executable .jar (or .bat) file's folder on the PATH, you can run it from anywhere:

ghlint my-workflow.yml

Usage¶

Usage: ghlint [<options>] <files>...

  GitHub Actions Linter (GH-Lint). A tool to lint GitHub Actions workflows and
  actions.
  See https://ghlint.twisterrob.net for more information.

Reporting:
  --exit / --ignore-failures  Exit with non-zero code if there are findings.
                              (default: --ignore-failures)
  --console / --silent        Output to console. --silent does not affect
                              --verbose, only findings. (default: --console)
  --ghcommands                Output GitHub Commands (warnings). (default: off)
  --sarif=<path>              Output a SARIF file.

Options:
  --root=<path>  Root directory of the repository. (default: .)
  --verbose      Prints more information. (default: off)
  -v, --version  Prints the version and exits.
  -h, --help     Show this message and exit

Arguments:
  <files>  Workflow YML files to check for problems.

Example usages:

Lint a single workflow:
$ ghlint .github/workflows/main.yml

Lint all workflows in GitHub Actions CI:
$ ghlint --verbose --sarif=report.sarif.json .github/workflows/*.yml

Lint a single action in repository root.:
$ ghlint action.yml

Lint for CI actions in a directory:
$ ghlint actions/my-action/action.yml