Skip to content

AGENTS.md

Latest commit

 

History

History
154 lines (114 loc) · 5.3 KB

AGENTS.md

File metadata and controls

154 lines (114 loc) · 5.3 KB

AGENTS.md — opsmill.infrahub Ansible Collection

Project Identity

This is the opsmill.infrahub Ansible collection — modules, plugins, and inventory sources for interacting with Infrahub, an infrastructure data platform.

Tech Stack

Component Version/Tool
Python >=3.10, <3.14
ansible-core >=2.17.7rc1 (Python 3.10+)
infrahub-sdk >=1.5, <2.0
Linter/Formatter Ruff (pinned in pyproject.toml)
Tests pytest, ansible-test sanity (Docker-based)
Docs Docusaurus + Jinja2 generation
Deps uv
Tasks Invoke

Quick Reference Commands

# Lint & format
invoke lint          # Check (ruff + yamllint)
invoke format        # Auto-fix (ruff)

# Tests (all run in Docker)
invoke tests-sanity
invoke tests-unit
invoke tests-integration
invoke tests-all

# Documentation
invoke generate-doc  # Regenerate plugin docs from docstrings
invoke docusaurus    # Build Docusaurus site

# Build
invoke galaxy-build  # Build collection tarball

Architecture Pointers

Detailed architecture docs live in dev/knowledge/:

Key Source Locations

Path Contents
plugins/modules/ Module stubs (DOCUMENTATION + AnsibleModule)
plugins/action/ Action plugins (controller-side logic)
plugins/module_utils/infrahub_utils.py Core: InfrahubclientWrapper, InfrahubModule, processors (~1500 lines)
plugins/module_utils/node.py NodeModule (node CRUD)
plugins/module_utils/branch.py BranchModule (branch CRUD)
plugins/module_utils/exception.py SDK exception → Ansible error mapping
plugins/inventory/inventory.py Dynamic inventory plugin
plugins/lookup/lookup.py GraphQL lookup plugin
plugins/doc_fragments/fragments.py Reusable DOCUMENTATION fragments

Coding Standards

Generated Files — Never Edit Directly

These files are generated by invoke generate-doc:

docs/docs/references/plugins/*.mdx
docs/docs/readme.mdx

Edit the source docstrings in plugins/modules/*.py or the Jinja2 templates in docs/_templates/ instead.

After Making Changes

Run these commands as part of your workflow — not just at the end, but as you go:

After modifying any plugin file (plugins/**/*.py)

invoke lint            # Verify lint passes
invoke tests-sanity    # Verify Ansible compliance (boilerplate, docs, imports)

After modifying module docstrings (DOCUMENTATION / EXAMPLES / RETURN)

invoke generate-doc    # Regenerate plugin reference MDX from docstrings

After modifying module logic or module_utils

invoke tests-unit      # Run unit tests

After any Python change

invoke format          # Auto-fix formatting (ruff)
invoke lint            # Check lint (ruff + yamllint)

Full verification before a PR

invoke format          # Fix formatting
invoke lint            # Check lint
invoke tests-sanity    # Ansible compliance
invoke tests-unit      # Unit tests
invoke generate-doc    # Regenerate docs

Boundaries

Always Do

  • Use the conditional import pattern for infrahub-sdk (HAS_INFRAHUBCLIENT)
  • Include __metaclass__ = type and from __future__ import boilerplate in plugin files
  • Use no_log=True for token/secret parameters
  • Run invoke tests-sanity after modifying plugins
  • Run invoke generate-doc after changing module docstrings
  • Run invoke format then invoke lint after any Python change
  • Follow the existing module patterns (see dev/knowledge/plugin-patterns.md)
  • Use deepcopy(INFRAHUB_ARG_SPEC) when extending the standard argument spec

Ask First

  • Adding new dependencies to pyproject.toml
  • Changing the ruff configuration or ignoring new rules
  • Modifying plugins/module_utils/infrahub_utils.py (core shared code, ~1500 lines)
  • Changing the INFRAHUB_ARG_SPEC (affects all modules using it)
  • Modifying CI workflows in .github/workflows/

Never Do

  • Edit generated files in docs/docs/references/plugins/
  • Remove the __metaclass__ = type or __future__ imports (breaks ansible-test sanity)
  • Use async SDK methods (this collection is synchronous only)
  • Hardcode credentials — always use environment variable fallbacks
  • Skip the conditional HAS_INFRAHUBCLIENT check in any plugin