Zenzic GitHub Action Reference¶

The PythonWoods/zenzic-action action is the official CI enforcement point for the Zenzic documentation quality system. In non-audit mode it executes a three-stage validation pipeline: zenzic check all (structural findings), zenzic score (DQS governance: fail_under + suppression_cap), and zenzic score --check-stamp (badge freshness, enabled by default). Findings are surfaced in GitHub Code Scanning, and quality regression gating is handled via zenzic diff when a baseline is configured.

Source: github.com/PythonWoods/zenzic-action

Inputs¶

Outputs¶

Exit Code Contract¶

Exit codes 2 and 3 are never suppressed by fail-on-error: "false", --exit-zero, or any other flag. The wrapper enforces this unconditionally — security findings are facts, not findings to be negotiated.

The Zenzic Quality Gate¶

The Zenzic Quality Gate is the recommended PR enforcement setup. It combines structural checks, governance scoring, optional badge freshness, and regression comparison to block merges that decrease documentation quality.

Implementation: see CI/CD Integration → Diff Protocol for the full zenzic-quality-gate.yml workflow.

Gate Logic¶

PR opened
  └─ zenzic check all → exit 0/1/2/3 (findings)
  └─ zenzic score → exit 0/1 (fail_under + suppression_cap)
  └─ zenzic score --check-stamp (default: true) → exit 0/1 (freshness)
  └─ zenzic diff --base <main-baseline>
       ├─ score stable or improved → exit 0 ✅ PR can merge

The suppression debt is included in the score used for comparison. A PR that adds suppressions to hide findings will show a lower score. Security exits (⅔) remain non-suppressible and always fail the run.

Sovereign Audit Mode¶

When audit: "true" is set, the action runs with the --audit flag, which bypasses: - All inline <!-- zenzic:ignore ZXXX --> comments - All [governance.per_file_ignores] entries in .zenzic.toml

Exclusion zones (excluded_dirs, excluded_file_patterns) are not bypassed by audit mode — they define the scan perimeter, not the suppression policy.

Use cases: - Nightly builds — verify suppressed debt remains intentional. - Security Review — surface all Z2xx findings regardless of suppression. - Pre-release audit — measure the true (unfiltered) documentation state before shipping.

Note: fail-on-error: "false" is available for observational audit workflows where findings should not block the run.

Configuration Discovery¶

Sovereign Intent Contract: if you supply config-file: path/to/custom.toml and the file does not exist, the action does not fall back to auto-discovery. You receive a ::warning annotation (or a fatal ::error with strict: "true").

Security Architecture¶

Permissions¶

Minimum permissions required for the most common configurations:

Environment Variables (Advanced)¶

The ZENZIC_EXTRA_ARGS environment variable passes additional flags directly to the Zenzic CLI without modifying action inputs:

- uses: PythonWoods/zenzic-action@<version>
  with:
    version: "<version>"
  env:
    ZENZIC_EXTRA_ARGS: >-
      --exclude-url https://staging.example.com
      --exclude-url https://example.com/blog/unreleased-post

Word-split is intentional (each --exclude-url <url> pair becomes separate argv elements). Glob expansion is disabled in the wrapper before constructing the argument array.

See Also¶

• CI/CD Integration — Full workflow examples including the Zenzic Quality Gate.
• Handle Technical Debt — How to audit and reduce suppression debt.
• Suppression Policy — The three suppression levels and the debt cost formula.
• Scoring Algorithm — How the quality score is computed.
• Finding Codes — Full catalog of all Zxxx codes.