opsscript-gate 0.4.1__tar.gz → 0.5.0__tar.gz

{opsscript_gate-0.4.1 → opsscript_gate-0.5.0}/.github/workflows/test.yml

@@ -8,7 +8,11 @@ on:
 
 jobs:
   test:
-    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ['3.10', '3.12']
+    runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout Code
         uses: actions/checkout@v7
@@ -16,7 +20,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v7
         with:
-          python-version: '3.12'
+          python-version: ${{ matrix.python }}
 
       - name: Install Dependencies
         run: |
@@ -50,3 +54,12 @@ jobs:
       - name: Run Docker Integration Tests
         run: |
           pytest -v -m integration
+
+      - name: Exercise the local composite Action
+        uses: ./
+        with:
+          script-path: tests/fixtures/pass_basic.sh
+          preset: minimal
+          network: none
+          output: action-report.json
+          format: json

{opsscript_gate-0.4.1 → opsscript_gate-0.5.0}/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [0.5.0] - 2026-09-24
+
+### Added
+- `init`: non-overwriting project configuration and GitHub workflow generation.
+- Shared, strictly validated `.opsscript-gate.json` settings; explicit CLI/Action inputs win.
+- Docker-free `--dry-run` plans in text or JSON, including execution counts.
+- `minimal` and `ubuntu` distribution presets, repeatable exclusion globs and configurable discovery limit.
+- `--output` report artifacts, including failure reports; source/config overwrite protection.
+- Action inputs for configuration, presets, exclusions, preview and saved reports.
+- Chinese quickstart, configuration guide and Ubuntu/Alpine troubleshooting guide.
+
+### Fixed
+- Discovery now fails on overflow instead of silently testing only the first 20 scripts.
+- Discovery skips symlinks and non-files and rejects shebang prefix collisions.
+- CLI rejects non-positive limits and unsupported network modes before execution.
+- Default Action inputs no longer override a user's project configuration.
+
+### Migration
+- Repositories with more than 20 discovered scripts must exclude unwanted scripts or raise `max_scripts`.
+- Auto-discovery no longer follows file symlinks; explicit script paths remain supported.
+- Default settings without a configuration file remain compatible with v0.4.1 and earlier.
+- Generated workflows use the v0.5.0 release tag.
+
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),

{opsscript_gate-0.4.1 → opsscript_gate-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: opsscript-gate
-Version: 0.4.1
+Version: 0.5.0
 Summary: Run Linux shell scripts across Debian, Ubuntu and Alpine before release to catch runtime compatibility failures
 Project-URL: Homepage, https://github.com/Mresyzz/opsscript-gate
 Project-URL: Repository, https://github.com/Mresyzz/opsscript-gate
@@ -26,7 +26,9 @@ Provides-Extra: test
 Requires-Dist: pytest>=8.0.0; extra == 'test'
 Description-Content-Type: text/markdown
 
-# OpsScript Gate
+# OpsScript Gate — shell script compatibility testing
+
+[简体中文](README.zh-CN.md) · [Configuration](docs/configuration.md) · [Troubleshooting](docs/troubleshooting.md)
 
 > **ShellCheck tells you if your script looks portable. OpsScript Gate checks if it actually runs there.**
 
@@ -41,8 +43,32 @@ Description-Content-Type: text/markdown
 
 **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.
+
+```bash
+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](docs/configuration.md) and
+[why a shell script works on Ubuntu but fails on Alpine](docs/troubleshooting.md).
+
 ## ⚡ 30-Second Quickstart
 
 ### In GitHub Actions (Zero Config)
@@ -58,15 +84,15 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: Mresyzz/opsscript-gate@v0.4.1
+      - uses: Mresyzz/opsscript-gate@v0.5.0
 ```
 
-> **Zero Config**: If `script-path` is omitted, OpsScript Gate automatically discovers shell scripts in your repository and tests them concurrently!
+> **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:
 
 ```yaml
-      - uses: Mresyzz/opsscript-gate@v0.4.1
+      - uses: Mresyzz/opsscript-gate@v0.5.0
         with:
           script-path: scripts/install.sh
           shell: auto
@@ -88,6 +114,35 @@ opsscript-gate run ./scripts/install.sh
 opsscript-gate run
 ```
 
+### Try a Real Failure in 30 Seconds
+
+Create `install.sh`:
+
+```sh
+#!/bin/sh
+set -e
+apt-get --version
+```
+
+Then run:
+
+```bash
+opsscript-gate run ./install.sh
+```
+
+A typical result across the default matrix looks like this:
+
+```text
+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
@@ -190,7 +245,10 @@ sh: line 4: apt-get: not found
 
 ## 🔒 Security Boundaries & Hardened Isolation
 
-OpsScript Gate is not a security sandbox for untrusted code. Containers may run as the image's default user, and Docker containers still share the host kernel.
+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.
+
+<details>
+<summary><strong>View security boundaries and runtime hardening details</strong></summary>
 
 OpsScript Gate applies conservative, restricted container defaults when running scripts:
 
@@ -208,22 +266,38 @@ OpsScript Gate applies conservative, restricted container defaults when running
 4. **Anti-Hang Deadlock Defense**:
    - Disables TTY and stdin (`stdin_open=False`, `tty=False`).
    - Disconnects standard input: `/bin/sh -c "... /tmp/target_script.sh </dev/null"`.
-   - Injects `DEBIAN_FRONTEND=noninteractive` and `CI=true`. Interactive prompts (`read -p`) fail immediately instead of hanging CI runners.
+   - Injects `DEBIAN_FRONTEND=noninteractive` and `CI=true`. Interactive prompts (`read -p`) fail instead of hanging CI runners.
 5. **Hard Timeout & Container Cleanup**:
    - Enforces configurable timeout (default: 60s). Timed-out containers are sent `SIGKILL` and marked `TIMED_OUT`.
    - Container removal is attempted from a `finally` block in normal, failure, and timeout execution paths.
 6. **Bounded Output & Memory Protection**:
-   - Captures container logs using an immediate rolling byte buffer capped at 256 KiB (`MAX_CAPTURED_LOG_BYTES`) and tail limited to 500 lines (`MAX_LOG_TAIL_LINES`), which bounds retained container log data to reduce memory-exhaustion risk.
+   - Captures container logs using a rolling byte buffer capped at 256 KiB (`MAX_CAPTURED_LOG_BYTES`) and a 500-line tail limit (`MAX_LOG_TAIL_LINES`) to reduce memory-exhaustion risk from runaway output.
 7. **Untrusted Log Neutralization & Terminal Defense**:
    - Neutralizes line-leading workflow commands (`[container] ::`) to prevent forged GitHub Actions annotations in CI runners.
-   - Strips ANSI escape sequences and dangerous C0 control characters, and normalizes carriage returns (`\r`) to defeat terminal line overwrite spoofing.
-   - Employs context-sensitive escaping (`escape_inline_code`, `escape_markdown_text`, `escape_markdown_table_cell`, `escape_html_text`, `format_safe_code_fence`) to prevent Step Summary layout disruptions.
+   - Strips ANSI escape sequences and dangerous C0 control characters, and normalizes carriage returns (`\r`) to defeat terminal line-overwrite spoofing.
+   - Employs context-sensitive escaping (`escape_inline_code`, `escape_markdown_text`, `escape_markdown_table_cell`, `escape_html_text`, `format_safe_code_fence`) to protect Step Summary output contexts.
 8. **Command Injection Defense**:
-   - OpsScript Gate's own annotations (`::error`) apply strict percent-encoding for all properties and message bodies, preventing workflow command injection.
+   - OpsScript Gate's own annotations (`::error`) apply strict percent-encoding for workflow-command fields and message bodies.
 9. **Bounded Streaming CRLF & Shebang Defense**:
-   - Stream-normalizes carriage returns in 64 KiB chunks, preserving lone CR bytes and bounds shebang parsing to 4096 bytes without whole-file memory allocation.
+   - Stream-normalizes CRLF in 64 KiB chunks and bounds shebang parsing to 4096 bytes without whole-file memory allocation.
    - Pre-normalizes scripts once before parallel matrix runs, sharing a read-only prepared path across worker threads.
 
+For the complete supported-version policy and vulnerability reporting guidance, see [SECURITY.md](SECURITY.md).
+
+</details>
+
+### 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
@@ -276,7 +350,23 @@ usage: opsscript-gate run [-h] [--matrix MATRIX] [-j JOBS] [--timeout TIMEOUT]
 
 ---
 
-## 🐶 Dogfooding
+### v0.5.0 project controls
+
+| Option | Purpose |
+| :--- | :--- |
+| `init` | Generate configuration and a GitHub workflow without overwriting files |
+| `--dry-run` | Preview selected scripts, images and total executions without Docker |
+| `--config PATH` | Load a specific JSON configuration file |
+| `--preset minimal` | Debian + Alpine (two container runs per script) |
+| `--preset ubuntu` | Ubuntu 22.04 + 24.04 |
+| `--exclude 'tests/*'` | Exclude a repository-relative glob; repeatable |
+| `--max-scripts 50` | Raise the default discovery limit of 20; overflow is an error |
+| `--output report.json` | Save the selected output format, including failed test reports |
+
+Explicit CLI options override project settings. Explicit script paths bypass discovery
+and its exclusions. See [complete configuration semantics](docs/configuration.md).
+
+## 🌍 Real-World Usage
 
 OpsScript Gate is actively used in [`Mresyzz/linux-dev-bootstrap`](https://github.com/Mresyzz/linux-dev-bootstrap) to validate `install.sh` across the default Debian, Ubuntu, and Alpine matrix in GitHub Actions.
 
@@ -303,6 +393,14 @@ 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](LICENSE).

{opsscript_gate-0.4.1 → opsscript_gate-0.5.0}/README.md

@@ -1,4 +1,6 @@
-# OpsScript Gate
+# OpsScript Gate — shell script compatibility testing
+
+[简体中文](README.zh-CN.md) · [Configuration](docs/configuration.md) · [Troubleshooting](docs/troubleshooting.md)
 
 > **ShellCheck tells you if your script looks portable. OpsScript Gate checks if it actually runs there.**
 
@@ -13,8 +15,32 @@
 
 **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.
+
+```bash
+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](docs/configuration.md) and
+[why a shell script works on Ubuntu but fails on Alpine](docs/troubleshooting.md).
+
 ## ⚡ 30-Second Quickstart
 
 ### In GitHub Actions (Zero Config)
@@ -30,15 +56,15 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: Mresyzz/opsscript-gate@v0.4.1
+      - uses: Mresyzz/opsscript-gate@v0.5.0
 ```
 
-> **Zero Config**: If `script-path` is omitted, OpsScript Gate automatically discovers shell scripts in your repository and tests them concurrently!
+> **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:
 
 ```yaml
-      - uses: Mresyzz/opsscript-gate@v0.4.1
+      - uses: Mresyzz/opsscript-gate@v0.5.0
         with:
           script-path: scripts/install.sh
           shell: auto
@@ -60,6 +86,35 @@ opsscript-gate run ./scripts/install.sh
 opsscript-gate run
 ```
 
+### Try a Real Failure in 30 Seconds
+
+Create `install.sh`:
+
+```sh
+#!/bin/sh
+set -e
+apt-get --version
+```
+
+Then run:
+
+```bash
+opsscript-gate run ./install.sh
+```
+
+A typical result across the default matrix looks like this:
+
+```text
+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
@@ -162,7 +217,10 @@ sh: line 4: apt-get: not found
 
 ## 🔒 Security Boundaries & Hardened Isolation
 
-OpsScript Gate is not a security sandbox for untrusted code. Containers may run as the image's default user, and Docker containers still share the host kernel.
+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.
+
+<details>
+<summary><strong>View security boundaries and runtime hardening details</strong></summary>
 
 OpsScript Gate applies conservative, restricted container defaults when running scripts:
 
@@ -180,22 +238,38 @@ OpsScript Gate applies conservative, restricted container defaults when running
 4. **Anti-Hang Deadlock Defense**:
    - Disables TTY and stdin (`stdin_open=False`, `tty=False`).
    - Disconnects standard input: `/bin/sh -c "... /tmp/target_script.sh </dev/null"`.
-   - Injects `DEBIAN_FRONTEND=noninteractive` and `CI=true`. Interactive prompts (`read -p`) fail immediately instead of hanging CI runners.
+   - Injects `DEBIAN_FRONTEND=noninteractive` and `CI=true`. Interactive prompts (`read -p`) fail instead of hanging CI runners.
 5. **Hard Timeout & Container Cleanup**:
    - Enforces configurable timeout (default: 60s). Timed-out containers are sent `SIGKILL` and marked `TIMED_OUT`.
    - Container removal is attempted from a `finally` block in normal, failure, and timeout execution paths.
 6. **Bounded Output & Memory Protection**:
-   - Captures container logs using an immediate rolling byte buffer capped at 256 KiB (`MAX_CAPTURED_LOG_BYTES`) and tail limited to 500 lines (`MAX_LOG_TAIL_LINES`), which bounds retained container log data to reduce memory-exhaustion risk.
+   - Captures container logs using a rolling byte buffer capped at 256 KiB (`MAX_CAPTURED_LOG_BYTES`) and a 500-line tail limit (`MAX_LOG_TAIL_LINES`) to reduce memory-exhaustion risk from runaway output.
 7. **Untrusted Log Neutralization & Terminal Defense**:
    - Neutralizes line-leading workflow commands (`[container] ::`) to prevent forged GitHub Actions annotations in CI runners.
-   - Strips ANSI escape sequences and dangerous C0 control characters, and normalizes carriage returns (`\r`) to defeat terminal line overwrite spoofing.
-   - Employs context-sensitive escaping (`escape_inline_code`, `escape_markdown_text`, `escape_markdown_table_cell`, `escape_html_text`, `format_safe_code_fence`) to prevent Step Summary layout disruptions.
+   - Strips ANSI escape sequences and dangerous C0 control characters, and normalizes carriage returns (`\r`) to defeat terminal line-overwrite spoofing.
+   - Employs context-sensitive escaping (`escape_inline_code`, `escape_markdown_text`, `escape_markdown_table_cell`, `escape_html_text`, `format_safe_code_fence`) to protect Step Summary output contexts.
 8. **Command Injection Defense**:
-   - OpsScript Gate's own annotations (`::error`) apply strict percent-encoding for all properties and message bodies, preventing workflow command injection.
+   - OpsScript Gate's own annotations (`::error`) apply strict percent-encoding for workflow-command fields and message bodies.
 9. **Bounded Streaming CRLF & Shebang Defense**:
-   - Stream-normalizes carriage returns in 64 KiB chunks, preserving lone CR bytes and bounds shebang parsing to 4096 bytes without whole-file memory allocation.
+   - Stream-normalizes CRLF in 64 KiB chunks and bounds shebang parsing to 4096 bytes without whole-file memory allocation.
    - Pre-normalizes scripts once before parallel matrix runs, sharing a read-only prepared path across worker threads.
 
+For the complete supported-version policy and vulnerability reporting guidance, see [SECURITY.md](SECURITY.md).
+
+</details>
+
+### 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
@@ -248,7 +322,23 @@ usage: opsscript-gate run [-h] [--matrix MATRIX] [-j JOBS] [--timeout TIMEOUT]
 
 ---
 
-## 🐶 Dogfooding
+### v0.5.0 project controls
+
+| Option | Purpose |
+| :--- | :--- |
+| `init` | Generate configuration and a GitHub workflow without overwriting files |
+| `--dry-run` | Preview selected scripts, images and total executions without Docker |
+| `--config PATH` | Load a specific JSON configuration file |
+| `--preset minimal` | Debian + Alpine (two container runs per script) |
+| `--preset ubuntu` | Ubuntu 22.04 + 24.04 |
+| `--exclude 'tests/*'` | Exclude a repository-relative glob; repeatable |
+| `--max-scripts 50` | Raise the default discovery limit of 20; overflow is an error |
+| `--output report.json` | Save the selected output format, including failed test reports |
+
+Explicit CLI options override project settings. Explicit script paths bypass discovery
+and its exclusions. See [complete configuration semantics](docs/configuration.md).
+
+## 🌍 Real-World Usage
 
 OpsScript Gate is actively used in [`Mresyzz/linux-dev-bootstrap`](https://github.com/Mresyzz/linux-dev-bootstrap) to validate `install.sh` across the default Debian, Ubuntu, and Alpine matrix in GitHub Actions.
 
@@ -275,6 +365,14 @@ 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](LICENSE).

opsscript_gate-0.5.0/README.zh-CN.md

@@ -0,0 +1,67 @@
+# OpsScript Gate：Shell 脚本跨发行版运行检查
+
+[English](README.md) · [配置说明](docs/configuration.md) · [常见问题](docs/troubleshooting.md)
+
+在 Debian、Ubuntu、Alpine 容器里实际运行 Shell 脚本，提前发现缺失命令、
+Bash 依赖、包管理器假设和交互式阻塞。它与 ShellCheck 互补。
+
+适合独立安装脚本、容器入口脚本和发布脚本。每次只挂载目标脚本，
+不挂载整个仓库；依赖其他仓库文件的脚本需要现有项目测试配合。
+
+## 试用本次 v0.5.0 更新
+
+v0.5.0 已作为正式版本发布；如果你要从源码验证当前分支，也可以执行：
+
+```bash
+pip install -e .
+opsscript-gate run examples/basic/clean_setup.sh --dry-run
+```
+
+在你希望接入检查的仓库根目录执行：
+
+```bash
+opsscript-gate init
+opsscript-gate run --dry-run
+opsscript-gate run --format json --output reports/compatibility.json
+```
+
+`init` 生成配置和 GitHub 工作流，不覆盖已有文件。工作流引用 `v0.5.0`。
+预览不需要 Docker；真实运行需要 Python 3.10+
+和可访问的 Linux Docker 引擎。
+
+生成的配置默认排除 `tests/*`、`examples/*`，使用 Debian + Alpine，尊重
+脚本 shebang，并关闭网络。请根据实际脚本审核配置；需要下载文件时启用
+`--network bridge`。保留现有无配置行为：四个发行版、POSIX shell、bridge 网络。
+
+## 本轮改进
+
+- 运行前展示脚本、镜像和总容器执行次数。
+- 本地与 GitHub Actions 共用 `.opsscript-gate.json`。
+- 排除规则、发行版预设、扫描数量限制。
+- 超过扫描上限明确报错，避免只测前 20 个却误以为全部通过。
+- 报告保存为 JSON、Markdown 或文本，失败时同样保留结果。
+- 自动发现跳过符号链接，并严格校验配置与执行参数。
+
+返回码 `0` 表示全部通过，`1` 表示检查失败或发生错误。`--dry-run` 成功只表示
+执行计划生成成功。容器不是不可信代码的安全沙箱。
+
+## 示例：为什么 Alpine 上会失败
+
+```sh
+#!/bin/sh
+set -e
+apt-get --version
+```
+
+这个脚本可以符合 POSIX 语法，但 Alpine 使用 `apk`，实际执行会暴露命令缺失。
+查看 [Ubuntu／Alpine 排错说明](docs/troubleshooting.md) 获取常见原因与修复方向。
+
+## 测试
+
+```bash
+pip install -e '.[test]'
+pytest -q -m 'not integration'
+pytest -q -m integration
+```
+
+第二组需要 Docker。跳过容器测试不能算作完整集成验证。

opsscript_gate-0.5.0/action.yml

@@ -0,0 +1,130 @@
+name: 'OpsScript Gate'
+description: 'Run Linux shell scripts across Debian, Ubuntu and Alpine before release to catch runtime compatibility failures'
+author: 'Mresyzz'
+branding:
+  icon: 'shield'
+  color: 'blue'
+
+inputs:
+  script-path:
+    description: 'Path to the target shell script to test (auto-discovers repository scripts if omitted)'
+    required: false
+    default: ''
+  matrix:
+    description: 'Comma-separated container images to test (e.g. debian:12-slim,ubuntu:22.04,ubuntu:24.04,alpine:3.20)'
+    required: false
+    default: ''
+  jobs:
+    description: 'Number of parallel container execution jobs (default: min(2, matrix_size))'
+    required: false
+    default: ''
+  timeout:
+    description: 'Hard timeout in seconds per container (default: 60)'
+    required: false
+    default: ''
+  format:
+    description: 'Output report format: table, markdown, or json'
+    required: false
+    default: ''
+  shell:
+    description: "Shell execution mode: 'posix' (default), 'shebang', or 'auto'"
+    required: false
+    default: ''
+  mem-limit:
+    description: 'Memory limit for containers (default: 256m)'
+    required: false
+    default: ''
+  pids-limit:
+    description: 'Maximum number of processes per container (default: 128)'
+    required: false
+    default: ''
+  network:
+    description: "Container network mode: 'bridge' or 'none' (default: bridge)"
+    required: false
+    default: ''
+
+  config:
+    description: 'Path to project JSON configuration'
+    required: false
+    default: ''
+  preset:
+    description: 'Distribution preset: minimal or ubuntu'
+    required: false
+    default: ''
+  exclude:
+    description: 'Newline-separated repository-relative exclusion globs'
+    required: false
+    default: ''
+  max-scripts:
+    description: 'Maximum discovered scripts; exceeding the limit fails'
+    required: false
+    default: ''
+  dry-run:
+    description: 'Preview the execution plan without Docker'
+    required: false
+    default: 'false'
+  output:
+    description: 'Save a report file for upload-artifact or other tooling'
+    required: false
+    default: ''
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Set up Python
+      uses: actions/setup-python@v7
+      with:
+        python-version: '3.12'
+
+    - name: Install opsscript-gate
+      shell: bash
+      run: |
+        pip install "${{ github.action_path }}"
+
+    - name: Run compatibility gate
+      shell: bash
+      env:
+        INPUT_SCRIPT_PATH: ${{ inputs.script-path }}
+        INPUT_MATRIX: ${{ inputs.matrix }}
+        INPUT_JOBS: ${{ inputs.jobs }}
+        INPUT_TIMEOUT: ${{ inputs.timeout }}
+        INPUT_FORMAT: ${{ inputs.format }}
+        INPUT_SHELL: ${{ inputs.shell }}
+        INPUT_MEM_LIMIT: ${{ inputs.mem-limit }}
+        INPUT_PIDS_LIMIT: ${{ inputs.pids-limit }}
+        INPUT_NETWORK: ${{ inputs.network }}
+        INPUT_CONFIG: ${{ inputs.config }}
+        INPUT_PRESET: ${{ inputs.preset }}
+        INPUT_EXCLUDE: ${{ inputs.exclude }}
+        INPUT_MAX_SCRIPTS: ${{ inputs.max-scripts }}
+        INPUT_DRY_RUN: ${{ inputs.dry-run }}
+        INPUT_OUTPUT: ${{ inputs.output }}
+      run: |
+        ARGS=("run")
+        if [ -n "$INPUT_SCRIPT_PATH" ]; then
+          ARGS+=("$INPUT_SCRIPT_PATH")
+        fi
+        # Only explicit inputs override project configuration.
+        [ -z "$INPUT_TIMEOUT" ] || ARGS+=(--timeout "$INPUT_TIMEOUT")
+        [ -z "$INPUT_FORMAT" ] || ARGS+=(--format "$INPUT_FORMAT")
+        [ -z "$INPUT_SHELL" ] || ARGS+=(--shell "$INPUT_SHELL")
+        [ -z "$INPUT_MEM_LIMIT" ] || ARGS+=(--mem-limit "$INPUT_MEM_LIMIT")
+        [ -z "$INPUT_PIDS_LIMIT" ] || ARGS+=(--pids-limit "$INPUT_PIDS_LIMIT")
+        [ -z "$INPUT_NETWORK" ] || ARGS+=(--network "$INPUT_NETWORK")
+        [ -z "$INPUT_MATRIX" ] || ARGS+=(--matrix "$INPUT_MATRIX")
+        [ -z "$INPUT_JOBS" ] || ARGS+=(--jobs "$INPUT_JOBS")
+        [ -z "$INPUT_CONFIG" ] || ARGS+=(--config "$INPUT_CONFIG")
+        [ -z "$INPUT_PRESET" ] || ARGS+=(--preset "$INPUT_PRESET")
+        [ -z "$INPUT_MAX_SCRIPTS" ] || ARGS+=(--max-scripts "$INPUT_MAX_SCRIPTS")
+        [ -z "$INPUT_OUTPUT" ] || ARGS+=(--output "$INPUT_OUTPUT")
+        while IFS= read -r pattern; do
+          pattern="${pattern%$'\r'}"
+          [ -z "$pattern" ] || ARGS+=("--exclude" "$pattern")
+        done <<< "$INPUT_EXCLUDE"
+        if [ "$INPUT_DRY_RUN" = "true" ]; then
+          ARGS+=("--dry-run")
+        elif [ "$INPUT_DRY_RUN" != "false" ]; then
+          echo "dry-run must be true or false" >&2
+          exit 1
+        fi
+        python -m opsscript_gate.cli "${ARGS[@]}"