holger artifact store — for idiots
Class:
guide(beginner) · The zero-knowledge walkthrough. What it IS: holger-artifact-store-design.md; how to use it: holger-artifact-store-guide.md.
The problem, in one picture
A CI forge builds things. Building the same thing twice is a waste, so dwarves remembers: "I already built step X; here is its result." It writes this in a little notebook (the action cache):
step X, with these inputs → result: OK, artifact
sha256:abc…
But sha256:abc… is just a name tag. It is not the built file. If you move to a fresh checkout or a different machine, the notebook says "already built, here's the tag" — but the actual file is nowhere to be found. The name without the thing.
The fix
Put the actual bytes somewhere everyone can reach. The constellation already has that place: holger, the artifact registry. It stores files immutably, addressed by their content, sealed with znippy (a pack format). So:
- A build step finishes and produces a file.
- dwarves pushes that file's bytes into holger. holger hands back the content id (
sha256:abc…). - dwarves writes that id in the notebook, as before.
- Later — even on another machine — the notebook says "already built, id
sha256:abc…". dwarves asks holger forsha256:abc…and gets the real file back.
That's it. The notebook (index) stayed the same; the bytes moved from "a folder on this one machine" to "the shared registry everyone can reach."
Why not just a folder?
There WAS a version that used a local folder. It could never help a second machine — the folder was only on the first one. holger is shared, so it actually delivers the cross-machine win. We reuse holger instead of building our own store (that's a rule: don't re-invent what the constellation already has).
What if holger isn't set up?
Then nothing changes — dwarves works exactly like it did before (name tag only, no pushing). You turn holger on by setting one environment variable, DWARVES_HOLGER_DIR, and building with the holger feature. If holger is set up but momentarily unreachable, a build still succeeds — the push is best-effort and never breaks your build.
The three words to remember
- push — send a built file's bytes to holger (it gets sealed via znippy).
- resolve — ask holger for a file back by its content id.
- no-op — with nothing configured, the whole thing quietly does nothing (safe default).