OpsScript Gate

ShellCheck tells you if your script looks portable. OpsScript Gate checks if it actually runs there.

OpsScript Gate is a drop-in runtime compatibility gate for Linux shell scripts. It executes your shell scripts inside isolated Debian, Ubuntu, and Alpine containers before release, catching environment-specific runtime failures that static analysis cannot detect.

Quickstart

In GitHub Actions

Add one step to your pull request workflow (.github/workflows/gate.yml):

- name: Verify Shell Script Portability
  uses: Mresyzz/opsscript-gate@v0.2.1
  with:
    script-path: scripts/setup.sh
    # shell: posix  # optional: 'posix' (default), 'shebang', or 'auto'

In Local Terminal (CLI)

Requires Python 3.10+ and a local Docker engine:

# Install from PyPI
pip install opsscript-gate

# Latest development version
pip install git+https://github.com/Mresyzz/opsscript-gate.git

# Run compatibility gate against your script
opsscript-gate run ./scripts/setup.sh

Example: What Static Analysis Misses

Consider this deployment script:

#!/bin/sh
set -e
echo "Fetching package information..."
apt-get --version

Running shellcheck reports 0 errors, 0 warnings because the syntax is valid POSIX shell.

However, when verified with OpsScript Gate:

+--------------------+----------+-----------+----------------------------------------------------+
| Distro             | Status   | Exit Code | Details                                            |
+--------------------+----------+-----------+----------------------------------------------------+
| debian:12-slim     | PASS     | 0         | OK                                                 |
| ubuntu:22.04       | PASS     | 0         | OK                                                 |
| ubuntu:24.04       | PASS     | 0         | OK                                                 |
| alpine:3.20        | FAIL     | 127       | Script failed with non-zero exit code: 127         |
+--------------------+----------+-----------+----------------------------------------------------+
Result: FAILED

============================================================
Failed Distributions - Output Snippets (last 15 lines):
============================================================

--- [alpine:3.20] (FAIL) ---
/tmp/target_script.sh: line 4: apt-get: not found

Example output; timing values omitted because they vary by host and image cache state.

Why it failed: Alpine Linux is musl/BusyBox-based and uses apk, not apt-get. OpsScript Gate catches the missing utility (exit code 127) during test execution, before the script is deployed.

Why OpsScript Gate?

OpsScript Gate vs ShellCheck vs Custom CI Matrix

• ShellCheck is indispensable for static analysis (syntax, quoting, SC warnings). OpsScript Gate complements it by testing actual execution behavior in real distributions.
• Handwritten CI Matrix requires maintaining complex Docker configurations, volume mounts, timeout guards, and log parsers across every project. OpsScript Gate packages this into a single check.

Security Boundaries

OpsScript Gate uses conservative container defaults when running scripts:

1. Unprivileged by Design:
   • Containers run with privileged=False.
   • All Linux capabilities are dropped: cap_drop=["ALL"].
   • Privilege escalation is disabled: security_opt=["no-new-privileges:true"].
2. Read-Only Target Mount:
   • The tested script is mounted read-only (:ro) at /tmp/target_script.sh.
   • OpsScript Gate does not mount additional host filesystem paths into the test container.
3. Anti-Hang Deadlock Defense:
   • Disables TTY and stdin (stdin_open=False, tty=False).
   • Redirects execution: /bin/sh -c "/bin/sh /tmp/target_script.sh </dev/null".
   • Injects DEBIAN_FRONTEND=noninteractive and CI=true.
   • Any script prompting for user input (read -p) fails immediately instead of blocking the CI runner.
4. Timeout & Container Cleanup:
   • Enforces a configurable timeout (default: 60s). Timed-out containers are sent SIGKILL and marked TIMED_OUT.
   • Container removal is attempted from a finally block during normal Python execution paths, including failures and timeouts.
5. Windows CRLF Defense:
   • Automatically detects and normalizes carriage returns (\r\n -> \n) before container execution, preventing false \r: command not found errors.
6. POSIX-oriented /bin/sh Baseline:
   • Containers invoke /bin/sh directly, catching undeclared Bashism syntax (e.g. bash arrays, [[ ... ]]) that break in lightweight Alpine environments.

Default Test Matrix

You can customize the matrix at any time via --matrix or Action input matrix.

CLI Reference

usage: opsscript-gate run [-h] [--matrix MATRIX] [--timeout TIMEOUT]
                          [--format {table,markdown,json}]
                          [--shell {posix,shebang,auto}]
                          script_path

Shell Execution Modes (--shell)

• posix (default): Strictly executes with /bin/sh, ignoring any script shebang. Ideal for verifying that your script runs in minimal POSIX-compliant environments (e.g. Alpine BusyBox).
• shebang: Strictly honors the interpreter specified in the script's shebang (#!/bin/sh, #!/bin/bash, #!/usr/bin/sh, #!/usr/bin/bash, #!/usr/bin/env sh, #!/usr/bin/env bash). If the shebang is missing, malformed, or specifies an unsupported interpreter/flag, the check fails immediately with an error before running containers.
• auto: Honors recognized shebangs if present; falls back to /bin/sh if no shebang is declared. Scripts with explicit unsupported or malformed shebangs fail immediately with an error (does not silently execute as POSIX).

Exit Code Convention

• 0: All distributions passed (PASS).
• 1: At least one distribution failed (FAIL), timed out (TIMED_OUT), or errored (ERROR).

Examples

Check out the examples/ directory for self-contained, runnable scenarios:

• examples/basic/: A clean POSIX script that passes across all distributions.
• examples/alpine-incompatibility/: Demonstrates catching implicit Debian/Ubuntu dependencies (e.g. apt-get).
• examples/interactive-hang/: Demonstrates how unhandled read prompts fail immediately instead of hanging.
• examples/github-actions/: Ready-to-copy production pull request workflow.

Dogfooding

OpsScript Gate is used in Mresyzz/linux-dev-bootstrap to validate its install.sh script across the default Debian, Ubuntu, and Alpine matrix in GitHub Actions. That workflow pins Mresyzz/opsscript-gate@v0.2.0 with shell: auto.

See the downstream workflow: .github/workflows/test.yml.

Development & Testing

The test suite uses Docker SDK mocking to ensure fast unit tests without needing a local daemon:

# Clone and install with test dependencies
git clone https://github.com/Mresyzz/opsscript-gate.git
cd opsscript-gate
pip install -e .[test]

# Run unit tests (mocked)
pytest -v -m "not integration"

# Run integration tests (Requires Docker daemon)
pytest -v

Current limitations

• Requires access to a Docker daemon.
• Scripts are executed with /bin/sh by default; use --shell shebang or --shell auto for shebang-aware execution.
• Distribution runs are currently sequential.
• Containers use bridge networking by default.
• Failure reports currently include only a tail of captured output.
• OpsScript Gate checks runtime execution and exit status; it does not validate application-specific outcomes.

Roadmap

See ROADMAP.md for planned capabilities, including:

• Container resource limits (--mem-limit, --pids-limit)
• Configurable network isolation (--network none|bridge)
• Parallel matrix execution

Contributing & Security

• Contributing: Please review CONTRIBUTING.md for pull request guidelines and security boundaries.
• Security Policy: Read SECURITY.md to report vulnerabilities responsibly.
• Changelog: See CHANGELOG.md for release history.

License

OpsScript Gate is licensed under the MIT License.