RunBook AcademyLinux

← All checklists in Linux

As neededCLI

Checklist: Shell script review

20 items ·9 critical ·7 warn ·4 info

This checklist is the pre-merge review for any shell script that will run in production — whether in a cron entry, a systemd timer, a CI pipeline, or a configuration-management run. Run it before the script reaches a production host for the first time.

Procedure

For each item:

Read the requirement.
Confirm the script satisfies it. If not, fix or document the exception.
For automated checks, run the listed command and confirm the expected output.

The critical items are non-negotiable. A script missing any of them should not reach production until the gap is closed. Warnings should be addressed or explicitly justified in the pull request.

Approval

Every script merged to production should have:

A peer review confirming this checklist passes.
ShellCheck green at the configured severity in CI.
A test fixture that exercises the script against representative input, with assertions on the output.
A runbook entry for the operational procedure, if the script is part of an incident response.

Critical9 items

Shebang is `#!/usr/bin/env bash` or `#!/bin/bash` — not `#!/bin/sh` for bash-only features, not missing.
```
head -1 script.sh
```
Top of script: `set -euo pipefail` to fail on errors, undefined variables, and pipeline failures.
```
head -5 script.sh
```
If invoked from cron or systemd, PATH is set explicitly via the crontab `PATH=` line or the unit `Environment=`.
Every variable reference is double-quoted: `"$var"`, never bare `$var`. Unquoted references are the most common source of word-splitting bugs.
No bare `rm -rf` against user-controlled paths. Use `find … -delete` with explicit predicates, or move to trash.
No secrets passed as command-line arguments. Secrets in `ps -ef` or `/proc/<pid>/cmdline` are world-readable.
No `set -x` or `set -v` left enabled in a script that handles credentials. xtrace writes every expanded argument to stderr — and therefore to the journal, the cron mail, and the CI log — including the secret you were careful to keep out of argv. If tracing is needed, wrap the sensitive section: `set +x; use_secret; set -x`.
```
grep -n "set -[a-z]*x" script.sh
```
Any scheduled script that could overrun its own interval holds a lock. In the script: `exec 9>/run/lock/myjob.lock` then `flock -n 9 || exit 0`. In a unit: `ExecStart=/usr/bin/flock -n /run/lock/myjob.lock /usr/local/bin/myjob`. Verify by starting two instances at once and confirming the second exits without doing work.
```
grep -n flock script.sh
```
No `curl … | bash` style invocations. Download first, verify, then execute.

Warning7 items

Globs that act on user-controlled paths are either quoted or replaced with `find -print0 | xargs -0`.
A script that creates files holding credentials, keys, or state sets `umask 077` before creating them rather than inheriting the umask of whatever invoked it. A cron job and an interactive shell do not have the same umask, so a file that is 0600 in testing can land as 0644 in production.
Exit codes are checked where they matter: `cmd || handle_failure`, or `set -e` + `if cmd; then …` for conditional handling.
`grep` and `find` "no results" are not treated as fatal errors; document explicitly: `grep … || [[ $? -eq 1 ]]` or similar.
Temporary files and background processes are cleaned up via `trap` on EXIT, INT, TERM.
ShellCheck reports no warnings at the configured severity level.
```
shellcheck script.sh
```
Temporary files use `mktemp -d` or `mktemp`, never `/tmp/something-static`. Predictable temp paths are a security risk.

Info4 items

Script is idempotent — running it twice produces the same state as running it once.
Logging is configurable via a flag or env var; default is informative without being noisy.
Tested on the minimum bash version in production (typically 4.x or 5.x). Avoid 5.x-only features if the estate has older bash.
```
bash --version
```
ShellCheck runs in CI on every change to the script.