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.

VERSION=X.Y.Z   # a release tag without the leading v; see Compatibility
API_CONTAINER=<your API container name>
WORKER_CONTAINER=<your worker container name>

for CONTAINER in "${API_CONTAINER}" "${WORKER_CONTAINER}"; do
  docker exec -u root -it "${CONTAINER}" bash -lc "
set -euo pipefail
version=${VERSION}
base=https://github.com/hegemony-sh/hegemony-secret-plugins/releases/download/v\${version}
tmp=\$(mktemp -d)
cd \"\${tmp}\"
curl -fsSLO \"\${base}/SHA256SUMS\"
for wheel in \
  hegemony_secret_1password-\${version}-py3-none-any.whl
do
  curl -fsSLO \"\${base}/\${wheel}\"
  grep \"  \${wheel}$\" SHA256SUMS | sha256sum -c -
done
uv pip install --python /opt/venv/bin/python ./*.whl
rm -rf \"\${tmp}\"
"
  docker restart "${CONTAINER}"
done

For a stronger supply-chain guarantee than checksums alone, also verify the build provenance attestation generated by the release workflow (requires the gh CLI):

gh attestation verify hegemony_secret_1password-${VERSION}-py3-none-any.whl \
  --repo hegemony-sh/hegemony-secret-plugins \
  --signer-workflow hegemony-sh/hegemony-github-workflows/.github/workflows/plugin-release.yml

The release workflow of this repository calls the shared plugin-release.yml workflow in hegemony-sh/hegemony-github-workflows, and that shared workflow signs the attestation. So gh needs both flags: --repo checks that the wheel was built from this repository, and --signer-workflow checks which workflow signed it.

Attestations are bound to the repository path at publish time: wheels from releases published before the move to the hegemony-sh organization are bound to the path this repository carried then, so verifying one means passing that path to --repo instead, and the workflow that signed that release to --signer-workflow. The release workflow creates attestations only while the repository is public (the feature needs a public repository or an Enterprise plan), and creates them when it publishes. A release published while the repository was private therefore has none, and making the repository public afterwards does not add one: gh attestation verify has nothing to check on it. SHA256SUMS still ships beside every release's assets, but it checks integrity against a manifest published in the same release rather than provenance, so where there is no attestation treat it as a consistency check and not as a stand-in for one.

Or build local wheels from this repository and copy them into the running dev containers:

cd ../hegemony-secret-plugins
task build

for CONTAINER in hegemony-dev-api-1 hegemony-dev-worker-1; do
  docker exec -u root "${CONTAINER}" mkdir -p /tmp/secret-wheels
  docker cp dist/. "${CONTAINER}:/tmp/secret-wheels/"
  docker exec -u root -it "${CONTAINER}" bash -lc '
  uv pip install --python /opt/venv/bin/python \
    /tmp/secret-wheels/hegemony_secret_1password-*.whl
  '
  docker restart "${CONTAINER}"
done

These Docker-command installs are runtime changes. Re-run them after recreating a container or replacing the image.

Compatibility

Each Hegemony release pins one release of this repository in its .github/plugin-pins.json and is built and tested against exactly that release. Install the release your platform pins; the newest one is on the Releases page.

Hegemony	hegemony-secret-plugins
1.0.0	0.3.4

Hegemony versions before 1.0.0 were not released publicly.

Build a secret backend

A backend does not have to live in this repository: any wheel that depends on hegemony-secret-sdk and registers a register(registry) callable under the hegemony.secret_backends entry-point group is discovered by the platform (install it into the API and the worker, as above, and restart both). The SDK README has the entry-point declaration, a complete minimal backend (read, write, test), and the config-schema keys the host form understands. The two plugins here are worked examples: Vault and OpenBao for a backend with several auth methods, and 1Password for one that wraps an SDK.

Documentation

• Hegemony documentation: the documentation site.
• Secrets: secret references, backends and how they are configured in the platform.
• Internal OpenBao lifecycle: the bundled OpenBao backend.
• Installed plugins: where the platform lists what is installed.
• Per-package configuration reference: the package READMEs linked above.

Development

uv sync --all-packages
uv run pre-commit install --install-hooks

If you have Task installed, the common workflow is:

task setup
task lint
task test
task build
task smoke
task md:lint

The hook set mirrors Hegemony where applicable for this package-only repo: general file hygiene, pyproject validation, typos, Zizmor, workflow schema checks, REUSE, Ruff, typecheck, tests, Gitleaks, and commitlint. UI, Docker, OpenAPI, and task-runner hooks stay in Hegemony because those surfaces are not present here. Gitleaks reads .gitleaks.toml, which extends the default ruleset and lists the one file it allowlists, with the reason.

Run the local equivalent of CI:

task ci

Run every configured pre-commit hook manually:

task precommit

Releases are cut automatically when a releasable change merges to main; see Contributing. Do not bump versions or push tags by hand. task version:set -- X.Y.Z and task version:verify -- vX.Y.Z stay available for trying the lockstep bump locally.

Contributing, security and licence

• Read Contributing first. Every commit needs a DCO sign-off (git commit -s) and follows Conventional Commits, because merges to main drive releases: feat, fix, perf and revert commits publish a new version.
• Report vulnerabilities privately, as SECURITY.md describes, and do not open public issues for them.
• Participation is governed by the Code of Conduct.
• Licensed under AGPL-3.0-or-later. See Licensing.