Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesSome links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
A shell script can be syntactically correct and still fail after a pull request is merged because CI is not the same machine, shell, directory, or process that you used locally. The reliable fix is a pre-merge gate that tests the runner contract, not just the script text. It validates the CI wrapper, identifies the interpreter and dialect, runs ShellCheck and shfmt, executes the script in the target image or runner class, checks paths, permissions, variables, locale and services, and publishes a redacted failure snapshot. That turns “works on my laptop” into a specific answer such as “the job invoked dash instead of Bash,” “the checkout directory is different,” or “the required command is absent.”
Why does a valid shell script work locally but fail in CI?
Because syntax is only one part of a shell program’s contract. The runner also supplies an interpreter, executable search path, operating-system tools, working directory, file modes, environment variables, locale, network access, service containers and a CI wrapper. Any mismatch can change the result before the first line of your script is evaluated or while an apparently successful command is running.
As an Amazon Associate I earn from qualifying purchases.
Recommended Free Tools
ShellCheck’s documented job is static analysis: it warns about shell-code mistakes and dialect-specific problems. It cannot prove that a runner contains a command, has the expected file, can reach a service, or provides a secret. Runtime reproduction answers those questions. A useful gate performs both checks and reports which assumption failed first.
What assumptions should a pre-merge gate make visible?
Write the assumptions down as a runner contract, then test each one. The following dimensions cover the failures that syntax-only checks miss.
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
| Contract dimension | What to record or verify | Typical failure revealed |
|---|---|---|
| Interpreter and dialect | Shebang, resolved executable, version and intended dialect such as bash, POSIX sh, dash or ash |
A Bash-only feature is sent to a POSIX shell, or the runner uses a different version |
| Image and command set | Pinned base image or runner class; command -v for every required executable; tool versions |
A utility exists on a developer laptop but is missing from the container |
| Process environment | Redacted PATH, library paths, locale and time zone |
Different command resolution, character handling or date output |
| Filesystem context | pwd, checkout depth, symlinks, mount points, ownership, permissions and executable bits |
A relative path points somewhere else or a checked-out script is not executable |
| Inputs and credentials | Required variable names, filtering rules and presence checks; never their values | A variable is unset, renamed or withheld from a forked merge request |
| External dependencies | Network policy, service containers, credentials and filesystem mounts | A connection or mounted file available locally does not exist in the job |
| CI wrapper | YAML quoting, multiline-block indentation, command grouping and default shell flags | The wrapper parses a colon incorrectly, folds commands unexpectedly or reports the wrong status |
Keep the snapshot small and deterministic. Its purpose is to explain a failure, not to archive every process detail from the host.
How do static linting and runtime reproduction complement each other?
Static linting finds mistakes without running the script; runtime reproduction tests the assumptions that only a real runner can provide. Neither is a substitute for the other.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Use ShellCheck for code and dialect
Run ShellCheck against every shell file with the dialect the target job will use. ShellCheck can select a shell dialect and check external sources, so the gate should not silently analyze a Bash file as generic POSIX sh. CircleCI describes ShellCheck as “a shell script static analysis tool that gives warnings and suggestions for Bash/sh shell scripts,” while the Debian manual calls it a static analysis and linting tool for sh/bash scripts. Those descriptions define its scope: analysis of source, not verification of the runner.
Use shfmt for a stable representation
Run shfmt in diff or check mode so a merge cannot introduce formatting changes that obscure review. GitLab documents ShellCheck and shfmt as CI jobs for shell-script repositories. Formatting does not make a script correct, but a consistent form makes quoting, pipelines and command grouping easier to inspect.
Then execute the real artifact
After linting, run the exact checked-out script in the same pinned image or runner class used by the target job. A green lint job paired with a red runtime job is useful evidence: it says the source passed static analysis while an environmental assumption failed.
How should the gate validate the CI wrapper before the shell starts?
Parse and lint the CI configuration as its own artifact. A malformed wrapper can produce an error that looks like a shell bug even when the script is never invoked as intended.
Quote values that contain YAML syntax
In YAML-based systems, a colon in an unquoted command or value can be interpreted as a mapping separator. Quote commands and values when punctuation could change the parse, then run the platform’s configuration validator before starting a job.
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
Check multiline blocks and indentation
GitLab’s examples show how folded blocks and incorrect indentation can move a command outside the intended block. Review whether a block uses literal (|) or folded (>) style, and ensure every command line is indented under the same key. A wrapper test should print the rendered command list or use the platform’s compiled configuration view when available.
Make command status explicit
Do not assume the wrapper’s default status behavior matches your shell. Group related commands and make the failure condition explicit. If a wrapper executes several lines as one block, verify which command supplies the block’s exit status; a successful final command can otherwise hide an earlier failure. Test the wrapper with a deliberately failing command in a disposable branch so the gate proves that a non-zero status reaches the merge check.
How do you prove that the intended interpreter is running?
Make the interpreter part of the contract instead of relying on a runner default. GitLab advises choosing a shell available in the target environment, and ShellCheck can detect or be told the dialect.
- Give each executable script an explicit shebang, such as
#!/usr/bin/env bashwhen Bash is guaranteed by the image, or a POSIX-compatible shebang when the script must run undersh. - At job start, print the resolved interpreter path and version to the job summary. Resolve it with the same
PATHthe script will use; do not report the developer’s local path. - Run ShellCheck with that dialect and reject a mismatch between the shebang, lint setting and runtime command.
- Test the file’s executable bit and invoke it the same way production does. Running
bash script.shcan conceal a missing executable bit or a shebang error that./script.shwould expose.
Differences between bash, POSIX sh, dash and ash are not cosmetic. Features accepted by Bash may be rejected by a smaller POSIX shell, and a script that relies on one shell’s option behavior can change meaning under another. Pin the image or runner class so an interpreter upgrade is a deliberate change.
How can the gate inspect the runner without leaking secrets?
Capture facts, not credential values. Jenkins documentation notes that special environment variables can change build-script behavior, including PATH, LD_PRELOAD, DYLD_LIBRARY_PATH and other variables. Treat those variables as executable inputs and check them explicitly.
A safe diagnostic block can look like this:
set +x
printf 'workdir: '; pwd
printf 'user: '; id
printf 'umask: '; umask
printf 'PATH entries (values redacted):n'
printf '%sn' "$PATH" | tr ':' 'n' | sed 's#.*#<path-entry>#'
printf 'locale:n'
locale 2>/dev/null || true
printf 'required tools:n'
for tool in bash sh shellcheck shfmt; do
if command -v "$tool" >/dev/null 2>&1; then
printf '%s: %sn' "$tool" "$(command -v "$tool")"
else
printf '%s: missingn' "$tool"
fi
done
printf 'variable names (values redacted):n'
env | sed 's/=.*$/=<redacted>/'The example intentionally disables xtrace before inspecting inputs. CircleCI warns that xtrace can print expanded secret values, so never enable set -x around credential setup or commands that interpolate secrets. Prefer an allowlist of variable names, redact values in every artifact, and review masking behavior for the CI system you use.
What runtime reproduction should happen before merge?
Reproduce the target job, not a convenient approximation. If production uses a container image, run the gate in that pinned image; if it uses a hosted runner class, use the same class or an image with the same interpreter and command set.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
- Prepare the checkout. Use the same checkout depth, submodules, symlink handling and mount points as the target job. Record
pwdand list the files the script expects. - Verify permissions. Check ownership, readable directories, writable output locations and executable bits. A permission failure should identify the path and operation, not merely return “command failed.”
- Check commands and versions. Resolve every external executable with
command -vand print its version where supported. Do not rely on a transitive tool that happens to be installed on a developer machine. - Check variables safely. Assert that required names are present and non-empty where appropriate, while keeping values masked. Test the filtering rules used for merge requests, forks and protected branches.
- Check services and network. Start the same service containers, mounts and credentials required by the script. If the gate is intentionally offline, make that restriction part of the contract and test the expected failure path.
- Run the script as the job runs it. Preserve the wrapper’s working directory, shell options and command grouping. Save the first failing command context and its exit status.
This sequence separates a missing dependency from a script defect. It also prevents a local reproduction from accidentally succeeding because an interactive shell has extra aliases, functions or exported variables.
How do you test failure propagation instead of just success?
A gate should demonstrate that an upstream failure cannot be hidden by a later successful command. CircleCI documents errexit, nounset and pipefail as protective options and explains the pipeline rationale.
Where the selected shell supports them and the script is compatible, enable:
set -o errexit
set -o nounset
set -o pipefailerrexit stops on many unhandled non-zero statuses, nounset exposes accidental use of unset variables, and pipefail makes a pipeline fail when an earlier component fails instead of trusting only the last command. Shell options have edge cases around conditionals, command substitutions and deliberately handled failures, so the gate must include a small negative test rather than assume the flags are sufficient.
For example, feed a known-failing producer into a successful consumer and assert that the job exits non-zero under the intended shell. Then test the script’s legitimate exceptions explicitly, using an intentional status check rather than disabling strict behavior for the whole job.
What should the gate publish when it fails?
Publish a sanitized environment snapshot and the exact failing command context as a CI artifact or job summary. Include the interpreter path and version, image or runner identifier, working directory, redacted path, locale, required-tool results, permission check and exit status. Put the first violated assumption at the top so a developer can act without rerunning the job blindly.
- Keep tokens, passwords, private keys, authorization headers and expanded command arguments out of logs.
- Do not attach raw environment dumps; redact values before the artifact is created.
- Record the script path and line number when the shell provides them, but avoid printing source lines that contain secrets.
- Retain enough image and runner metadata to reproduce the same environment after the merge request changes.
A diagnostic artifact is part of the gate’s interface. A red check that says only “exit code 1” encourages guesswork; a red check that says “shfmt passed, interpreter is /bin/dash, required Bash feature failed at runtime” points to a repair.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
What does a complete pre-merge sequence look like?
Order checks from cheapest and most structural to most environment-dependent, while preserving the same artifact throughout.
- Validate the wrapper: parse the CI file, check quoting and multiline indentation, and verify command grouping and status behavior.
- Identify the interpreter: enforce the shebang, resolve the executable and print its version; reject dialect disagreement.
- Lint and format: run ShellCheck with the intended dialect and shfmt in check mode.
- Reproduce the runtime: enter the pinned image or runner class and capture the redacted contract snapshot.
- Exercise the script: check paths, permissions, variables, tools, services and the real command invocation.
- Prove propagation: run a controlled pipeline-failure test and verify that the wrapper receives a non-zero result.
- Protect and publish: keep xtrace off around secrets, redact diagnostics and attach the first-failure summary.
Require every stage for merge. If a repository has scripts for several shells, create a separate job per declared dialect rather than letting one permissive job stand in for all of them.
How do you troubleshoot the most common gate failures?
“Command not found” after a clean lint
Compare command -v output and the redacted PATH between local and CI. Install the dependency in the pinned image or call an approved absolute path; do not “fix” the symptom by adding an untracked directory to PATH.
“Bad substitution” or an option is illegal
Inspect the shebang, job-level shell setting and ShellCheck dialect. The script may be running under sh, dash or ash while it requires Bash, or the reverse may be true for a script intended to remain portable.
Relative files cannot be found
Compare pwd, checkout layout, symlinks and checkout depth. Use an intentional project-root change in the script or wrapper, then test from the same starting directory as the real job.
Free tools Windows power users keep installed
One-click scans. No signup required.
A variable is empty only for merge requests
Check variable filtering and protected-secret rules. The correct fix may be to provide a non-secret default, change the job’s trust boundary or fail with a clear missing-input message—not to print the secret while debugging.
The job is green even though an earlier command failed
Inspect pipeline status handling, command grouping and shell options. Enable compatible strict options, add pipefail, and retain a negative test that proves an upstream failure reaches the job result.
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
The YAML error looks like a shell error
Validate the rendered configuration first. Quote colon-containing values and repair multiline indentation before changing shell syntax; otherwise you may be debugging a command that the wrapper never passed to the interpreter.
What can this gate prove—and what can it not prove?
It can prove that a defined script, wrapper, interpreter, image and set of declared inputs behave together under the tested conditions. It cannot prove that every future runner, dependency upgrade, network response or production secret will behave identically. Keep the image, tool versions and contract checks under version control so an environmental change creates a visible review rather than a surprise after merge.
There is no established percentage showing how often environment failures outweigh syntax failures. The practical conclusion is narrower and more useful: syntax validity is necessary, while environment observability is what explains CI-only failures. A pre-merge gate that tests both gives developers a failing assumption they can fix instead of a vague green-or-red verdict.
Frequently Asked Questions
Can I run the same pre-merge gate on a developer laptop?
Yes, but treat the laptop run as a convenience check, not proof of CI parity. Run the gate inside the pinned image or runner-compatible container locally when possible, and compare its redacted contract snapshot with the CI artifact.
Should a shell script be rewritten in another language when this keeps happening?
Not automatically. First identify whether the defect is an interpreter mismatch, missing tool, wrapper parse issue or unavailable service; a rewrite will not remove those constraints. Consider another language only when its testing, dependency and deployment model better matches the job’s requirements.
How should optional commands be handled under strict shell options?
Make optionality explicit with a conditional status check and document the allowed failure. Do not disable errexit or pipefail for an entire job just to tolerate one expected non-zero result.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →What is the safest way to debug a missing CI secret?
Test only whether the variable is present and meets a non-sensitive shape requirement, then emit its name and a redacted status. Never print the value, enable xtrace around its use or include expanded command arguments in an artifact.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
