From infrahub
Guides creation of Infrahub check definitions: Python validation classes, GraphQL queries, and YAML-driven tests for proposed change pipelines.
How this skill is triggered — by the user, by Claude, or both
Slash command
/infrahub:infrahub-managing-checks [check-name] [description...][check-name] [description...]This skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Expert guidance for creating Infrahub checks. Checks are
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.
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
| 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 |
| HIGH | Testing | testing- | Resources Testing Framework (YAML-driven tests), infrahubctl check commands |
A check is only useful if it can fetch and validate the right data. Most check failures at deploy time are actually schema-side gaps:
| If the check... | The schema (or .infrahub.yml) must... | See |
|---|---|---|
| Reads an attribute via GraphQL | Expose it on the schema node with the same name (name__value-shaped paths) | ../infrahub-managing-schemas/rules/attribute-defaults-and-types.md |
| Walks a relationship to validate related objects | Have both sides of the relationship defined with matching identifiers; otherwise the traversal returns nothing | ../infrahub-managing-schemas/rules/relationship-identifiers.md |
| Is targeted (per-object) | Register a CoreStandardGroup as targets: in .infrahub.yml and map parameters: to bind GraphQL variables | rules/registration-config.md |
| Needs the GraphQL response keyed to typed nodes | Select id and __typename in the query — the SDK relies on both | ../infrahub-common/graphql-queries.md |
| Should never block a merge but only annotate | Use self.log_info() instead of log_error(); log_warning() does not exist | rules/python-validate.md |
Every check has three components:
.gql file) -- fetches the data to
validate, and is registered under the top-level
queries: section of .infrahub.ymlInfrahubCheck,
sets query = "<query_name>", implements
validate().infrahub.yml under
check_definitions (which does not take a
query: field — see below)from infrahub_sdk.checks import InfrahubCheck
class MyCheck(InfrahubCheck):
query = "my_query" # Must match queries[].name in .infrahub.yml
def validate(self, data: dict) -> None:
# Validation logic here
if something_is_wrong:
self.log_error(
message="Problem description"
)
Where the query is bound: the Python class (
query = "..."), notcheck_definitions. The repository config model usesextra="forbid", so puttingquery:undercheck_definitions:makes the whole repo config fail validation. This is the #1 confusion vs.generator_definitions:, which does take a top-levelquery:. See rules/registration-config.md.
Follow these steps when creating a check:
.gql file
that fetches the data to validate. Read
../infrahub-common/graphql-queries.md
for query patterns.InfrahubCheck, implement validate(). Read
rules/python-validate.md
for the class pattern and
rules/api-reference.md
for available methods.check_definitions. The query name must match the
Python class query attribute. See
rules/registration-config.md.infrahubctl check to validate
against a feature branch. See
rules/testing-commands.md..infrahub.yml registration (with the no-query:
shape that differs from generator_definitions)npx claudepluginhub opsmill/claude-marketplace --plugin infrahubAudits an Infrahub repository against best practices and rules, producing a structured compliance report covering schemas, objects, checks, generators, transforms, menus, and deployment readiness.
Integrates GraphQL Inspector into GitHub Actions, GitLab CI, and pipelines for automated schema diffing, operation validation, breaking change detection, and PR comments.
Generates a pre-deployment verification checklist customized to the project's tech stack, including rollback triggers and graph-based module boundary validation.