Skip to content

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:

bash
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:

text
hegemony/
  Hegemony/
  hegemony-inventory-plugins/

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

text
../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, for example:

json
{
  "hegemony-inventory-plugins": {
    "ref": "v0.5.0",
    "commit": "0a6eaefa28ebee4d21cea5f54f1c49ceaf1aaa6b"
  }
}

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.

Declarative Git objects ​

Git providers can discover repository-defined generic types through the same SDK contracts as other providers. They retain their legacy device/site methods and use no projection bindings, so those records are not duplicated as generic objects.

The host refreshes Git discovery before each sync. The provider validates a locked checkout into one in-memory snapshot and reuses it across discovery and all sync reads. Core constructs a fresh provider instance for each sync and runs discovery before its reads; provider instances must not be pooled across syncs. The host-only test_each_sync_builds_a_fresh_provider_and_discovers_before_reads regression enforces this lifecycle even when the optional Git plugin is not installed. PlatformServices.git.locked_workdir(...) is an async context manager with the same arguments as get_workdir; it resolves HEAD under the cache-entry lock and releases the lock after the provider has parsed the files. Existing fetchers need not implement this optional extension for legacy inventories. New generic Git inventories fail with a compatibility error on hosts without it.

Repository schemas are isolated by organization/provider identity. Same-ID schemas involving Git must be identical within the visible tenant/shared schema namespace. Conflicts fail discovery before replacing the previous result. Type advisory locks serialize concurrent declarations on PostgreSQL. Other sources retain their existing schema-extension behavior when no Git declaration is involved.

The equality rule includes the complete type specification: labels (display_name, plural, group), UI hints, field and query schemas, identity keys, and relationships. A column or label change can therefore conflict just like a data-contract change. Give each type ID one schema owner; if several providers publish it, distribute that owner's exact definition to each. Disabling a provider does not remove its stored declaration and is not a migration mechanism.

For a type published by several providers, use a new ID such as example.service.v2 to roll out changes without requiring simultaneous syncs:

  1. Keep the old definition and records while adding the new definition and migrated records in each repository. Update relationship targets for the new records too.
  2. Sync providers individually. The old ID keeps its original specification, and every publisher of the new ID uses the same new specification.
  3. Select the new type where provider type selection is explicit, and migrate forms, flows, and other consumers to the new ID. Object UUIDs belong to their type, so consumers storing UUIDs must resolve the new objects rather than reuse old IDs.
  4. After all consumers have moved, remove the old records and definition from each repository and sync each provider to retire its declaration and stale old objects.

Changing all repositories in place before syncing is insufficient: the first sync still conflicts with the other providers' stored declarations. Registered static specifications also participate in the check; use a distinct ID instead of trying to override one with a different Git definition.

Dropdown search uses tenant-visible discovered metadata as well as registered metadata. It retains the existing option values, deduplication, filtering, and submission membership checks.

The Git plugin's GENERIC_OBJECTS.md documents the repository format and provides a native Scope → Service interface graph.

To run the optional real-plugin integration tests, install the matching Git plugin wheel in the test environment, then run pytest tests/api/test_git_generic_inventory_integration.py. These tests are skipped when the optional Git plugin is absent; host-only discovery, dropdown, object-store, and Git-lock regressions run without it. The plugin repository's CI covers the YAML/provider layer independently.

Released as open source under the AGPL-3.0-or-later license. Development is sponsored by Rexonix s.r.o. Contact — [email protected].