Infrahub Repo Auditor
Overview
Comprehensive audit of an Infrahub repository against
all rules and best practices from the infrahub-skills
plugin. Produces a structured report covering schemas,
objects, checks, generators, transforms, menus,
.infrahub.yml configuration, and deployment readiness.
Project Context
Project structure:
!find . -maxdepth 2 -type f \( -name "*.yml" -o -name "*.yaml" -o -name "*.py" -o -name "*.gql" -o -name "*.j2" \) 2>/dev/null | head -40
Infrahub config:
!cat .infrahub.yml 2>/dev/null || echo "No .infrahub.yml found"
When to Use
- Before deploying a repository to Infrahub
- When onboarding to an existing Infrahub project
- After significant refactoring to catch regressions
- As a periodic quality gate in development workflows
- When troubleshooting schema loading, object sync,
or pipeline failures
How It Works
When invoked, the auditor:
- Discovers the project structure
(
.infrahub.yml, schemas, objects, checks,
generators, transforms, menus)
- Validates each component against the rules
defined in the infrahub-skills plugin
- Cross-references between components (e.g.,
query names match between Python files and
.infrahub.yml)
- Generates a markdown report with findings organized by severity
The phased procedure that ties these steps together
lives in audit-procedure.md —
read that file when running an audit. It defines the
nine phases (project structure → schema → objects →
Python components → cross-references → registration →
best practices → deployment → YAGNI / cost-to-fix)
and the per-finding severity levels used in the final
report.
Audit Categories
| Priority |
Category |
What It Checks |
| CRITICAL |
Project Structure |
.infrahub.yml exists, paths valid |
| CRITICAL |
Schema Validation |
Naming, relationships, deprecated fields |
| CRITICAL |
Object Validation |
YAML structure, value types, refs |
| CRITICAL |
Python Components |
Class inheritance, required methods |
| HIGH |
Cross-References |
Query names match, target groups |
| HIGH |
Relationships |
Bidirectional IDs, cardinality |
| HIGH |
Registration |
All files registered, no orphans |
| MEDIUM |
Best Practices |
human_friendly_id, display_label |
| MEDIUM–LOW |
YAGNI / Cost-to-Fix |
Python doing what schema, GraphQL, Jinja2, or built-in IPAM/VLAN can do; denormalized data; un-extracted duplicate shapes; a whole domain hand-rolled when the marketplace ships it. Severity tracks the cost-to-fix ladder: steps 1–3 MEDIUM, steps 4–7 LOW |
| MEDIUM |
Deployment |
Git status, bootstrap placement |
| LOW |
Patterns & Style |
Code organization, naming |
Running the Audit
Tell Claude: "Audit this Infrahub repo" or "Run the Infrahub repo auditor"
The auditor will scan the current working directory,
walk the phases defined in
audit-procedure.md, and
produce the report described below.
Report Format
The report is written to AUDIT_REPORT.md in the project root with this structure:
# Infrahub Repository Audit Report
## Summary
- Total findings: N
- Critical: N | High: N | Medium: N | Low: N | Info: N
## Project Structure
...
## Schema Audit
...
## Object Data Audit
...
## Checks Audit
...
## Generators Audit
...
## Transforms Audit
...
## Menus Audit
...
## Cross-Reference Integrity
...
## Deployment Readiness
...
## YAGNI / Cost-to-Fix Findings
Findings sorted by `ladder_step` ascending (cheapest
fix first), then by file path. Each entry names the
rule, the ladder step, the file:line, and the
suggested replacement (schema feature, GraphQL query,
Jinja2 template, `Builtin*`/`Ipam*` inheritance, or
inverse relationship declaration).
...
Audit Rules Reference
The auditor checks rules from all skills:
- ../infrahub-managing-schemas/ -- Naming,
relationships, attributes, hierarchy, display,
extensions, uniqueness, migration
- ../infrahub-managing-objects/ -- Format,
values, children, ranges, organization
- ../infrahub-managing-checks/ --
Architecture, Python class, API, registration
- ../infrahub-managing-generators/ --
Architecture, Python class, tracking, API
- ../infrahub-managing-transforms/ --
Types, Python/Jinja2, hybrid, artifacts, API
- ../infrahub-managing-menus/ -- Format,
item properties, hierarchy, icons
- ../infrahub-common/ -- Git integration,
caching,
.infrahub.yml reference, GraphQL
- ../infrahub-common/rules/workflow-information-priority.md
-- Skill content first; how to consult
docs.infrahub.app
on a genuine gap (e.g. deleting nodes)
Rules and Procedure
- audit-procedure.md — the
nine-phase walkthrough that drives every audit
run
- rules/ — detailed audit rule
definitions referenced from the phases
- examples.md — sample audit
reports and finding patterns
1---2name: infrahub-auditing-repo-33description: >-4 Audits an Infrahub repository against best practices and rules, producing a structured compliance report.5 TRIGGER when: reviewing repo for compliance, onboarding to existing project, pre-deployment validation, catching issues.6 DO NOT TRIGGER when: creating schemas, writing checks/generators, querying live data, populating objects.7context: fork8allowed-tools:9 - Read10 - Bash11 - Grep12 - Glob13argument-hint: "[focus-area]"14metadata:15 source: https://skillmd.com/skills/opsmill/infrahub-auditing-repo-316 version: 1.2.817 author: OpsMill18---1920# Infrahub Repo Auditor2122## Overview2324Comprehensive audit of an Infrahub repository against25all rules and best practices from the infrahub-skills26plugin. Produces a structured report covering schemas,27objects, checks, generators, transforms, menus,28`.infrahub.yml` configuration, and deployment readiness.2930## Project Context3132Project structure:33!`find . -maxdepth 2 -type f \( -name "*.yml" -o -name "*.yaml" -o -name "*.py" -o -name "*.gql" -o -name "*.j2" \) 2>/dev/null | head -40`3435Infrahub config:36!`cat .infrahub.yml 2>/dev/null || echo "No .infrahub.yml found"`3738## When to Use3940- Before deploying a repository to Infrahub41- When onboarding to an existing Infrahub project42- After significant refactoring to catch regressions43- As a periodic quality gate in development workflows44- When troubleshooting schema loading, object sync,45 or pipeline failures4647## How It Works4849When invoked, the auditor:50511. **Discovers** the project structure52 (`.infrahub.yml`, schemas, objects, checks,53 generators, transforms, menus)542. **Validates** each component against the rules55 defined in the infrahub-skills plugin563. **Cross-references** between components (e.g.,57 query names match between Python files and58 `.infrahub.yml`)594. **Generates** a markdown report with findings organized by severity6061The phased procedure that ties these steps together62lives in [audit-procedure.md](./audit-procedure.md) —63read that file when running an audit. It defines the64nine phases (project structure → schema → objects →65Python components → cross-references → registration →66best practices → deployment → YAGNI / cost-to-fix)67and the per-finding severity levels used in the final68report.6970## Audit Categories7172| Priority | Category | What It Checks |73| -------- | -------- | -------------- |74| CRITICAL | Project Structure | `.infrahub.yml` exists, paths valid |75| CRITICAL | Schema Validation | Naming, relationships, deprecated fields |76| CRITICAL | Object Validation | YAML structure, value types, refs |77| CRITICAL | Python Components | Class inheritance, required methods |78| HIGH | Cross-References | Query names match, target groups |79| HIGH | Relationships | Bidirectional IDs, cardinality |80| HIGH | Registration | All files registered, no orphans |81| MEDIUM | Best Practices | human_friendly_id, display_label |82| MEDIUM–LOW | YAGNI / Cost-to-Fix | Python doing what schema, GraphQL, Jinja2, or built-in IPAM/VLAN can do; denormalized data; un-extracted duplicate shapes; a whole domain hand-rolled when the marketplace ships it. Severity tracks the cost-to-fix ladder: steps 1–3 MEDIUM, steps 4–7 LOW |83| MEDIUM | Deployment | Git status, bootstrap placement |84| LOW | Patterns & Style | Code organization, naming |8586## Running the Audit8788Tell Claude: **"Audit this Infrahub repo"** or **"Run the Infrahub repo auditor"**8990The auditor will scan the current working directory,91walk the phases defined in92[audit-procedure.md](./audit-procedure.md), and93produce the report described below.9495## Report Format9697The report is written to `AUDIT_REPORT.md` in the project root with this structure:9899```markdown100# Infrahub Repository Audit Report101102## Summary103104- Total findings: N105- Critical: N | High: N | Medium: N | Low: N | Info: N106107## Project Structure108109...110111## Schema Audit112113...114115## Object Data Audit116117...118119## Checks Audit120121...122123## Generators Audit124125...126127## Transforms Audit128129...130131## Menus Audit132133...134135## Cross-Reference Integrity136137...138139## Deployment Readiness140141...142143## YAGNI / Cost-to-Fix Findings144145Findings sorted by `ladder_step` ascending (cheapest146fix first), then by file path. Each entry names the147rule, the ladder step, the file:line, and the148suggested replacement (schema feature, GraphQL query,149Jinja2 template, `Builtin*`/`Ipam*` inheritance, or150inverse relationship declaration).151152...153```154155## Audit Rules Reference156157The auditor checks rules from all skills:158159- **[../infrahub-managing-schemas/](../infrahub-managing-schemas/)** -- Naming,160 relationships, attributes, hierarchy, display,161 extensions, uniqueness, migration162- **[../infrahub-managing-objects/](../infrahub-managing-objects/)** -- Format,163 values, children, ranges, organization164- **[../infrahub-managing-checks/](../infrahub-managing-checks/)** --165 Architecture, Python class, API, registration166- **[../infrahub-managing-generators/](../infrahub-managing-generators/)** --167 Architecture, Python class, tracking, API168- **[../infrahub-managing-transforms/](../infrahub-managing-transforms/)** --169 Types, Python/Jinja2, hybrid, artifacts, API170- **[../infrahub-managing-menus/](../infrahub-managing-menus/)** -- Format,171 item properties, hierarchy, icons172- **[../infrahub-common/](../infrahub-common/)** -- Git integration,173 caching, `.infrahub.yml` reference, GraphQL174- **[../infrahub-common/rules/workflow-information-priority.md](../infrahub-common/rules/workflow-information-priority.md)**175 -- Skill content first; how to consult `docs.infrahub.app`176 on a genuine gap (e.g. deleting nodes)177178## Rules and Procedure179180- [audit-procedure.md](./audit-procedure.md) — the181 nine-phase walkthrough that drives every audit182 run183- [rules/](./rules/) — detailed audit rule184 definitions referenced from the phases185- [examples.md](./examples.md) — sample audit186 reports and finding patterns