Use CircleCI version 2.1 at the top of your .circleci/config.yml file.
1
version: 2.1
Add the orbs
stanza below your version, invoking the orb:
1
2
orbs:
shellcheck: circleci/shellcheck@3.3.0
Use shellcheck
elements in your existing workflows and jobs.
Easily integrate shellcheck into an existing workflow. Add the "check" job and provide any optional parameters desired.
1
2
3
4
5
6
7
8
9
version: '2.1'
orbs:
shellcheck: circleci/shellcheck@3.1.2
workflows:
my_workflow:
jobs:
- shellcheck/check:
dir: ./myScripts
exclude: SC2148
Install the Shellcheck CLI into your CI environment.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
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
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 | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
circleci_ip_ranges | Enables jobs to go through a set of well-defined IP address ranges. | No | false | boolean |
dir | Specify the root path containing the shell scripts. The directory will be recursively searched.
| No | . | string |
exclude | A comma separated list of SC codes to explicitly ignore. Example: "SC1000,SC1001"
| No | '' | string |
external_sources | Follow source statements even when the file is not specified as input.
| No | false | boolean |
format | Specify the output format of shellcheck. Valid values include: "tty", "gcc", "checkstyle", "diff", "json1", "json", "quiet"
| No | tty | enum |
ignore-dirs | Specify directories to be ignored during shellcheck. Separate paths by with new line.
| No | ./.git | string |
image-tag | 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
| No | current | string |
output | The filename of the shellcheck output, which is automatically saved
as a job artifact
| No | shellcheck.log | string |
pattern | The file pattern to search for. By default will search for "*.sh" | No | '' | string |
severity | Specify minimum severity of errors to consider. Valid values in order of severity are error, warning, info and style.
| No | style | enum |
shell | Shell language to check against. | No | '' | string |
Scan files in directory matching pattern.
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
dir | Specify the root path containing the shell scripts. The directory will be recursively searched.
| No | . | string |
exclude | A comma separated list of SC codes to explicitly ignore. Example: "SC1000,SC1001"
| No | '' | string |
external_sources | Follow source statements even when the file is not specified as input.
| No | false | boolean |
format | Specify the output format of shellcheck. Valid values include: "tty", "gcc", "checkstyle", "diff", "json1", "json", "quiet"
| No | tty | enum |
ignore-dirs | Specify directories to be ignored during shellcheck. Separate paths by with new line.
| No | ./.git | string |
output | The filename of the shellcheck output, which is automatically saved
as a job artifact
| No | shellcheck.log | string |
pattern | The file pattern to search for. By default will search for "*.sh" | No | '' | string |
severity | Specify minimum severity of errors to consider. Valid values in order of severity are error, warning, info and style.
| No | style | enum |
shell | Shell language to check against. | No | '' | string |
Install Shellcheck.
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
version | Select the tagged release version of Shellcheck to install.
Mac with ARM arquitecture is only supported since version 0.10.0
| No | 0.10.0 | string |
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
# This code is licensed from CircleCI to the user under the MIT license.
# See here for details: https://circleci.com/developer/orbs/licensing
version: 2.1
description: |
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.
display:
home_url: https://shellcheck.net
source_url: https://github.com/circleci-public/shellcheck-orb
commands:
check:
description: |
Scan files in directory matching pattern.
parameters:
dir:
default: .
description: |
Specify the root path containing the shell scripts. The directory will be recursively searched.
type: string
exclude:
default: ""
description: |
A comma separated list of SC codes to explicitly ignore. Example: "SC1000,SC1001"
type: string
external_sources:
default: false
description: |
Follow source statements even when the file is not specified as input.
type: boolean
format:
default: tty
description: |
Specify the output format of shellcheck. Valid values include: "tty", "gcc", "checkstyle", "diff", "json1", "json", "quiet"
enum:
- tty
- gcc
- checkstyle
- diff
- json1
- json
- quiet
type: enum
ignore-dirs:
default: ./.git
description: |
Specify directories to be ignored during shellcheck. Separate paths by with new line.
type: string
output:
default: shellcheck.log
description: |
The filename of the shellcheck output, which is automatically saved
as a job artifact
type: string
pattern:
default: ""
description: The file pattern to search for. By default will search for "*.sh"
type: string
severity:
default: style
description: |
Specify minimum severity of errors to consider. Valid values in order of severity are error, warning, info and style.
enum:
- error
- warning
- info
- style
type: enum
shell:
default: ""
description: Shell language to check against.
type: string
steps:
- run:
command: "#!/bin/bash\nRun_ShellCheck() {\n input=\"$1\"\n set --\n \n if [ -n \"$SC_PARAM_EXCLUDE\" ]; then\n set -- \"$@\" \"--exclude=$SC_PARAM_EXCLUDE\"\n fi\n \n if [ \"$SC_PARAM_EXTERNAL_SOURCES\" == \"1\" ]; then\n set -- \"$@\" \"--external-sources\"\n fi\n \n if [ -n \"$SC_PARAM_SHELL\" ]; then\n set -- \"$@\" \"--shell=$SC_PARAM_SHELL\"\n fi\n \n shellcheck \"$@\" --severity=\"$SC_PARAM_SEVERITY\" --format=\"$SC_PARAM_FORMAT\" \"$input\" >> \"$SC_PARAM_OUTPUT\"\n}\n\nCheck_For_ShellCheck() {\n if ! command -v shellcheck &> /dev/null\n then\n echo \"Shellcheck not installed\"\n exit 1\n fi\n}\n\nShellCheck_Files() {\n IFS=$'\\n'\n for file in ${SC_PARAM_IGNORE_DIRS}; do\n trimmed=$(echo \"${file}\" | awk '{$1=$1};1')\n \n if [ -e \"${trimmed}\" ]; then\n set -- \"$@\" \"!\" \"-path\" \"${trimmed}/*.sh\"\n fi\n done\n \n SC_PARAM_PATTERN=\"${SC_PARAM_PATTERN:-\"*.sh\"}\"\n SC_INPUT_FILES=/tmp/sc-input-files\n find \"$SC_PARAM_DIR\" ! -name \"$(printf \"*\\n*\")\" -name \"$SC_PARAM_PATTERN\" -type f \"$@\" | tee \"${SC_INPUT_FILES}\"\n set +e\n while IFS= read -r script\n do\n Run_ShellCheck \"$script\"\n done < \"${SC_INPUT_FILES}\"\n set -eo pipefail\n}\n\nCatch_SC_Errors() {\n if [ -s \"$SC_PARAM_OUTPUT\" ]; then\n printf '\\e[1;31mShellCheck Errors Found\\e[0m\\n'\n cat \"$SC_PARAM_OUTPUT\"\n exit 1\n else\n printf '\\e[1;32mNo ShellCheck Errors Found\\e[0m\\n'\n fi\n}\n\nSC_Main() {\n Check_For_ShellCheck\n ShellCheck_Files\n Catch_SC_Errors\n rm /tmp/sc-input-files\n}\n\n# Will not run if sourced for bats.\n# View src/tests for more information.\nTEST_ENV=\"bats-core\"\nif [ \"${0#*\"$TEST_ENV\"}\" == \"$0\" ]; then\n SC_Main\nfi\n"
environment:
SC_PARAM_DIR: <<parameters.dir>>
SC_PARAM_EXCLUDE: <<parameters.exclude>>
SC_PARAM_EXTERNAL_SOURCES: <<parameters.external_sources>>
SC_PARAM_FORMAT: <<parameters.format>>
SC_PARAM_IGNORE_DIRS: <<parameters.ignore-dirs>>
SC_PARAM_OUTPUT: <<parameters.output>>
SC_PARAM_PATTERN: <<parameters.pattern>>
SC_PARAM_SEVERITY: <<parameters.severity>>
SC_PARAM_SHELL: <<parameters.shell>>
name: Run Shellcheck
- store_artifacts:
destination: shellcheck
path: <<parameters.output>>
install:
description: |
Install Shellcheck.
parameters:
version:
default: 0.10.0
description: |
Select the tagged release version of Shellcheck to install.
Mac with ARM arquitecture is only supported since version 0.10.0
type: string
steps:
- run:
command: |
#!/bin/bash
if [[ $EUID == 0 ]]; then export SUDO=""; else # Check if we're root
export SUDO="sudo"
fi
install_mac() {
curl -LJO "https://github.com/koalaman/shellcheck/releases/download/v${SC_INSTALL_VERSION}/shellcheck-v${SC_INSTALL_VERSION}.darwin.aarch64.tar.xz"
tar -xvf "shellcheck-v$SC_INSTALL_VERSION.darwin.aarch64.tar.xz"
cd "shellcheck-v$SC_INSTALL_VERSION/" || false
$SUDO cp shellcheck /usr/local/bin
}
install_linux() {
wget -qO- "https://github.com/koalaman/shellcheck/releases/download/v${SC_INSTALL_VERSION}/shellcheck-v${SC_INSTALL_VERSION}.linux.x86_64.tar.xz" | tar -xJf -
cd "shellcheck-v$SC_INSTALL_VERSION/" || false
$SUDO cp shellcheck /usr/local/bin
}
install_arm64() {
wget -qO- "https://github.com/koalaman/shellcheck/releases/download/v${SC_INSTALL_VERSION}/shellcheck-v${SC_INSTALL_VERSION}.linux.armv6hf.tar.xz" | tar -xJf -
cd "shellcheck-v$SC_INSTALL_VERSION/" || false
$SUDO cp shellcheck /usr/local/bin
}
install_alpine() {
apk add shellcheck
}
install_arch() {
wget -qO- "https://github.com/koalaman/shellcheck/releases/download/v${SC_INSTALL_VERSION}/shellcheck-v${SC_INSTALL_VERSION}.linux.aarch64.tar.xz" | tar -xJf -
cd "shellcheck-v$SC_INSTALL_VERSION/" || false
$SUDO cp shellcheck /usr/local/bin
}
# Platform check
if uname -a | grep -q "Darwin"; then
install_mac
elif uname -a | grep -q "x86_64 GNU/Linux"; then
install_linux
elif uname -a | grep -q "aarch64 GNU/Linux"; then
install_arm64
elif uname -a | grep -q "x86_64 Msys"; then
install_windows
elif grep -q "Alpine" /etc/issue; then
install_alpine
elif grep -q Arch /etc/issue; then
install_arch
else
echo "This platform appears to be unsupported."
uname -a
exit 1
fi
environment:
SC_INSTALL_VERSION: <<parameters.version>>
name: Install Shellcheck
jobs:
check:
circleci_ip_ranges: << parameters.circleci_ip_ranges >>
description: |
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.
docker:
- image: cimg/base:<<parameters.image-tag>>
parameters:
circleci_ip_ranges:
default: false
description: Enables jobs to go through a set of well-defined IP address ranges.
type: boolean
dir:
default: .
description: |
Specify the root path containing the shell scripts. The directory will be recursively searched.
type: string
exclude:
default: ""
description: |
A comma separated list of SC codes to explicitly ignore. Example: "SC1000,SC1001"
type: string
external_sources:
default: false
description: |
Follow source statements even when the file is not specified as input.
type: boolean
format:
default: tty
description: |
Specify the output format of shellcheck. Valid values include: "tty", "gcc", "checkstyle", "diff", "json1", "json", "quiet"
enum:
- tty
- gcc
- checkstyle
- diff
- json1
- json
- quiet
type: enum
ignore-dirs:
default: ./.git
description: |
Specify directories to be ignored during shellcheck. Separate paths by with new line.
type: string
image-tag:
default: current
description: |
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
type: string
output:
default: shellcheck.log
description: |
The filename of the shellcheck output, which is automatically saved
as a job artifact
type: string
pattern:
default: ""
description: The file pattern to search for. By default will search for "*.sh"
type: string
severity:
default: style
description: |
Specify minimum severity of errors to consider. Valid values in order of severity are error, warning, info and style.
enum:
- error
- warning
- info
- style
type: enum
shell:
default: ""
description: Shell language to check against.
type: string
steps:
- checkout
- check:
dir: <<parameters.dir>>
exclude: <<parameters.exclude>>
external_sources: <<parameters.external_sources>>
format: <<parameters.format>>
ignore-dirs: <<parameters.ignore-dirs>>
output: <<parameters.output>>
pattern: <<parameters.pattern>>
severity: <<parameters.severity>>
shell: <<parameters.shell>>
examples:
add_shellcheck_to_workflow:
description: |
Easily integrate shellcheck into an existing workflow. Add the "check" job and provide any optional parameters desired.
usage:
version: "2.1"
orbs:
shellcheck: circleci/shellcheck@3.1.2
workflows:
my_workflow:
jobs:
- shellcheck/check:
dir: ./myScripts
exclude: SC2148
custom_shellcheck_job:
description: |
Install the Shellcheck CLI into your CI environment.
usage:
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