Auditing Repository Skill
Relevant source files
The following files were used as context for generating this wiki page:
The Infrahub Auditing Repository Skill provides a framework for auditing an Infrahub repository against best practices and structural rules. It produces a structured compliance report covering schemas, objects, Python components (checks, generators, transforms), and deployment readiness. The skill operates as a read-only process, ensuring the working tree remains untouched except for the generation of the audit report.
Sources: skills/infrahub-auditing-repo/SKILL.md:14-23, AGENTS.md:179
Core Architecture and Execution Flow
The Auditor follows a phased execution model to ensure structural integrity and compliance. It uses a three-level progressive disclosure system to manage context: metadata for triggering, the primary SKILL.md for workflow guidance, and supporting rule files for detailed checks.
Sources: dev/knowledges/architecture.md:38-51, skills/infrahub-auditing-repo/SKILL.md:46-55
Audit Execution Logic
The following diagram illustrates the high-level flow of the auditing process:
The auditor discovers project components and validates them against rules defined in the plugin.
Sources: skills/infrahub-auditing-repo/SKILL.md:46-59, skills/infrahub-auditing-repo/audit-procedure.md:9-14
Mandatory Constraints (Phase 0)
Every audit run must adhere to strict read-only and evidence-based reporting constraints.
Read-Only Conduct
The auditor is granted Bash tool access for inspection only. It must not run destructive git commands or modify any file in the working tree other than AUDIT_REPORT.md. This is critical for auditing trees with uncommitted work.
Sources: skills/infrahub-auditing-repo/SKILL.md:24-33, skills/infrahub-auditing-repo/audit-procedure.md:9-18
Evidence Requirements
Findings must include specific metadata to ensure they are actionable and verified:
- Verification: State how the finding was verified or mark it
verified_against: unknown. - Sites: List every reference site that must change if a symbol is removed or renamed.
- Syntax Resolution: Resolve proposed filters or keys against the specific Infrahub version under audit rather than general documentation.
Sources: skills/infrahub-auditing-repo/audit-procedure.md:22-42
Audit Phases and Categories
The audit procedure is organized into nine sequential phases, each targeting specific repository artifacts.
| Priority | Category | Key Checks |
|---|---|---|
| CRITICAL | Project Structure | .infrahub.yml existence, top-level key validity, and file path resolution. |
| CRITICAL | Schema Validation | Naming conventions (Regex), attribute types, relationships, and hierarchy. |
| CRITICAL | Object Data | YAML structure, value types (Text, Number, Boolean), and load order. |
| CRITICAL | Python Components | Inheritance from InfrahubCheck, InfrahubGenerator, or InfrahubTransform. |
| HIGH | Cross-References | Matching query names between Python classes and .infrahub.yml. |
| HIGH | Registration | Detection of orphan files not registered in the project configuration. |
| MEDIUM | Best Practices | human_friendly_id usage, display_label templates, and watch dependencies. |
| MEDIUM | Deployment | Git status, clean working tree, and proper bootstrap file placement. |
| LOW | YAGNI / Cost-to-Fix | Identifying hand-rolled logic that could be handled by schema or built-in IPAM/VLAN. |
Sources: skills/infrahub-auditing-repo/SKILL.md:69-82, skills/infrahub-auditing-repo/audit-procedure.md:44-190
The YAGNI Cost-to-Fix Ladder
Phase 9 focuses on "You Ain't Gonna Need It" (YAGNI) principles. It evaluates whether Python code or denormalized data can be replaced by more efficient rungs on the "ladder."
The ladder sorts findings by feasibility and cost, prioritizing the removal of custom Python logic in favor of built-in Infrahub features.
Sources: skills/infrahub-auditing-repo/audit-procedure.md:196-267
Report Structure
The auditor outputs findings to AUDIT_REPORT.md at the project root. The report follows a standardized format:
Report Data Model
| Field | Description |
|---|---|
| Summary | Total finding counts categorized by severity (Critical to Info). |
| Severity | Determined by impact (e.g., Critical for sync failures, Low for style). |
| Sites | Paths and line numbers for every location requiring a fix. |
| Verified against | The specific artifact version used to validate proposed syntax. |
| Feasibility | For generic-extraction findings, a verdict (e.g., clear (unverified)). |
Sources: skills/infrahub-auditing-repo/SKILL.md:93-125, skills/infrahub-auditing-repo/audit-procedure.md:273-305
Severity Definitions
- CRITICAL: Causes infrastructure failures (schema, sync, or pipelines).
- HIGH: Broken references or silent failures.
- MEDIUM: Best practice violations; suboptimal but functional.
- LOW: Style or organizational suggestions.
Sources: skills/infrahub-auditing-repo/audit-procedure.md:307-313
Summary
The Auditing Repository Skill acts as a safety and quality gate for Infrahub development. By enforcing structural rules across YAML and Python artifacts and applying the YAGNI cost-to-fix ladder, it ensures repositories are maintainable, efficient, and compliant with Infrahub's architecture. The skill provides developers with a clear roadmap for refactoring through its structured markdown reports and evidence-backed findings.