hegemony-secret-plugins
Secret-backend SDK and plugin wheels for Hegemony,
a self-hosted orchestration platform for long-running infrastructure changes.
Hegemony flows carry secret references, such as {{ secret('vault://orgs/default/secrets/db/password') }},
never values; a secret backend is what resolves a reference at run time.
| Package | What it is |
|---|
hegemony-secret-sdk | The public SDK a backend is written against: the SecretBackend protocol, the registry and the entry-point group. Depends only on pydantic. |
hegemony-secret-vault | HashiCorp Vault and OpenBao KV v2 backends (vault, the hidden legacy alias vault_kv2, and openbao), plus optional Transit data-key wrapping. |
hegemony-secret-1password | 1Password backends: onepassword_connect (Connect server) and onepassword_service_account. |
The SDK and all plugin wheels are released together under one semver tag,
vX.Y.Z, cut automatically when a releasable change merges to main. Plugin wheels depend on the exact SDK version from the same release.
A plugin depends only on hegemony-secret-sdk (which depends only on pydantic) and
exposes a register(registry) callable under the hegemony.secret_backends
entry-point group. Secret backends are leaf components — the host injects no services or
context into them; a registered factory receives only an already-resolved configuration
dict and returns a backend instance directly. See the
SDK README.
How this relates to Hegemony
The platform, hegemony-sh/hegemony,
owns the secret references, the Settings → Secret Backends screens and the
registry that loads plugins. This repository owns the backends and the SDK they
register through, so a backend can be released, and installed, without a
platform release.
- The platform pins this repository by release tag and commit in its
.github/plugin-pins.json, and builds hegemony-secret-sdk and
hegemony-secret-vault into its API and worker images from a checkout at
that tag.
- Version numbers here are independent of the platform's. These packages have
their own 0.x line, so a platform release does not imply a release here.
- The other plugin kinds live in sibling repositories:
hegemony-step-plugins,
hegemony-inventory-plugins and
hegemony-notification-plugins.
What is auto-installed vs opt-in
- Auto-installed with the platform (already present in Hegemony API and worker
images):
hegemony-secret-sdk and hegemony-secret-vault (the built-in KV v2
backends — vault, the hidden legacy alias vault_kv2, and openbao). One hvac
client serves both products because OpenBao keeps Vault's HTTP API. See its
README.
- Opt-in:
hegemony-secret-1password adds the 1Password backend
(onepassword_connect / onepassword_service_account backend types). Install it in any
deployment that wants a 1Password-backed secrets backend. See its
README.
Both the API (to list/validate the backend type and resolve secrets) and the
worker (to resolve secrets at run time) must have an opt-in plugin installed to use it.
Restart both after installing so each registry reloads its entry points. Do not use
--system; Hegemony runs from /opt/venv.
Install From A Release
Released wheels are published with a SHA256SUMS file. Verify downloaded wheels before
installing them. hegemony-secret-sdk and hegemony-secret-vault are already in the API
and worker images, so only the opt-in hegemony-secret-1password wheel is installed here.
It is installed with dependencies so its 1Password SDKs (onepasswordconnectsdk,
onepassword-sdk) are pulled in.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
