Skip to content

configuration.md

Latest commit

 

History

History
151 lines (122 loc) · 6.07 KB

configuration.md

File metadata and controls

151 lines (122 loc) · 6.07 KB
Raw

Configure shell script compatibility tests

The controls below require v0.5.0. Existing v0.4.1 and earlier installations do not have these commands.

Start with a preview

opsscript-gate init
opsscript-gate doctor
opsscript-gate run --dry-run

init refuses to overwrite either .opsscript-gate.json or .github/workflows/opsscript-gate.yml. The generated workflow uses the v0.9.2 tag.

doctor checks Python and Docker connectivity without executing repository scripts. Use opsscript-gate doctor --format json when collecting a support report.

The generated config uses the two-image minimal preset, honors recognized shell shebangs, disables networking, and excludes tests/* and examples/*. Review these choices: an installer that downloads files needs network: bridge.

Project settings

Configuration is JSON, supported on all supported Python versions without extra dependencies. The CLI automatically reads .opsscript-gate.json in the current working directory. --config PATH selects another file; a missing explicit file is an error. Script paths and exclusion patterns remain relative to the working directory, not the config file's parent.

{
  "preset": "minimal",
  "shell": "auto",
  "network": "none",
  "packages": [],
  "timeout": 30,
  "repeat": 1,
  "jobs": 2,
  "mem_limit": "256m",
  "pids_limit": 128,
  "max_scripts": 50,
  "exclude": ["tests/*", "examples/*", "scripts/manual/*"]
}

These are all supported keys, plus matrix, a comma-separated image string used instead of preset. Unknown keys and incorrect value types are errors. Numeric limits must be positive integers. shell accepts posix, auto, shebang; network accepts none, bridge. packages is an optional list of package names to install inside each test container before the target script runs. The runner uses apt-get for Debian/Ubuntu images and apk for Alpine images. It accepts package names only, never shell commands, and requires network: bridge. The default is an empty list, so existing networking settings and execution remain unchanged. repeat runs each distribution more than once (up to 20 attempts) and reports FLAKY when at least one attempt passes and another fails. Keep it at 1 for the normal fast gate; use 3 or 5 while investigating intermittent CI failures.

Preset Images
minimal debian:12-slim, alpine:3.20
ubuntu ubuntu:22.04, ubuntu:24.04

Without a config or preset, the existing four-image default is unchanged. These are reproducible compatibility baselines, not a promise to track latest distro releases.

Explicit CLI flags override configuration. --matrix replaces a configured preset; --preset replaces a configured matrix. Providing both flags is an error. Repeated --exclude flags replace the configured exclusion list rather than append.

opsscript-gate run --exclude 'tests/*' --exclude 'vendor-scripts/*' --dry-run
opsscript-gate run scripts/install.sh --matrix alpine:3.20 --network bridge

Discovery rules

  • Files ending in .sh or .bash, or with recognized sh/bash shebangs, are candidates.
  • Empty files, files over 1 MiB, symlinks, hidden directories and common dependency/build directories are skipped.
  • Patterns match case-sensitive, repository-relative POSIX paths, without ./. This is Python fnmatch syntax, not gitignore syntax: * also matches /; tests/* therefore excludes all descendants. Negation (!) is not supported.
  • Results are sorted. More than max_scripts candidates is an error before any execution; narrow exclusions or explicitly increase the limit.
  • Explicit script paths bypass discovery filters and limits.
  • An empty selection is an error, not a passing compatibility check.

Reports and CI

opsscript-gate run --format json --output reports/compatibility.json
opsscript-gate run --repeat 3 --format markdown
opsscript-gate run --dry-run --format json --output reports/plan.json

--output saves the same report printed to the terminal, creates parent directories and returns failure if saving fails. Existing report files are replaced, but a target script or active configuration cannot be used as the output path. Failed compatibility checks still save their report and exit 1. Preview JSON is an execution plan, not a test result. Docker startup failures may occur before a report can be produced.

The Action accepts matching config, preset, max-scripts, dry-run, and output inputs; exclude is a multiline list. Omitted execution inputs preserve config values.

For pull requests, set changed-since to the base commit and fetch full Git history:

- uses: actions/checkout@v7
  with:
    fetch-depth: 0
- uses: Mresyzz/opsscript-gate@v0.9.2
  with:
    changed-since: ${{ github.event.pull_request.base.sha }}
    preset: minimal

The Action passes when no changed shell scripts are selected. This keeps unrelated documentation or application changes from starting container jobs.

- uses: Mresyzz/opsscript-gate@v0.9.2
  with:
    config: .opsscript-gate.json
    format: json
    output: reports/compatibility.json
    network: bridge
    packages: |
      curl
      ca-certificates
    exclude: |
      tests/*
      examples/*

Archive that path using your CI artifact uploader, with an always-run condition if you also want failed reports. GitHub annotations and the step summary remain automatic. In GitHub Actions, stdout can contain workflow annotations after JSON; use the saved report file for machine consumption.

Upgrade from v0.4.1 and earlier

The CLI defaults remain POSIX shell, bridge networking, 60 seconds, 256 MiB memory and 128 processes. New projects generated by init deliberately choose auto, offline networking and a smaller matrix. Existing users do not need to run init.

The intentional breaking corrections are that discovery overflow now fails and symlinked files are no longer automatically selected. Preview discovery after upgrading.

timeout is the hard limit per container in seconds. It must be between 1 and 3600. Custom matrix values may contain up to 32 container images.