> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# circleci/shellcheck

Automatically find bugs and errors in your shell scripts with ShellCheck on every commit. Add this static analysis tool to any CI/CD workflow and ShellCheck your scripts across your repository.


## Commands

### check

Scan files in directory matching pattern.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `dir` | string | . | Specify the root path containing the shell scripts. The directory will be recursively searched.
 |
| `exclude` | string |  | A comma separated list of SC codes to explicitly ignore. Example: "SC1000,SC1001"
 |
| `external_sources` | boolean | false | Follow source statements even when the file is not specified as input.
 |
| `format` | enum | tty | Specify the output format of shellcheck. Valid values include: "tty", "gcc", "checkstyle", "diff", "json1", "json", "quiet"
 |
| `ignore-dirs` | string | ./.git | Specify directories to be ignored during shellcheck. Separate paths by with new line.
Do not add slash (/) at the end of the directory.
 |
| `output` | string | shellcheck.log | The filename of the shellcheck output, which is automatically saved
as a job artifact
 |
| `pattern` | string |  | The file pattern to search for. By default will search for "*.sh" |
| `severity` | enum | style | Specify minimum severity of errors to consider. Valid values in order of severity are error, warning, info and style.
 |
| `shell` | string |  | Shell language to check against. |

### install

Install Shellcheck.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `version` | string | 0.10.0 | Select the tagged release version of Shellcheck to install.
Mac with ARM arquitecture is only supported since version 0.10.0
 |

## Jobs

### check

Run shellcheck over any shell scripts in the repository.
Add this job to any workflow to automatically check any shell scripts
in your repository using the official Koalaman Shellcheck Docker image.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `circleci_ip_ranges` | boolean | false | Enables jobs to go through a set of well-defined IP address ranges. |
| `dir` | string | . | Specify the root path containing the shell scripts. The directory will be recursively searched.
 |
| `exclude` | string |  | A comma separated list of SC codes to explicitly ignore. Example: "SC1000,SC1001"
 |
| `external_sources` | boolean | false | Follow source statements even when the file is not specified as input.
 |
| `format` | enum | tty | Specify the output format of shellcheck. Valid values include: "tty", "gcc", "checkstyle", "diff", "json1", "json", "quiet"
 |
| `ignore-dirs` | string | ./.git | Specify directories to be ignored during shellcheck. Separate paths by with new line.
Do not add slash (/) at the end of the directory.
 |
| `image-name` | string | cimg/base | Shellcheck is included in the CircleCI authored `cimg/base` docker image (Feb 2022 onward), installed via the official Ubuntu packages.
By default, "cimg/base" is used as the image, but you may specify a different base image with this parameter.
https://circleci.com/developer/images/image/cimg/base
 |
| `image-tag` | string | current | Shellcheck is included in the CircleCI authored `cimg/base` docker image (Feb 2022 onward), installed via the official Ubuntu packages.
By default the most current stable release of this image will be used, but you may statically set the image tag with this parameter.
https://circleci.com/developer/images/image/cimg/base
 |
| `output` | string | shellcheck.log | The filename of the shellcheck output, which is automatically saved
as a job artifact
 |
| `pattern` | string |  | The file pattern to search for. By default will search for "*.sh" |
| `resource_class` | enum | small | Configure the executor resource class |
| `severity` | enum | style | Specify minimum severity of errors to consider. Valid values in order of severity are error, warning, info and style.
 |
| `shell` | string |  | Shell language to check against. |

## Examples

### add_shellcheck_to_workflow

Easily integrate shellcheck into an existing workflow. Add the "check" job and provide any optional parameters desired.


```yaml
version: '2.1'
orbs:
  shellcheck: circleci/shellcheck@3.1.2
workflows:
  my_workflow:
    jobs:
      - shellcheck/check:
          dir: ./myScripts
          exclude: SC2148
```

### custom_shellcheck_job

Install the Shellcheck CLI into your CI environment.


```yaml
version: '2.1'
orbs:
  shellcheck: circleci/shellcheck@3.1.2
jobs:
  my_job:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - shellcheck/install
      - run:
          command: shellcheck <options>
          name: Run Shellcheck command
workflows:
  my_workflow:
    jobs:
      - my_job
```