Shellcheck Clean + Shell Collector

✓ Guardrail ↓ Collector Beta Testing And Quality

Enforce Shellcheck Clean using data collected by Shell Collector. Automatically check testing and quality standards on every PR.

Guardrail: Ensures ShellCheck finds no issues at or above the configured severity level (default: error). Skips if no shell scripts are detected. Severity filtering and warning threshold are both configurable.

Data Source: Detect shell scripts (.sh, .bash) in a repository and run ShellCheck for automated static analysis. Writes language detection data and lint results to Component JSON. Skips gracefully if no shell scripts are found.

Get Started View on GitHub

How Shell Collector Powers This Guardrail

The Shell Collector gathers metadata from your languages, build systems. This data flows into Lunar's Component JSON, where the Shellcheck Clean guardrail evaluates it against your standards.

When enabled, this check runs automatically on every PR and in AI coding workflows, providing real-time enforcement with actionable feedback.

↓ Shell Collector Gathers Data Collector

Extracts metadata from code, configs, and tool outputs

{ } Component JSON

Data centralized in structured format for evaluation

✓ Shellcheck Clean Checks Guardrail

Pass/fail result with actionable feedback in PRs

Quick Start Configuration

Add both the collector and policy to your lunar-config.yml to enable this guardrail.

📄 lunar-config.yml

# Step 1: Enable the Shell Collector
collectors:
  - uses: github://earthly/lunar-lib/collectors/shell@v1.0.5
    # with: ...

# Step 2: Enable the Shell Guardrails
policies:
  - uses: github://earthly/lunar-lib/policies/shell@v1.0.5
    include: [shellcheck-clean]
    # with: ...

What Shell Collector Collects

This collector gathers the following data that the Shellcheck Clean guardrail evaluates.

Collector code

`project`

Detects shell scripts in the repository by scanning for .sh and .bash files. Identifies shell types from shebang lines (bash, sh, zsh, dash, etc.). Writes script count, file locations, and shell type metadata to .lang.shell.

Collector code

`shellcheck`

Runs ShellCheck against all detected shell scripts with JSON output. Parses results into normalized lint warnings at .lang.shell.lint and tool-specific summary data at .lang.shell.native.shellcheck including pass/fail status and per-severity issue counts.

Collector ci-before-command

`shellcheck-cicd`

Detects ShellCheck executions in CI pipelines and records the command and version. Writes CI integration metadata to .lang.shell.native.shellcheck.cicd confirming ShellCheck is part of the CI workflow.

Example Data Flow

Here's an example of the data that Shell Collector writes to the Component JSON, which Shellcheck Clean then evaluates.

{ } component.json From Shell Collector

{
  "lang": {
    "shell": {
      "script_count": 3,
      "scripts": ["deploy.sh", "build/compile.sh", "scripts/test.sh"],
      "shells": ["bash", "sh"],
      "source": {
        "tool": "shell-collector",
        "integration": "code"
      },
      "native": {
        "shellcheck": {
          "passed": false,
          "version": "0.10.0",
          "files_checked": 3,
          "error_count": 0,
          "warning_count": 1,
          "info_count": 0,
          "style_count": 0,
          "cicd": {
            "commands": ["shellcheck scripts/*.sh"],
            "version": "0.10.0"
          }
        }
      },
      "lint": {
        "warnings": [
          {
            "file": "deploy.sh",
            "line": 15,
            "column": 3,
            "message": "Double quote to prevent globbing and word splitting.",
            "linter": "shellcheck",
            "severity": "warning",
            "code": "SC2086"
          }
        ],
        "linters": ["shellcheck"],
        "source": {
          "tool": "shellcheck",
          "integration": "code"
        }
      }
    }
  }
}

Configuration Options

Shell Collector Inputs

Input	Required	Default	Description
`find_command`	Optional	`find . -type f \( -name '.sh' -o -name '.bash' \) -not -path '/node_modules/' -not -path '/vendor/' -not -path '/.git/' -not -path '/dist/' -not -path '/.terraform/'`	Command to find shell scripts (must output one file path per line)
`shellcheck_severity`	Optional	`style`	Minimum ShellCheck severity level to collect (error, warning, info, style). Default collects everything.

Shell Guardrails Inputs

Input	Required	Default	Description
`min_severity`	Optional	`error`	Minimum severity level to enforce (error, warning, info, style). Issues below this level are ignored.
`max_shellcheck_warnings`	Optional	`0`	Maximum number of ShellCheck warnings allowed at or above min_severity (0 = must be completely clean)

Learn More

Guardrail · Shell Guardrails Shellcheck Clean View all compatible integrations

→

Collector Shell Collector View full documentation

→

Ready to Automate Your Standards?

See how Lunar can turn your AGENTS.md, engineering wiki, compliance docs, or postmortem action items into automated guardrails with our 200+ built-in guardrails.

Works with any process

AI agent rules & prompt files

Post-mortem action items

Security & compliance policies

Testing & quality requirements

Automate Now

Paste your AGENTS.md or manual process doc and get guardrails in minutes

Book a Demo