Deterministic Document Integrity Engine and SAST for Markdown/MDX graphs.
Run Zenzic SAST and graph integrity analysis in CI — surfacing results directly in GitHub Code Scanning without reading logs.
Exit code contract (ADR-075). The wrapper propagates Zenzic's exit codes without remapping. Exit 1 (quality) obeys fail-on-error. Exit 2 (credential) and exit 3 (path traversal) terminate the job regardless of fail-on-error: false or --exit-zero — security findings are never suppressed at the enforcement boundary.
| Feature | Category | Description |
|---|---|---|
| Security Scanning (SAST) | Security | Detects hardcoded tokens (Z201) and path traversal (Z202/Z203); exits 2/3 survive fail-on-error: false |
| Graph Topology Analysis | Topology | Virtual Site Map (VSM) verifies cross-file links, orphan pages, and dead navigation graph nodes |
| Deterministic CI/CD Enforcement | CI/CD | Zero-DBT quality gate ensuring bit-for-bit reproducible enforcement across build environments |
| Zero-setup install | Execution | uvx zenzic — no Python toolchain required on the runner |
| SARIF output | Integration | Findings feed directly into GitHub Code Scanning |
| Sovereign Audit mode | Security | audit: "true" bypasses suppressions to reveal unfiltered documentation graph state |
| PR annotations | Feedback | Inline findings on diffs, colour-coded by severity |
| Version pinning | Governance | Pin to exact release (e.g. 0.25.0) for deterministic, reproducible CI gates |
The minimal configuration — zero Python setup, SARIF to Code Scanning in one step:
- uses: actions/checkout@v4
- name: Run Zenzic Documentation Quality Gate
uses: PythonWoods/zenzic-action@v2
with:
version: "0.25.3"
format: sarif
upload-sarif: "true"
permissions:
contents: read
security-events: writePlace a .zenzic.toml at the root of your repository and the action picks it up automatically — no config-file input required. Run zenzic init once to scaffold a config if your docs live outside the default docs/ folder.
For advanced configuration (Configuration Discovery, Sovereign Override, Quality Gate scoring, nightly audit), see the Zenzic Action docs.
Zenzic Action surfaces findings directly where you work — no digging through CI logs.
This blueprint provides static application security testing (SAST), link validation, and graph topology verification. It executes during pushes and PRs, ensuring no broken links, credential leaks, or invalid configurations enter the repository.
name: Zenzic Baseline Audit
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
baseline-check:
runs-on: ubuntu-latest
steps:
- name: Checkout Repository
uses: actions/checkout@v4
- name: Run Zenzic Baseline
uses: PythonWoods/zenzic-action@v2
with:
version: "0.25.0"
format: text
fail-on-error: "true"This blueprint runs a security-hardened gate. It executes the secret scanner (guard-scan) to catch exposed credentials and path traversals, then uploads the SARIF report directly to the GitHub Code Scanning Security tab.
name: Zenzic Hardened Quality Gate
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
security-gate:
runs-on: ubuntu-latest
permissions:
contents: read
security-events: write
steps:
- name: Checkout Repository
uses: actions/checkout@v4
- name: Run Hardened Zenzic Audit
uses: PythonWoods/zenzic-action@v2
with:
version: "0.25.0"
format: sarif
upload-sarif: "true"
guard-scan: "true"This blueprint implements pull-request governance. It downloads the DQS baseline from the default branch, runs the quality gate comparison, maps issues to inline annotations, and publishes a summary of the Document Quality Score (DQS) to the workflow run.
name: Zenzic PR Governance & DQS Tracking
on:
pull_request:
branches: [ main ]
jobs:
pr-governance:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- name: Checkout Repository
uses: actions/checkout@v4
- name: Run PR Governance Check
uses: PythonWoods/zenzic-action@v2
with:
version: "0.25.0"
format: text
fail-on-error: "true"Runs an unsuppressed audit on schedule, reporting hidden technical debt directly to Code Scanning.
name: Zenzic Sovereign Audit
on:
schedule:
- cron: "0 2 * * *" # Daily at 02:00 UTC
jobs:
sovereign-audit:
runs-on: ubuntu-latest
permissions:
contents: read
security-events: write
steps:
- name: Checkout Repository
uses: actions/checkout@v4
- name: Run Sovereign Audit
uses: PythonWoods/zenzic-action@v2
with:
version: "0.25.0"
audit: "true"
format: sarif
upload-sarif: "true"| Input | Default | Description |
|---|---|---|
version |
0.25.3 |
Zenzic Core version to execute. Pin to a specific release (e.g. 0.25.0) for reproducible CI. |
| format | "text" | Output format: text, json, or sarif |
| upload-sarif | "false" | Automatically upload SARIF output to GitHub Code Scanning |
| guard-scan | "false" | Triggers fatal pre-gate security scan (zenzic guard scan) |
| audit | "false" | Sovereign Audit mode: bypasses all active suppressions |
| fail-on-error | "true" | Controls job failure for quality findings (Exit 1) |
| config-file | "" | Optional path to custom .zenzic.toml configuration |
| Concern | Zenzic Core | Zenzic Action |
|---|---|---|
| Link & Topology validation | ✅ | Executes Core |
| Credential scanner (Z2xx) | ✅ | Executes Core |
| Exit-code contract (0/1/2/3) | ✅ | Enforced |
GitHub Annotations (::error::) |
— | ✅ |
| Code Scanning SARIF upload | — | ✅ |
| PR inline diff annotations | — | ✅ |
Licensed under Apache-2.0. For complete finding taxonomy and developer guides, visit zenzic.dev.