# Infrahub Auditing Repo

> Audits an Infrahub repository against best practices and rules, producing a structured compliance report. TRIGGER when: reviewing repo for compliance, onboarding to existing project, pre-deployment validation, catching issues. DO NOT TRIGGER when: creating schemas, writing checks/generators, querying live data, populating objects.

- Skill: `opsmill/infrahub-auditing-repo-3` (Agent Skill, multi-file: 33 files)
- Install (CLI): `npx skillmds@latest add opsmill/infrahub-auditing-repo-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/opsmill/infrahub-auditing-repo-3/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: opsmill (https://skillmd.com/u/opsmill)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/opsmill/infrahub-auditing-repo-3

---


# 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:

1. **Discovers** the project structure
   (`.infrahub.yml`, schemas, objects, checks,
   generators, transforms, menus)
2. **Validates** each component against the rules
   defined in the infrahub-skills plugin
3. **Cross-references** between components (e.g.,
   query names match between Python files and
   `.infrahub.yml`)
4. **Generates** a markdown report with findings organized by severity

The phased procedure that ties these steps together
lives in [audit-procedure.md](./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](./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:

```markdown
# 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/](../infrahub-managing-schemas/)** -- Naming,
  relationships, attributes, hierarchy, display,
  extensions, uniqueness, migration
- **[../infrahub-managing-objects/](../infrahub-managing-objects/)** -- Format,
  values, children, ranges, organization
- **[../infrahub-managing-checks/](../infrahub-managing-checks/)** --
  Architecture, Python class, API, registration
- **[../infrahub-managing-generators/](../infrahub-managing-generators/)** --
  Architecture, Python class, tracking, API
- **[../infrahub-managing-transforms/](../infrahub-managing-transforms/)** --
  Types, Python/Jinja2, hybrid, artifacts, API
- **[../infrahub-managing-menus/](../infrahub-managing-menus/)** -- Format,
  item properties, hierarchy, icons
- **[../infrahub-common/](../infrahub-common/)** -- Git integration,
  caching, `.infrahub.yml` reference, GraphQL
- **[../infrahub-common/rules/workflow-information-priority.md](../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](./audit-procedure.md) — the
  nine-phase walkthrough that drives every audit
  run
- [rules/](./rules/) — detailed audit rule
  definitions referenced from the phases
- [examples.md](./examples.md) — sample audit
  reports and finding patterns