# Infrahub Managing Checks

> Creates Infrahub check definitions — Python validation logic and GraphQL queries for proposed change pipelines. TRIGGER when: writing validation checks, creating Python checks, building data quality guards for proposed changes. DO NOT TRIGGER when: designing schemas, querying live data, building transforms or generators.

- Skill: `opsmill/infrahub-managing-checks` (Agent Skill, multi-file: 13 files)
- Install (CLI): `npx skillmds@latest add opsmill/infrahub-managing-checks`
- Raw SKILL.md: https://api.skillmd.com/api/skills/opsmill/infrahub-managing-checks/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: opsmill (https://skillmd.com/u/opsmill)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/opsmill/infrahub-managing-checks

---


# Infrahub Check Creator

## Overview

Expert guidance for creating Infrahub checks. Checks are
user-defined validation logic (Python + GraphQL) that run as
part of a proposed change pipeline. If a check logs any
errors, the proposed change cannot be merged.

## Project Context

Infrahub config:
!`cat .infrahub.yml 2>/dev/null || echo "No .infrahub.yml found"`

Existing checks:
!`find . -name "*.py" -path "*/checks/*" 2>/dev/null | head -20`

Existing queries:
!`find . -name "*.gql" -path "*/queries/*" 2>/dev/null | head -20`

## When to Use

- Writing validation logic for proposed changes
- Creating data quality guards (e.g., rack collision
  detection)
- Building global checks that validate all objects of a type
- Building targeted checks that validate specific grouped
  objects
- Debugging check failures or understanding the check
  lifecycle

## Rule Categories

<!-- markdownlint-disable MD013 -->

| Priority | Category | Prefix | Description |
| -------- | -------- | ------ | ----------- |
| CRITICAL | Architecture | `architecture-` | Three components, global vs targeted, execution flow |
| CRITICAL | Python Class | `python-` | InfrahubCheck base class, validate(), log_error/log_info |
| HIGH | API Reference | `api-` | Class attributes, instance properties, methods, lifecycle |
| HIGH | Registration | `registration-` | .infrahub.yml config, query name matching, parameters |
| MEDIUM | Patterns | `patterns-` | Error collection, shared utilities, scoped validation |
| LOW | Testing | `testing-` | infrahubctl check commands, branch testing |

<!-- markdownlint-enable MD013 -->

## Check Basics

Every check has three components:

1. **GraphQL query** (`.gql` file) -- fetches the data to
   validate
2. **Python class** -- inherits from `InfrahubCheck`,
   implements `validate()`
3. **Configuration** -- declared in `.infrahub.yml` under
   `check_definitions`

```python
from infrahub_sdk.checks import InfrahubCheck


class MyCheck(InfrahubCheck):
    query = "my_query"  # Must match query name

    def validate(self, data: dict) -> None:
        # Validation logic here
        if something_is_wrong:
            self.log_error(
                message="Problem description"
            )
```

## Workflow

Follow these steps when creating a check:

1. **Understand the validation goal** — What data
   condition should block a proposed change? Determine
   whether this is a global check (all objects of a
   type) or targeted (specific group). Read
   [rules/architecture-types.md](./rules/architecture-types.md).
2. **Write the GraphQL query** — Create a `.gql` file
   that fetches the data to validate. Read
   [../infrahub-common/graphql-queries.md](../infrahub-common/graphql-queries.md)
   for query patterns.
3. **Implement the Python class** — Inherit from
   `InfrahubCheck`, implement `validate()`. Read
   [rules/python-validate.md](./rules/python-validate.md)
   for the class pattern and
   [rules/api-reference.md](./rules/api-reference.md)
   for available methods.
4. **Register in .infrahub.yml** — Add the check under
   `check_definitions`. The query name must match the
   Python class `query` attribute. See
   [rules/registration-config.md](./rules/registration-config.md).
5. **Test** — Run `infrahubctl check` to validate. See
   [rules/testing-commands.md](./rules/testing-commands.md).

## Supporting References

- **[examples.md](./examples.md)** -- Complete check
  patterns (global, targeted, minimal)
- **[../infrahub-common/graphql-queries.md](../infrahub-common/graphql-queries.md)**
  -- GraphQL query writing reference
- **[../infrahub-common/infrahub-yml-reference.md](../infrahub-common/infrahub-yml-reference.md)**
  -- .infrahub.yml project configuration
- **[../infrahub-common/rules/](../infrahub-common/rules/)** -- Shared rules
  (git integration, caching gotchas) that apply across all
  skills
- **[../infrahub-managing-schemas/SKILL.md](../infrahub-managing-schemas/SKILL.md)**
  -- Schema definitions checks validate against
- **[rules/](./rules/)** -- Individual rules organized by
  category prefix