ModRelease Gate

Run ModRelease Studio in GitHub Actions for every mod pull request. Get workflow annotations for blocking and advisory findings, a Markdown job summary, and downloadable JSON/Markdown reports.

· · MIT License

ModRelease Gate is a small composite action around the existing ModRelease Studio scanner. It does not comment on pull requests through the API, modify the checked-out mod, or upload source files. It uploads only the generated reports as a workflow artifact.

Quick start

Add this workflow to the mod repository as .github/workflows/modrelease.yml:

name: Mod release preflight

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  preflight:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: GhosTnever-lkm/modrelease-studio-action@v1.0.73
        with:
          mod-path: .
          tool-version: v0.3.91

The consumer workflow must check out its mod repository first. The action installs the scanner from its exact tagged GitHub source; it never runs pip install . in the consumer project.

Use a project-specific release policy

Create a modrelease.toml file in the checked-out mod repository and pass its workspace-relative path with config-file. The action rejects paths that resolve outside the checkout, including symlink escapes. ModRelease Studio v0.3.91 scans .env, .env.*, and *.env configuration files, detects temporary AWS access key IDs (ASIA…) and quoted AWS secret-key fields in JSON/YAML, reports multiple matching secret categories in the same file, and writes SARIF artifact URIs for unusual filesystem-encoded names and normalizes safe relative SARIF prefixes such as .. It also detects same-language localization keys repeated across YAML files as reviewable warnings, detects fine-grained GitHub personal access tokens (github_pat_) without echoing their value, detects Windows junctions on Python 3.11, and counts directory entries against the folder scan limit. Filesystem errors and shareable reports omit local parent directories. The action CI exercises this integration using examples/policy-project and synthetic environment-file fixtures.

- uses: GhosTnever-lkm/modrelease-studio-action@v1.0.73
  with:
    mod-path: .
    config-file: modrelease.toml
    tool-version: v0.3.91

Example policy:

[scan]
required_paths = ["descriptor.mod", "README.md"]
required_paths_severity = "ERROR"

Inputs

Input	Default	Purpose
mod-path	.	Mod folder or ZIP path relative to the checked-out workspace.
config-file	empty	Optional TOML configuration path relative to the checked-out workspace.
tool-version	v0.3.91	Exact scanner version with or without a leading v, such as 0.3.91 or v0.3.91.
python-version	3.12	Python runtime.
artifact-name	modrelease-report	Name of the uploaded reports artifact.
fail-on-warning	false	Also fail the workflow when advisory warnings exist. Errors always fail the scan.

The tool-version input accepts a strict major.minor.patch tag (no leading zeroes except for 0), with an optional leading v. The action pins its helper actions to major releases. GitHub-hosted runners are recommended; self-hosted runners need support for the Node runtime used by the referenced Actions.

What the workflow receives

• Annotations: up to 50 findings per run, mapped to GitHub error, warning, and notice annotations.
• Job summary: finding counts and a compact Markdown table.
• Artifact: modrelease-report.md, modrelease-report.json, and modrelease-report.sarif, available even when the scan reports blocking findings.
• Outputs: runner paths to JSON, Markdown, and SARIF reports (steps.<id>.outputs.json-report, markdown-report, and sarif-report), plus sarif-ready to confirm the SARIF file exists.

Annotation fields are escaped using GitHub's workflow-command encoding; untrusted control, bidi, and Unicode line-separator characters are shown as visible escapes in annotations and the Markdown summary. The scanner's messages do not include detected credential values. The workflow artifact includes the scanner's file manifest and paths; artifact access follows the mod repository's Actions permissions and retention policy.

Optional GitHub Code Scanning upload

SARIF is always included as a downloadable artifact. To also publish findings to the repository's Security → Code scanning page, add the upload step below after the scan. This is optional and separate from the Action. Set security-events: write only in a workflow that opts into uploading findings. SARIF paths automatically include the mod-path directory prefix for folder scans. Upload results only for a folder that is checked out in the repository; ZIP member paths do not necessarily map to committed source files. See GitHub's SARIF upload guide.

permissions:
  contents: read
  security-events: write

jobs:
  preflight:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - name: Scan the checked-out mod folder
        id: modrelease
        uses: GhosTnever-lkm/modrelease-studio-action@v1.0.73
        with:
          mod-path: mods/my-mod
      - name: Upload findings to Code Scanning
        if: always() && steps.modrelease.outputs.sarif-ready == 'true'
        uses: github/codeql-action/upload-sarif@v4
        with:
          sarif_file: ${{ steps.modrelease.outputs.sarif-report }}
          category: modrelease-studio

Development

The action and its annotation formatter use only Python's standard library.

python -m unittest discover -s tests -v

The fixture in examples/findings.sample.json contains placeholder paths and generic messages only; it does not contain real credentials or game files.

☕ Support

ModRelease Gate is free and open source. Support the author through Buy Me a Coffee, Boosty, or GitHub Sponsors.

License

MIT. See LICENSE.