OpsScript Gate — shell script compatibility testing

简体中文 · Configuration · Troubleshooting

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 scripts inside unprivileged Debian, Ubuntu, and Alpine containers before merge, catching environment-specific runtime failures, missing interpreters, and package-manager assumptions that static analysis cannot detect.

It is designed for shell testing, portable shell validation, Bash/POSIX compatibility checks, and cross-distro CI where syntax-only tooling is not enough.

New in v0.5.0

Preview exactly what will run, keep local and CI settings together, and exclude test fixtures before executing scripts. These controls are included in v0.5.0. Projects on v0.4.1 and earlier do not include them.

opsscript-gate init
opsscript-gate run --dry-run
opsscript-gate run --format json --output reports/compatibility.json

init creates .opsscript-gate.json and a GitHub Actions workflow without replacing existing files. Review its exclusions (tests/*, examples/*) and offline network default before running. No Docker is required for init or --dry-run.

Useful for standalone installers, container entrypoints and release scripts that must work on both GNU/Linux and Alpine/BusyBox. Each script runs independently; repository files, sibling scripts and project dependencies are not mounted. See configuration and migration and why a shell script works on Ubuntu but fails on Alpine.

⚡ 30-Second Quickstart

In GitHub Actions (Zero Config)

Drop this minimal workflow into .github/workflows/shell-compat.yml:

name: Shell Compatibility Gate
on: [pull_request, push]

jobs:
  compat:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: Mresyzz/opsscript-gate@v0.5.0

Zero Config: If script-path is omitted, OpsScript Gate automatically discovers shell scripts in your repository. Scripts run sequentially, with concurrent distribution checks for each script. Preview discovery before running unfamiliar repositories.

Or test a specific script with custom execution modes:

      - uses: Mresyzz/opsscript-gate@v0.5.0
        with:
          script-path: scripts/install.sh
          shell: auto
          jobs: 4

In Local Terminal (CLI)

Requires Python 3.10+ and a running local Docker engine:

# Install from PyPI
pip install opsscript-gate

# Run against a specific script
opsscript-gate run ./scripts/install.sh

# Or auto-discover scripts across your repository
opsscript-gate run

Try a Real Failure in 30 Seconds

Create install.sh:

#!/bin/sh
set -e
apt-get --version

Then run:

opsscript-gate run ./install.sh

A typical result across the default matrix looks like this:

Debian 12        PASS
Ubuntu 22.04     PASS
Ubuntu 24.04     PASS
Alpine 3.20      FAIL

apt-get: not found

The script is valid shell, but the runtime environment is incompatible. That is exactly the class of failure OpsScript Gate is designed to catch.

🎯 Reviewer-First Experience: What It Produces

Every run of OpsScript Gate generates clean, actionable feedback right where developers and reviewers need it:

1. Line-Level GitHub Annotations

When a failure occurs, OpsScript Gate flags the exact script line on your Pull Request's Files Changed view with high-confidence diagnostics and conservative remediation hints:

::error file=scripts/setup.sh,line=4,title=OpsScript Gate: [alpine:3.20] command not found: apt-get::command not found: apt-get — Alpine normally uses apk instead of apt-get.

2. GitHub Step Summary Compatibility Card

A beautifully formatted markdown summary is automatically posted to $GITHUB_STEP_SUMMARY:

## 🛡️ OpsScript Gate Compatibility Report

**Target Script**: `scripts/setup.sh`  
**Status**: ❌ **CHECKS FAILED (3/4 Passed)**  
**Total Duration**: `1.24s`

### 📊 Compatibility Matrix

| Distribution | Status | Exit Code | Time | Diagnostic & Recommendation |
| :--- | :---: | :---: | :---: | :--- |
| `debian:12-slim` | ✅ PASS | `0` | `0.42s` | OK |
| `ubuntu:22.04` | ✅ PASS | `0` | `0.38s` | OK |
| `ubuntu:24.04` | ✅ PASS | `0` | `0.35s` | OK |
| `alpine:3.20` | ❌ FAIL | `127` | `0.19s` | ⚠️ Missing command: `apt-get` (line 4)<br>💡 *Alpine normally uses apk instead of apt-get.* |

<details>
<summary>📋 <b>Copyable Markdown (Click to expand & copy to PR / Issue)</b></summary>
...
</details>

🔍 Example: What Static Analysis Misses

Consider this clean deployment script:

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

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

However, when verified with OpsScript Gate:

+----------------+----------+-----------+----------+------------------------------------+
| Distro         | Status   | Exit Code | Duration | Details                            |
+----------------+----------+-----------+----------+------------------------------------+
| debian:12-slim | PASS     | 0         | 0.42s    | OK                                 |
| ubuntu:22.04   | PASS     | 0         | 0.38s    | OK                                 |
| ubuntu:24.04   | PASS     | 0         | 0.35s    | OK                                 |
| alpine:3.20    | FAIL     | 127       | 0.19s    | command not found: apt-get (line 4)|
+----------------+----------+-----------+----------+------------------------------------+
Total duration: 0.58s | Result: FAILED

Remediation Recommendations:
  * [alpine:3.20] Alpine normally uses apk instead of apt-get.

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

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

Why it failed: Alpine Linux is musl/BusyBox-based and uses apk, not apt-get. OpsScript Gate catches the missing command (exit code 127) and gives you the exact line number and conservative remediation hint before deployment.

🛡️ 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 & Hardened Isolation

OpsScript Gate is a runtime compatibility testing tool, not a security sandbox for hostile or fully untrusted code. Containers still share the host kernel, so target scripts should be treated accordingly.

When NOT to use OpsScript Gate

OpsScript Gate is intentionally focused on Linux shell runtime compatibility. It is not designed for:

• executing hostile or fully untrusted third-party scripts
• kernel-level or privileged behavior testing
• replacing full integration or end-to-end test suites
• validating macOS or Windows behavior
• proving that a script is secure

Use it when you want to know whether a shell script actually runs across the supported Linux distributions.

📦 Default Test Matrix

Customize the matrix at any time via --matrix or Action input matrix.

🛠️ CLI Reference

usage: opsscript-gate run [-h] [--matrix MATRIX] [-j JOBS] [--timeout TIMEOUT]
                          [--format {table,markdown,json}]
                          [--shell {posix,shebang,auto}]
                          [--mem-limit MEM_LIMIT] [--pids-limit PIDS_LIMIT]
                          [--network NETWORK]
                          [script_path]

Shell Execution Modes (--shell)

• posix (default): Strictly executes with /bin/sh, ignoring any script shebang to verify portability against minimal POSIX environments (including 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). Fails immediately if shebang is missing, malformed, or unsupported.
• auto: Honors recognized shebangs if present; safely falls back to /bin/sh if no shebang is present.

Exit Code Convention

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

v0.5.0 project controls

Explicit CLI options override project settings. Explicit script paths bypass discovery and its exclusions. See complete configuration semantics.

🌍 Real-World Usage

OpsScript Gate is actively used in Mresyzz/linux-dev-bootstrap to validate install.sh across the default Debian, Ubuntu, and Alpine matrix in GitHub Actions.

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

🧪 Development & Testing

# Clone repository
git clone https://github.com/Mresyzz/opsscript-gate.git
cd opsscript-gate

# Install in editable mode with test dependencies
pip install -e .[test]

# Run unit tests (Mocked, no Docker daemon required)
pytest -v -m "not integration"

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

💛 If OpsScript Gate Helps

If OpsScript Gate catches a compatibility problem in one of your scripts, consider starring the repository so other shell and DevOps maintainers can find it too.

Bug reports, real-world compatibility cases, and pull requests are especially welcome.

📄 License

OpsScript Gate is licensed under the MIT License.