Shellcheck

Overview

A tool to perform static code analysis on shell scripts using ShellCheck.

This tool has been tested against the following:

1. GitHub Actions
2. Travis CI
3. CircleCI
4. BitBucket pipelines
5. Local command line

Because it is a plain Bash script, it should work on most CI platforms where you can run arbitrary commands.

Basic Usage

GitHub Actions

on: [push, pull_request]

jobs:
  build:
    name: ShellCheck
    runs-on: ubuntu-latest

    steps:
      - name: Checkout the Repository
        uses: actions/checkout@v4
      - name: Run ShellCheck
        run: bash <(curl -s https://raw.githubusercontent.com/lupaxa-cicd-toolbox/shellcheck/master/src/pipeline.sh)

Local

./src/pipeline.sh

Or without cloning:

bash <(curl -s https://raw.githubusercontent.com/lupaxa-cicd-toolbox/shellcheck/master/src/pipeline.sh)

Configuration Options

The following environment variables customise the script:

Variable	Default	Purpose
INCLUDE_FILES	(empty)	Comma-separated path regexes to force-include
EXCLUDE_FILES	(empty)	Comma-separated path regexes to skip
NO_COLOR	false	Disable colour output
REPORT_ONLY	false	Report results but always exit 0
SHOW_ERRORS	true	Show detailed errors for failed files
SHOW_FILTERED	false	Show files skipped by exclude rules
SHOW_UNMATCHED	false	Show files that matched neither pattern
SCAN_ROOT	script default	Override scan directory without editing the script

Note

If you set INCLUDE_FILES, only matching paths are scanned (everything else is skipped, including paths that would match EXCLUDE_FILES).

You can combine any of the settings above:

on: [push, pull_request]

jobs:
  build:
    name: ShellCheck
    runs-on: ubuntu-latest

    steps:
      - name: Checkout the Repository
        uses: actions/checkout@v4
      - name: Run ShellCheck
        env:
          REPORT_ONLY: true
          SHOW_ERRORS: true
        run: bash <(curl -s https://raw.githubusercontent.com/lupaxa-cicd-toolbox/shellcheck/master/src/pipeline.sh)

Example Output

--------------------------------------------------------------------- Stage 1: Parameters --
 No parameters given
---------------------------------------------------------- Stage 2: Install Prerequisites --
 [ OK ] docker pull --quiet koalaman/shellcheck:stable
------------------------------------------------------- Stage 3: Run shellcheck (v0.10.0) --
 [ ✅ ] .github/scripts/check-jobs.sh
 [ ✅ ] pipeline.sh
 [ ✅ ] tests/advanced-tests
 [ ✅ ] tests/bash.sh
 [ ✅ ] tests/dash.sh
 [ ✅ ] tests/ksh.sh
 [ ✅ ] tests/no-extension
 [ ✅ ] tests/sh.sh
------------------------------------------------------------------------- Stage 4: Report --
 Total: 8, OK: 8, Failed: 0, Skipped: 0
----------------------------------------------------------------------- Stage 5: Complete --

File Identification

Shell scripts are identified using the following code:

file -b "${filename}" | grep -qE '(shell|dash) script'

AND

[[ ${filename} =~ \.(sh|bash|dash|ksh)$ ]]