feat: release OpsScript Gate v0.4.0 with annotations, parallel execution, and hardened runtime controls

Release OpsScript Gate v0.4.0 with a major upgrade to runtime compatibility diagnostics, GitHub Actions integration, execution performance, and container safety controls.

Key changes:

Add high-confidence GitHub Actions line-level annotations for runtime failures, including exact script paths and line numbers.
Normalize annotation paths to repository-relative POSIX paths so annotations correctly map to pull request diffs.
Add workflow-command escaping to prevent untrusted container output from injecting GitHub Actions commands.
Add deterministic, distro-aware remediation hints for common compatibility failures such as apt/apk mismatches, missing Bash, missing curl/wget, and unsupported shebang interpreters.
Redesign the GitHub Step Summary with a compatibility matrix, actionable diagnostics, and copyable Markdown output.
Add parallel distro execution through --jobs while preserving deterministic report ordering.
Add container resource controls with configurable memory limits, PID limits, and network mode.
Add zero-config shell script discovery when no script path is provided.
Ignore common generated and dependency directories including .git, node_modules, vendor, target, dist, build, venv, and .venv during auto-discovery.
Add MultiScriptReport support for consolidated multi-script results and correct failure propagation.
Optimize GitHub Action startup by removing unnecessary pip upgrade work.
Refine README and SECURITY documentation to accurately describe hardened container defaults without presenting the execution environment as a complete security sandbox.
Clarify that container cleanup is attempted across normal, failure, and timeout execution paths rather than making an absolute cleanup guarantee.
Expand regression coverage for annotations, escaping, path normalization, discovery exclusions, parallel execution, timeouts, resource limits, and reporting.

Validation:

53 unit tests passed locally.
GitHub Actions test workflow passed across supported Python versions.
Real Docker integration tests passed.
End-to-end demo workflow passed on GitHub Actions.
Verified Debian 12, Ubuntu 22.04, Ubuntu 24.04, and Alpine 3.20 compatibility reporting.
Verified a real Alpine apt-get failure produces the expected line-level GitHub annotation and remediation hint.

This release preserves the existing CLI and GitHub Action workflow while making OpsScript Gate faster, easier to adopt, and significantly more useful during pull request review.

Author: Mresyzz

.github/workflows/demo.yml

@@ -3,6 +3,8 @@ name: Demo Shell Script Compatibility Gate
 on:
   push:
     branches: [ main ]
+  pull_request:
+    branches: [ main ]
   workflow_dispatch:
 
 jobs:

CHANGELOG.md

@@ -5,6 +5,30 @@ 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/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-09-19
+
+### Added
+- **High-confidence line-level GitHub Actions annotations**: Emits inline `::error` annotations with exact script line numbers directly on pull request file diffs.
+- **Workflow command injection defense**: Strictly escapes parameters (`%`, `\r`, `\n`, `:`, `,`) and message bodies (`%`, `\r`, `\n`) to eliminate command injection from unclassified container logs.
+- **Conservative distro-aware remediation hints**: Suggests testable, high-confidence remediation recommendations (`RemediationRule`) with conservative phrasing (`normally`, `may`, `consider`), covering:
+  - Alpine package manager mismatches (`apt`/`apt-get` -> `apk`)
+  - Debian/Ubuntu package manager mismatches (`apk` -> `apt-get`)
+  - Alpine minimal missing Bash (`bash` -> consider POSIX sh or installing bash)
+  - Missing network prerequisites (`curl`, `wget`)
+  - Missing shebang interpreter paths.
+- **Re-engineered Compatibility Card**: Overhauled GitHub Actions Step Summary with an instant 5-second triage table and an expandable copy-pasteable Markdown snippet ready for PR descriptions and Issue comments.
+- **Parallel matrix execution (`--jobs` / `jobs`)**: Concurrently runs container checks using `ThreadPoolExecutor` (defaults to `min(2, matrix_size)`), strictly preserving matrix output order and ensuring reliable container cleanup.
+- **Hardened container resource limits**: Added `--mem-limit` (default: 256m) and `--pids-limit` (default: 128) flags and Action inputs to prevent runaway resource exhaustion.
+- **Configurable network isolation (`--network`)**: Supports `--network bridge` (default) and `--network none` for offline script execution.
+- **Zero-config repository script auto-discovery**: Running `opsscript-gate run` without arguments automatically discovers and validates shell scripts in the repository, ignoring directories like `.git`, `node_modules`, and `.venv`, capped at 20 scripts and 1 MB per file.
+- **Multi-script test consolidation (`MultiScriptReport`)**: Supports aggregate reporting and Step Summary cards when multiple scripts are evaluated in a single run.
+
+### Changed
+- **Action initialization performance**: Removed redundant `pip install --upgrade pip` step in composite `action.yml` to minimize Action startup latency.
+- **Flexible Action inputs**: Made `script-path` optional in `action.yml` (triggers auto-discovery if omitted); added inputs `jobs`, `mem-limit`, `pids-limit`, and `network`.
+
+---
+
 ## [0.3.0] - 2026-09-19
 
 ### Added

README.md

@@ -1,30 +1,41 @@
 # OpsScript Gate Roadmap
 
-This roadmap tracks features being considered for future releases.
+This roadmap tracks features delivered in recent releases and areas under consideration for future versions.
 
-> **Note:** Features listed below are planned or under consideration; they are not implemented in current releases.
+---
+
+## Delivered in v0.4.0
+
+- [x] **High-confidence Line-level GitHub Actions Annotations**: Emits safe `::error` annotations linking failure lines directly on pull request file diffs.
+- [x] **Distro-aware Remediation Hints**: Conservative, testable hints for Alpine vs Debian package managers, missing bash interpreters, and core utilities.
+- [x] **Interactive Compatibility Card & Copyable Summary**: Rich GitHub Actions Step Summary table with copy-pasteable Markdown snippets for PR/Issue triage.
+- [x] **Parallel Matrix Execution (`--jobs` / `jobs`)**: Concurrent multi-container testing via `ThreadPoolExecutor` with strict matrix order preservation.
+- [x] **Hardened Resource Limits**: Added `--mem-limit` (default: 256m) and `--pids-limit` (default: 128) container controls.
+- [x] **Configurable Network Isolation (`--network none|bridge`)**: Run scripts offline when network access is not required.
+- [x] **Zero-Config Script Auto-Discovery**: Automatically discovers candidate shell scripts in repository root when `script_path` is omitted.
+- [x] **Composite Action Initialization Optimization**: Stripped redundant pip upgrade steps for rapid Action startup.
 
 ---
 
-## Planned Features
+## Delivered in v0.2.0 - v0.3.0
 
-### 1. Execution Modes (`--shell`)
-- [x] **Shebang-aware execution (`--shell shebang | auto`)**: Implemented in v0.2.0. Parses and honors recognized shebang forms (`sh`, `bash`) across distributions using fixed trusted container commands.
-- [x] **Explicit POSIX mode (`--shell posix`)**: Implemented in v0.2.0. Retains `/bin/sh` baseline across all containers to verify strict POSIX portability.
+- [x] **Structured Runtime Failure Diagnostics**: Detects "command not found" errors with exit code 127 validation (v0.3.0).
+- [x] **Shebang-aware execution (`--shell shebang | auto`)**: Parses and honors recognized shebang forms (`sh`, `bash`) across distributions using fixed trusted container commands (v0.2.0).
+- [x] **Explicit POSIX mode (`--shell posix`)**: Retains `/bin/sh` baseline across all containers to verify strict POSIX portability (v0.2.0).
+
+---
 
-### 2. Resource Constraints
-- [ ] **Memory limits (`--mem-limit`)**: Planned. Constrain container memory usage for scripts under test.
-- [ ] **PID limits (`--pids-limit`)**: Under consideration. Guard against fork bombs within the timeout window.
+## Planned for Future Releases (v0.5.0+)
 
-### 3. Network Isolation
-- [ ] **Offline execution (`--network none`)**: Planned. Run verification without network access for scripts that should not require network connectivity.
+### 1. Matrix & Distribution Presets
+- [ ] **RPM-based distributions**: Evaluate support for Enterprise Linux baselines (e.g. Rocky Linux 9, AlmaLinux, Fedora).
+- [ ] **Matrix presets**: Predefined profiles (e.g. `--preset minimal`, `--preset enterprise`, `--preset all`).
 
-### 4. Matrix & Distribution Presets
-- [ ] **Additional distributions**: Under evaluation (e.g. Rocky Linux, Fedora).
-- [ ] **Parallel container execution**: Under consideration to reduce execution time on multi-core runners.
+### 2. Performance & Caching
+- [ ] **Docker image pre-pull & caching action**: Optional helper step to leverage GitHub Actions cache for test container base images.
 
-### 5. Tooling & CI Integration
-- [ ] **GitHub Workflow Problem Matchers**: Under consideration. Provide inline annotations on pull request diffs for failure lines.
+### 3. Pre-run Setup Hooks
+- [ ] **Script prerequisites hook**: Declarative environment setup (e.g. install custom apt packages before testing the target script).
 
 ---
 

ROADMAP.md

@@ -6,9 +6,9 @@ Only the latest release of **OpsScript Gate** receives security updates and bug
 
 | Version | Supported          |
 | :---    | :---:              |
-| 0.2.x   | :white_check_mark: |
-| 0.1.x   | :x:                |
-| < 0.1.0 | :x:                |
+| 0.4.x   | :white_check_mark: |
+| 0.3.x   | :white_check_mark: |
+| < 0.3.0 | :x:                |
 
 ---
 
@@ -34,5 +34,7 @@ OpsScript Gate is not a security sandbox for untrusted code. Containers may run
 
 OpsScript Gate applies conservative container defaults when running scripts:
 - **Restricted Container Defaults**: Containers run with `privileged=False`, `cap_drop=["ALL"]`, and `security_opt=["no-new-privileges:true"]`.
+- **Resource Limits & Isolation**: Enforces memory caps (`--mem-limit`, default 256m), process table caps (`--pids-limit`, default 128), and optional network isolation (`--network none`).
 - **Read-Only Mounting**: Target scripts are mounted read-only (`:ro`). OpsScript Gate does not mount additional host filesystem paths into test containers.
-- **Resource Protection**: Containers are subject to timeouts and `SIGKILL` termination. Container removal is attempted from a `finally` block during normal Python execution paths, including failures and timeouts.
+- **Resource Protection & Hard Timeout**: Containers are subject to hard timeouts (default 60s) with `SIGKILL` termination. Container removal is attempted from a `finally` block in normal, failure, and timeout execution paths.
+- **Workflow Command Injection Defense**: All GitHub Actions workflow commands (`::error`) apply strict percent-encoding for properties (`%`, `\r`, `\n`, `:`, `,`) and data (`%`, `\r`, `\n`), completely preventing command injection from unclassified container output.

SECURITY.md

@@ -7,12 +7,17 @@ branding:
 
 inputs:
   script-path:
-    description: 'Path to the target shell script to test'
-    required: true
+    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: 'debian:12-slim,ubuntu:22.04,ubuntu:24.04,alpine:3.20'
+  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
@@ -25,6 +30,18 @@ inputs:
     description: "Shell execution mode: 'posix' (default), 'shebang', or 'auto'"
     required: false
     default: 'posix'
+  mem-limit:
+    description: 'Memory limit for containers (default: 256m)'
+    required: false
+    default: '256m'
+  pids-limit:
+    description: 'Maximum number of processes per container (default: 128)'
+    required: false
+    default: '128'
+  network:
+    description: "Container network mode: 'bridge' or 'none' (default: bridge)"
+    required: false
+    default: 'bridge'
 
 runs:
   using: 'composite'
@@ -37,26 +54,37 @@ runs:
     - name: Install opsscript-gate
       shell: bash
       run: |
-        python -m pip install --upgrade pip
         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 }}
       run: |
-        ARGS=(
-          "run"
-          "$INPUT_SCRIPT_PATH"
+        ARGS=("run")
+        if [ -n "$INPUT_SCRIPT_PATH" ]; then
+          ARGS+=("$INPUT_SCRIPT_PATH")
+        fi
+        ARGS+=(
           "--timeout" "$INPUT_TIMEOUT"
           "--format" "$INPUT_FORMAT"
           "--shell" "$INPUT_SHELL"
+          "--mem-limit" "$INPUT_MEM_LIMIT"
+          "--pids-limit" "$INPUT_PIDS_LIMIT"
+          "--network" "$INPUT_NETWORK"
         )
         if [ -n "$INPUT_MATRIX" ]; then
           ARGS+=("--matrix" "$INPUT_MATRIX")
         fi
+        if [ -n "$INPUT_JOBS" ]; then
+          ARGS+=("--jobs" "$INPUT_JOBS")
+        fi
         python -m opsscript_gate.cli "${ARGS[@]}"

action.yml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "opsscript-gate"
-version = "0.3.0"
+version = "0.4.0"
 description = "Run Linux shell scripts across Debian, Ubuntu and Alpine before release to catch runtime compatibility failures"
 readme = "README.md"
 license = { text = "MIT" }

pyproject.toml

@@ -1,4 +1,4 @@
 """OpsScript Gate: Lightweight cross-distro compatibility pre-check for Linux ops scripts."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 __all__ = ["__version__"]