Hamburger Cross Icon
Shell Collector - Lunar Collector

Shell Collector

↓ Collector Beta LanguagesBuild

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.

Add shell to your lunar-config.yml:
uses: github://earthly/lunar-lib/collectors/shell@v1.0.5
Get Started View on GitHub

What This Integration Collects

This integration includes 3 collectors that gather metadata from your systems.

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.

shell bash sh scripts shebang scripting
Book a demo
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.

shellcheck linting shell bash static analysis code quality
Book a demo
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.

shellcheck ci cicd shell linting pipeline
Book a demo

How Collectors Fit into Lunar

Lunar watches your code and CI/CD systems to collect SDLC data from config files, test results, IaC, deployment configurations, security scans, and more.

Collectors are the automatic data-gathering layer. They extract structured metadata from your repositories and pipelines, feeding it into Lunar's centralized database where guardrails evaluate it to enforce your engineering standards.

Learn How Lunar Works →
1
↓ Collectors Gather Data This Integration
Triggered by code changes or CI pipelines, collectors extract metadata from config files, tool outputs, test results, and scans
2
{ } Centralized as JSON
All data merged into each component's unified metadata document
3
✓ Guardrails Enforce Standards
Real-time feedback in PRs and AI workflows

Example Collected Data

This collector writes structured metadata to the Component JSON. Here's an example of the data it produces:

{ } component.json Component JSON 
{
  "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

Configure this collector in your lunar-config.yml.

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.

Related

Policy Testing And Quality
Shell Guardrails

ShellCheck linting guardrails using collected lint data
Policy Testing And Quality
Linter Guardrails

Generic linter guardrails compatible with shell lint data

Documentation

View on GitHub

Shell Collector

Detects shell scripts and runs ShellCheck linting for bash/sh files.

Overview

This collector scans repositories for shell scripts (.sh, .bash files and files with shell shebangs), identifies the shell types in use, and runs ShellCheck for automated static analysis. Results are written as both normalized lint warnings (compatible with the generic linter policy) and tool-specific ShellCheck data. ShellCheck is bundled in the custom collector image (shell-main). Shell type detection uses shebang lines; files without shebangs fall back to file extension.

Collected Data

This collector writes to the following Component JSON paths:

Path Type Description
.lang.shell.script_count integer Number of shell scripts detected
.lang.shell.scripts array File paths of detected shell scripts
.lang.shell.shells array Shell types found (e.g., ["bash", "sh"])
.lang.shell.source object Source metadata
.lang.shell.native.shellcheck.passed boolean Whether ShellCheck found no issues
.lang.shell.native.shellcheck.version string ShellCheck version used
.lang.shell.native.shellcheck.files_checked integer Number of files checked
.lang.shell.native.shellcheck.error_count integer Number of errors found
.lang.shell.native.shellcheck.warning_count integer Number of warnings found
.lang.shell.native.shellcheck.info_count integer Number of informational issues
.lang.shell.native.shellcheck.style_count integer Number of style suggestions
.lang.shell.native.shellcheck.cicd.commands array ShellCheck commands detected in CI
.lang.shell.native.shellcheck.cicd.version string ShellCheck version detected in CI
.lang.shell.lint.warnings array Normalized lint warnings
.lang.shell.lint.linters array Linters used (["shellcheck"])
.lang.shell.lint.source object Source metadata

Collectors

This plugin provides the following collectors (use include to select a subset):

Collector Hook Type Description
project code Detects shell scripts and identifies shell types from shebangs
shellcheck code Runs ShellCheck and writes lint results
shellcheck-cicd ci-before-command Detects ShellCheck usage in CI pipelines

Installation

Add to your lunar-config.yml:

collectors:
  - uses: github://earthly/lunar-lib/collectors/shell@main
    on: ["domain:your-domain"]  # replace with your own domain or tags
    # include: [project, shellcheck, shellcheck-cicd]  # Only include specific subcollectors
    # with:
    #   find_command: "find . -type f -name '*.sh' -not -path '*/node_modules/*'"  # Override file discovery

No configuration required. Skips gracefully if no shell scripts are found.

Open Source

This collector is open source and available on GitHub. Contribute improvements, report issues, or fork it for your own use.

View Repository

Common Use Cases

Explore guardrails that use data from Shell Collector.

+
Shellcheck Clean + Shell Collector Ensures ShellCheck finds no issues at or above the configured severity level...
→

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 100+ built-in guardrails.

Works with any process
check AI agent rules & prompt files
check Post-mortem action items
check Security & compliance policies
check Testing & quality requirements
Automate Now
Paste your AGENTS.md or manual process doc and get guardrails in minutes
Book a Demo