GitHub Action — Quality Gate for PR Checks & SARIF Upload

Use the Marketplace wrapper when you want plugin-scanner in pull requests, release checks, or registry submission workflows.

The action is published in its own repository. Its source of truth is the action/ directory of the scanner repository:

hashgraph-online/ai-plugin-scanner-action (Marketplace repository)
hashgraph-online/hol-guard, action directory (source)

The older slug hashgraph-online/hol-codex-plugin-scanner-action@v1 still works as a compatibility alias. Use ai-plugin-scanner-action for new workflows.

Minimal quality gate

- name: AI plugin quality gate
  uses: hashgraph-online/ai-plugin-scanner-action@v1
  with:
    plugin_dir: "."
    mode: scan
    fail_on_severity: high
    min_score: 80

Each release is published with an immutable v1.x.y tag, and the floating v1 tag moves to the latest compatible release. @v1 is convenient, but the code behind it changes. For a reproducible gate, pin an exact release tag or a full commit SHA:

# Immutable release tag
- uses: hashgraph-online/[email protected]

# Full commit SHA, the strictest form
- uses: hashgraph-online/ai-plugin-scanner-action@<full-commit-sha>

Check the releases page for the latest tag. By default the action installs an exact, reviewed plugin-scanner release from PyPI with hash-locked dependencies, and verifies the wheel's PyPI provenance before installing it.

Modes

mode selects what the action runs:

scan (default) for weighted quality scoring
lint for authoring feedback and rule-level findings
verify for manifest, marketplace, and MCP readiness checks
submit for artifact-backed submission gating on one plugin directory

Inputs

Input	Default	Purpose
`plugin_dir`	`.`	one plugin directory or a marketplace root
`mode`	`scan`	`scan`, `lint`, `verify`, or `submit`
`format`	`text`	`text`, `json`, `markdown`, or `sarif`
`output`	none	write the report to this path
`profile`	`default`	`default`, `public-marketplace`, or `strict-security`
`config`, `baseline`	none	scanner config file and baseline suppression file, used only when `trust_repository_policy` is `true`
`trust_repository_policy`	`false`	let repository-owned config and baselines change the verdict
`min_score`	`0`	fail below this score
`fail_on_severity`	`none`	fail at or above `critical`, `high`, `medium`, `low`, or `info`
`online`	`false`	permit network probing in `verify` mode and external analyzer credentials
`upload_sarif`	`false`	upload SARIF to code scanning in `scan` mode
`sarif_category`	`ai-plugin-scanner`	SARIF category used for the upload
`write_step_summary`	`true`	write a job summary
`registry_payload_output`	none	write the registry payload JSON to this path
`cisco_skill_scan`	`auto`	`auto`, `on`, or `off`
`cisco_policy`	`balanced`	`permissive`, `balanced`, or `strict`
`install_cisco`	`false`	install the optional Cisco skill scanner dependency
`install_source`	`pypi`	`pypi` for the reviewed release, or `local` for the scanner repository itself

The submission inputs (submission_enabled, submission_token, submission_score_threshold, and related) are covered in Submission and registry payloads. The action also has pr_comment, pr_comment_style, and pr_comment_max_findings inputs, but the Marketplace wrapper currently reports pr_comment_status as skipped. To comment on pull requests, post the markdown report from your own step.

trust_repository_policy is off by default, so .plugin-scanner.toml, baseline files, and the config and baseline inputs do not change the action's verdict. The profile, min_score, and fail_on_severity inputs still apply. Turn it on only for policy you intend the workflow to trust.

online is off by default. While it is off, the action also removes MCP_SCANNER_API_KEY and MCP_SCANNER_LLM_API_KEY from the scan environment so repository content is not sent to external analyzers.

Outputs

Output	Meaning
`score`, `grade`, `grade_label`	numeric score, letter grade, and label
`policy_pass`	whether the selected profile passed
`verify_pass`	`true` when the run performed verification and it passed (`verify` and `submit` modes)
`max_severity`	most severe finding, or `none`
`findings_total`	finding count across all severities
`report_path`	the report file, when `output` is set
`registry_payload_path`	the registry payload file, when requested
`submission_eligible`, `submission_performed`	whether the plugin qualified for a submission issue and whether one was created or reused
`submission_issue_urls`, `submission_issue_numbers`	comma-separated issue URLs and numbers
`action_exit_code`	the action's exit code

Typical pull request flow

check out the repository
run the action on pull requests with mode: scan or mode: verify
set upload_sarif: true when you want code scanning annotations
fail the workflow on severity or minimum-score thresholds
switch to submit only when the repository is ready to emit release or registry artifacts

Example with SARIF

The action can upload SARIF itself. The calling workflow needs security-events: write:

permissions:
  contents: read
  security-events: write

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - name: Scan plugin
        uses: hashgraph-online/ai-plugin-scanner-action@v1
        with:
          plugin_dir: "."
          mode: scan
          format: sarif
          fail_on_severity: high
          upload_sarif: true

To upload in a separate step, write the file with output and pass steps.<id>.outputs.report_path to github/codeql-action/upload-sarif.

Action and CLI together

The common split is:

hol-guard on developer machines for local harness protection
plugin-scanner in CI for maintainer and release gates, installed from the same repository
ai-plugin-scanner-action when you want the scanner wrapped for GitHub Actions

Teams that prefer a reviewed container image over runtime installation can run ghcr.io/hashgraph-online/hol-guard with the plugin-scanner entrypoint instead. See Policies, output, and trust provenance.

GitHub Action quality gate