Inventory Plugin Development

Inventory providers are optional by design. Hegemony core images should run with the inventory SDK and the built-in local provider only. External providers are installed only when a deployment or developer workflow opts into them.

The long-term source of truth for the inventory SDK and external provider packages is the separate hegemony-inventory-plugins repository:

• hegemony-inventory-sdk
• hegemony-inventory-netbox
• hegemony-inventory-git

Local Checkout Layout

Clone the repositories as siblings for a full development checkout and whenever you work on inventory providers or run checks that install provider packages:

mkdir -p ~/work/hegemony
cd ~/work/hegemony
git clone https://github.com/hegemony-sh/hegemony.git Hegemony
git clone https://github.com/hegemony-sh/hegemony-inventory-plugins.git

Expected layout:

hegemony/
  Hegemony/
  hegemony-inventory-plugins/

Hegemony resolves inventory packages from the sibling checkout during local development:

../hegemony-inventory-plugins/packages/inventory_sdk
../hegemony-inventory-plugins/plugins/inventory_netbox
../hegemony-inventory-plugins/plugins/inventory_git

This keeps Hegemony focused on app integration while provider package development, tests, versioning, release wheels, and plugin pre-commit hooks live in the plugin repository.

Pinned Revisions

Which revision of the plugin repository Hegemony is built and tested against is recorded in .github/plugin-pins.json, one entry per sibling repository:

{
  "hegemony-inventory-plugins": {
    "ref": "v0.4.0",
    "commit": "9940b0fa76d4fc946e8f6f744227290ed7b03bde"
  }
}

ref is what was pinned (a tag, a branch or a SHA); commit is the 40-hex commit it resolved to and what CI checks out. Keep the local sibling checkout at that commit: the step-handler fixture check and the release-train checks (task release:manifest:check) stand down or fail on a checkout that is elsewhere, because the versions it reports would not be the pinned ones.

A Hegemony release requires every ref to be the plugin repository's release tag v<SDK version>, verified against the repository at release time; the pin format, the gate and the Renovate pull requests that propose new tags are described in the release process.

Development Rules

• Do not add external provider packages to the default Hegemony install path.
• Do not add external provider packages to Hegemony's pyproject.toml or uv.lock; keep them in the plugin repository and install released wheels in deployments that need them.
• Make provider implementation changes in ../hegemony-inventory-plugins.
• Keep Hegemony integration and parity tests in this repository.
• Keep provider unit tests and release smoke tests in hegemony-inventory-plugins.

Docker Install Workflow

Hegemony source-built images receive the sibling plugin repository as a Docker named build context and copy only hegemony-inventory-plugins/packages/inventory_sdk from it. This keeps the SDK in the base API, worker, and scheduler images without copying optional provider implementations into those images.

The API process discovers and runs inventory provider plugins. Install selected provider wheels into each API container's /opt/venv as root, then restart the API so entry points are loaded. Do not use --system; Hegemony runs from /opt/venv. The SDK wheel is already present in Hegemony images, so provider installs can use --no-deps.

Production deployments that need external inventory providers should install released provider wheels from hegemony-inventory-plugins. Development deployments can install the same release wheels or locally built wheels from a sibling hegemony-inventory-plugins/dist/ directory.

Hegemony images that do not need external inventory providers should not install provider wheels at all.

See the hegemony-inventory-plugins install guide for the current Docker commands, release wheel URLs, checksum verification, and local-wheel development flow.