Managing Checks Skill
Relevant source files
The following files were used as context for generating this wiki page:
The Managing Checks Skill provides expert guidance for creating, modifying, and debugging Python-based validation checks within Infrahub. These checks serve as automated gates that validate proposed changes against defined infrastructure policies and data models. Unlike manual analysis or reporting, checks execute automatically during the proposed change pipeline to enforce compliance before data merges into the branch of truth.
Sources: AGENTS.md:144, skills/infrahub-analyzing-data/rules/approach-selection.md:52-64
Purpose and Functionality
Infrahub Checks are designed for ongoing policy enforcement. A check utilizes Python logic and GraphQL queries to inspect data within a proposed change. If the validation logic fails, the check blocks the merge, ensuring that non-compliant infrastructure changes do not enter the system.
Sources: skills/infrahub-analyzing-data/rules/approach-selection.md:52-64, dev/guides/getting-started.md:90
Key Characteristics of Checks
| Feature | Description |
|---|---|
| Trigger | Automatically runs on every proposed change. |
| Enforcement | Blocks the merge of a branch if the check fails. |
| Automation | Fully automated execution within the CI/CD pipeline. |
| Output | Provides a Pass/Fail status in the Infrahub UI. |
| Components | Requires Python code, GraphQL queries, and .infrahub.yml configuration. |
Sources: skills/infrahub-analyzing-data/rules/approach-selection.md:52-60
Architecture and Data Flow
Checks operate at the validation layer of the Infrahub lifecycle. They interact with the schema to understand valid node shapes and use the GraphQL API to fetch the specific instances being changed.
Validation Pipeline Flow
The following diagram illustrates how a check interacts with a proposed change to enforce policy.
This flow shows the automated transition from a change request to a final merge decision based on Python validation logic.
Sources: skills/infrahub-analyzing-data/rules/approach-selection.md:52-64, dev/knowledges/architecture.md:32
Comparison with Other Analysis Methods
Users choose Checks when they require mandatory enforcement. For exploration or one-off audits, other tools like MCP Analysis or Transforms are more appropriate.
| Method | Best For | Enforcement |
|---|---|---|
| Infrahub Check | Stable policy enforcement (e.g., RU collision). | Blocks merge. |
| MCP Analysis | Data exploration and one-off audits. | None (informational). |
| Transform | Recurring reports and stakeholder exports. | None (output only). |
Sources: skills/infrahub-analyzing-data/rules/approach-selection.md:52-64
Implementation Workflow
Implementing a check involves several technical steps to ensure the logic is correctly registered and executed by the Infrahub platform.
- Define the Policy: Identify the invariant that must be true for all infrastructure objects (e.g., "All active interfaces must have a description").
- Author the GraphQL Query: Create a
.gqlfile that fetches the necessary nodes and attributes required for the validation. - Write the Python Logic: Create a Python class that inherits from the appropriate base class and implements the validation logic.
- Register the Check: Add the check definition to the
.infrahub.ymlconfiguration file, mapping the Python class to the relevant targets. - Test on a Branch: Create a branch, apply changes, and verify the check correctly identifies non-compliant data.
Sources: dev/guides/getting-started.md:90, skills/infrahub-managing-schemas/SKILL.md:155-165
Integration with Schema
Checks are highly dependent on the underlying schema. A check often validates specific attributes or relationships defined in the schema nodes. If the schema is modified (e.g., an attribute is marked as optional), existing checks may require updates to avoid false failures.
Sources: skills/infrahub-managing-schemas/SKILL.md:40-50, dev/knowledges/architecture.md:32
Dependency Relationship
This diagram shows that checks validate the schema definitions and gate the proposed changes containing data objects.
Sources: skills/infrahub-managing-schemas/SKILL.md:40-50, skills/infrahub-analyzing-data/rules/approach-selection.md:52-64
Summary
The Managing Checks Skill is a critical component for infrastructure-as-code reliability. By providing a structured way to author Python validation logic, it ensures that every proposed change is automatically audited for compliance, preventing configuration errors from reaching the production environment.