Files
skills/public/hip-0036.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

388 lines
39 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>hip-0036</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/hip-0036.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/hip-0036">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/hip-0036.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>hip-0036</h1><p class="lede">HIP-36: CI/CD Build System Standard. Status Final. Hanzo architectural specification.</p><h1>HIP-0036: CI/CD Build System Standard</h1>
<h2>Abstract</h2>
<p>CI is <strong>Hanzo Git Actions</strong> at <code>git.hanzo.ai</code>, executed by <strong><code>act_runner</code></strong> — one runner, capability-routed, serving <code>hanzoai</code>, <code>luxfi</code>, <code>zooai</code>, <code>parsdao</code> and <code>zenlm</code>. Workflows live in <strong><code>.hanzo/workflows/</code></strong>. GitHub Actions is not part of this path and has no runners here; a workflow left under <code>.github/workflows/</code> queues forever while looking like CI.</p>
<p>A repository needs two files: <code>hanzo.yml</code> at the root, which declares what to test and what images to build (HIP-0142), and a short <code>.hanzo/workflows/cicd.yml</code> that imports the one reusable workflow. Build and test logic lives in <code>hanzoai/ci</code>, once, and no repository carries its own.</p>
<p>A build ends at a <strong>published image</strong>. It does not deploy. What runs in a cluster is declared in <code>hanzoai/universe</code> and applied by <code>cd.hanzo.ai</code>; <code>ci.hanzo.ai</code> reports whether the two agree.</p>
<p><strong>Reusable workflow</strong>: <code>hanzoai/ci/.hanzo/workflows/build.yml@v1</code> <strong>Runner labels</strong>: <code>hanzoai/.github</code> → <code>RUNNERS.md</code>, the single source of truth <strong>Registry</strong>: <code>oci.hanzo.ai/&lt;org&gt;/&lt;app&gt;</code> (HIP-0033)</p>
<h2>Motivation</h2>
<h3>The Problem at Scale</h3>
<p>Managing CI/CD for 260+ repositories creates compounding problems:</p>
<ol><li><strong>Configuration drift</strong>: Without a standard, each repo invents its own workflow. Team A uses <code>npm test</code>, Team B uses <code>pnpm test</code>, Team C uses <code>yarn test</code>. Multiply this by every build step and you get 260 slightly different pipelines that nobody fully understands.</li></ol>
<ol><li><strong>Secret sprawl</strong>: if each repository stores its own registry token, rotating that token means editing every repository that holds it. Miss one and its next build breaks silently. With twenty-odd secrets per repository this is a full-time job that produces nothing.</li></ol>
<ol><li><strong>Registry fragmentation</strong>: repositories pushed to one registry, another, both or neither, so a consumer could not predict where an image lived or what tags it carried.</li></ol>
<ol><li><strong>Deployment inconsistency</strong>: One repo deploys via SSH + docker-compose, another via kubectl, another via Helm. Incident response requires knowing which method each service uses.</li></ol>
<ol><li><strong>Wasted compute</strong>: Without shared caching strategies, every build downloads the same Go modules, Node packages, and Docker layers from scratch.</li></ol>
<h3>The Solution</h3>
<p>One reusable workflow — <code>hanzoai/ci</code> — that every repository imports, driven entirely by that repository&#x27;s <code>hanzo.yml</code>. No per-repo build logic, one place to fix a build step, and one place secrets are fetched.</p>
<h2>Design Philosophy</h2>
<h3>Why our own forge runs our own CI</h3>
<p>Secret rotation is the concrete reason. With a per-repository secret store, one rotated credential is an edit in every repository that holds it; miss one and its next build breaks silently. Secrets are fetched from KMS at build time instead, so a rotation is one write and every subsequent build picks it up. The only long-lived values a repository holds are the machine identity it authenticates with.</p>
<p>The second reason is that the fleet&#x27;s builds need hardware GitHub-hosted runners do not have — Metal GPU, macOS, Windows, Linux arm64 with CUDA — and a single capability-routed runner serves all of it beside the fungible amd64 bulk.</p>
<h3>Why Multi-Arch Builds (linux/amd64 + linux/arm64)</h3>
<p>Hanzo infrastructure runs on two architectures:</p>
<p>| Environment | Architecture | Examples | |-------------|-------------|----------| | Production K8s | AMD64 | DigitalOcean droplets, Kubernetes cluster | | Developer machines | ARM64 | Apple Silicon MacBooks (M1/M2/M3/M4) | | CI runners | AMD64 and ARM64 | the in-cluster <code>act_runner</code> pool, plus native arm64 hosts |</p>
<p>Without multi-arch images, a developer on Apple Silicon pulling a service image gets an amd64 image under emulation -- several times slower, and with behaviour differences that show up as flaky tests rather than as an obvious wrong-architecture error.</p>
<p>A multi-arch manifest list solves it: one tag carries both architectures and the client selects the native one.</p>
<p>The build uses <code>docker/setup-qemu-action</code> for cross-compilation and <code>docker/setup-buildx-action</code> for multi-platform builds:</p>
<pre><code class="lang-yaml">- uses: docker/setup-qemu-action@v3
- uses: docker/setup-buildx-action@v3
- uses: docker/build-push-action@v5
with:
platforms: linux/amd64,linux/arm64</code></pre>
<p><strong>Trade-off acknowledged</strong>: Multi-arch builds take 2-3x longer than single-arch builds because each platform compiles separately. We accept this because builds are not in the critical path for developer iteration (developers build locally) and the production correctness guarantee is worth the extra CI minutes.</p>
<h3>Why one registry</h3>
<p>An image lives at exactly one address. A second registry was previously mirrored on a best-effort push, and the mirror is the problem rather than the fallback — a &quot;convenience mirror&quot; a build is permitted to fail is a set of tags that disagree with the source of truth, at a cadence nobody watches, and a consumer cannot tell which one they pulled. HIP-0033 is the one statement of where an image is published, and the org prefix never mixes: <code>hanzoai</code> for Hanzo, <code>luxfi</code> for Lux, <code>zooai</code> for Zoo.</p>
<h3>Why a build ends at an image</h3>
<p>The pipeline publishes an image and stops. It holds no cluster credential, runs no <code>kubectl</code>, and cannot roll anything out. What runs is declared in <code>hanzoai/universe</code> as a pinned tag, and <code>cd.hanzo.ai</code> reconciles the cluster toward that declaration.</p>
<p>That split is what makes drift nameable rather than a feeling. Four values form one causal line — <code>head → built → declared → running</code> — and a service is current exactly when all four agree. Each way they disagree names the arrow that did not happen: <code>unbuilt</code> (head produced no image), <code>unshipped</code> (an image was proved that the pin never named), <code>unsynced</code> (the pin and the cluster disagree, compared by digest), <code>untested</code> (a passing build whose tests did not execute). A pipeline that deploys directly can report success while running something nobody declared, and has no way to say which of the four steps failed.</p>
<h2>Specification</h2>
<p>The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are to be interpreted as in RFC 2119.</p>
<h3>1. Two files per repository</h3>
<p>A repository declares itself with <code>hanzo.yml</code> at the root (HIP-0142 specifies the manifest and its <code>kind</code> field) and imports the one reusable workflow:</p>
<pre><code class="lang-yaml"># hanzo.yml — what to test, what to build
images:
- { name: api, context: ./api, repo: oci.hanzo.ai/hanzoai/&lt;repo&gt;, tag-suffix: api }
test:
- { name: api, run: &quot;pytest -q&quot; }
kms: { path: /deploy, environment: prod }</code></pre>
<pre><code class="lang-yaml"># .hanzo/workflows/cicd.yml — the whole workflow
name: CI/CD
on:
push: { branches: [main], tags: [&quot;v*&quot;] }
pull_request:
workflow_dispatch:
jobs:
cicd:
uses: hanzoai/ci/.github/workflows/build.yml@v2
secrets: inherit</code></pre>
<p><strong>The caller&#x27;s directory and the callee&#x27;s path are governed by different rules, and conflating them breaks the build.</strong> The caller sits in this repository&#x27;s one workflow directory, which the forge <em>scans</em> (§2). The <code>uses:</code> line is a reference into another repository at a pinned tag — resolved by path at that tag, never scanned — so it names whatever path the reusable workflow occupies there. Today that is <code>hanzoai/ci/.github/workflows/build.yml@v2</code>. Copy the line from <code>hanzoai/ci</code>&#x27;s own caller rather than from memory; it is the one place both halves are known to agree.</p>
<p>A <code>v*</code> tag is what produces a published immutable image tag. Without that trigger, a release tag builds nothing and there is no version for the declared state to pin.</p>
<p>A repository MUST NOT carry its own build, test, release or publish logic. Where one exists, the fix is to move the specifics into <code>hanzo.yml</code> and delete the rest — a second implementation of the pipeline is the defect this HIP exists to prevent.</p>
<h3>2. <code>.hanzo/workflows/</code>, and nothing left under <code>.github/workflows/</code></h3>
<p>Hanzo Git collects workflows from the <strong>first</strong> entry of <code>WORKFLOW_DIRS</code> that exists — not the union. The moment one file lands in <code>.hanzo/workflows/</code>, every remaining file under <code>.github/workflows/</code> stops running, and it stops <strong>silently</strong>: the checks that would go red are the ones no longer running, so the repository reports green over a pipeline that is not there. A half-finished migration runs neither lane.</p>
<p>Find the dead files in any repository:</p>
<pre><code class="lang-bash">comm -23 &lt;(ls .github/workflows) &lt;(ls .hanzo/workflows) # anything listed is dead</code></pre>
<p>Moving a file is not reviving it. Two things break on the way across, and both MUST be handled deliberately:</p>
<ul><li><strong><code>runs-on: ubuntu-latest</code> matches no runner in this fleet, deliberately.</strong></li></ul>
<p> Hanzo Git hosts roughly 1,400 mirrored repositories whose upstream workflows all ask for it; advertising that label would hand the fleet to their CI. An unmatched label does not fail — it <strong>queues until the timeout</strong>, which reads as a hung build rather than a misconfiguration. Use a label from <code>RUNNERS.md</code>.</p>
<ul><li><strong>Anything reading a GitHub-only surface</strong> — <code>github.event.pull_request</code>, PR</li></ul>
<p> comments, GitHub Releases, the compare API, GitHub App tokens, CodeQL&#x27;s <code>security-events</code> upload, OIDC trusted publishing — has no equivalent here. Port it deliberately, or drop it and say so out loud.</p>
<p>In a fork, most files under <code>.github/workflows/</code> are the <strong>upstream project&#x27;s</strong> CI: label bots, reviewer assignment, stale bots, release trains for packages we do not publish. Moving those runs someone else&#x27;s automation on our fleet. Sort every file into revive / rewrite / drop, then <strong>delete the directory</strong> — a dead file cannot accumulate in a directory that does not exist.</p>
<p>The one repository that keeps files in both is <code>hanzoai/ci</code> itself, and for a reason that is not an exception to this rule: its <code>.hanzo/workflows/cicd.yml</code> is its own caller, gated like any other repository, while the reusable workflow it publishes for everyone else is an artifact addressed by path at a tag. It is consumed by reference, never scanned.</p>
<h3>3. Runner labels</h3>
<p><code>hanzoai/.github</code> → <code>RUNNERS.md</code> is the single source of truth for the label taxonomy, and both the runner configuration and every workflow&#x27;s <code>runs-on</code> consume it. The canonical label for new workflows is the compound <code>&lt;org&gt;-&lt;os&gt;-&lt;arch&gt;</code> — <code>hanzo-linux-amd64</code>, <code>lux-macos-arm64</code>. Every runner also advertises the compatibility aliases that route to the same capability; author against the canonical form and treat the aliases as history.</p>
<p>A <code>runs-on</code> value names a <strong>capability</strong>, not a machine. The in-cluster runner serves the fungible amd64-Linux bulk with no physical-host dependency; native host runners serve only what the cluster cannot — Metal GPU, macOS, Windows, and Linux arm64 with CUDA.</p>
<h3>4. Secrets</h3>
<p>Secrets are fetched from KMS at build time (HIP-0027, HIP-0136). A repository holds the machine identity it authenticates with and nothing else: no vendor token, no registry password, no cluster credential.</p>
<p>The build MUST NOT hold a credential for anything it does not itself call. In particular it holds <strong>no cloud provider token and no kubeconfig</strong>, because it does not deploy (§Deployment below). An upstream credential a <em>service</em> needs at runtime is never handed to the build at all — that is egress&#x27;s custody (HIP-0143).</p>
<h3>5. What a build produces</h3>
<p>A build produces images and stops. It publishes to <strong>one</strong> destination — <code>oci.hanzo.ai/&lt;org&gt;/&lt;app&gt;</code>, the fleet registry — authenticated with the build&#x27;s IAM identity through a per-repository registry token, never a registry password. HIP-0033 is the one statement of where an image goes; <code>ghcr.io/&lt;org&gt;</code> is for already-published open source that outside users pull, and there is no mirror, no second push and no best-effort publication lane.</p>
<p>The org prefix never mixes: Hanzo under <code>hanzoai</code>, Lux under <code>luxfi</code>, Zoo under <code>zooai</code>, on whichever host applies.</p>
<h3>6. Caching</h3>
<p>Builds MUST cache dependency downloads and image layers.</p>
<p>| Language | Cache Mechanism | Configuration | |----------|----------------|---------------| | Go | <code>actions/setup-go</code> built-in | <code>cache-dependency-path: ./go.mod</code> | | Node.js | <code>actions/setup-node</code> built-in | <code>cache: &#x27;pnpm&#x27;</code> (or <code>&#x27;yarn&#x27;</code>) | | Python | <code>astral-sh/setup-uv</code> built-in | Automatic uv cache | | Rust | <code>actions/cache</code> manual | <code>~/.cargo/registry</code>, <code>target/</code> | | Docker | GitHub Actions cache backend | <code>cache-from: type=gha</code>, <code>cache-to: type=gha,mode=max</code> |</p>
<p>Layer caching is the one that matters: a build that changes only the application layer reuses the base image, the dependency install and the compilation layers, which is the difference between a build measured in minutes and one measured in tens of seconds. The cache backend is the forge&#x27;s, reached the same way through <code>act_runner</code>&#x27;s GitHub-Actions-compatible surface.</p>
<h3>7. Image tagging</h3>
<p>All images MUST use this tag scheme:</p>
<pre><code>oci.hanzo.ai/&lt;org&gt;/{service}:{tag}
Tags:
latest - Latest build from default branch
{semver} - Semantic version (e.g., 1.5.2)
{branch}-{sha} - Branch name + short commit SHA (e.g., main-a1b2c3d)</code></pre>
<p>Examples:</p>
<pre><code>oci.hanzo.ai/hanzoai/iam:latest
oci.hanzo.ai/hanzoai/iam:1.5.2
oci.hanzo.ai/hanzoai/iam:main-a1b2c3d
oci.hanzo.ai/luxfi/node:1.17.32</code></pre>
<p>A floating tag never reaches a cluster: <code>hanzoai/universe</code> pins a semver tag, and <code>latest</code> exists for local pulls and nothing else.</p>
<h3>8. Service containers in a test job</h3>
<p>A test job that needs a store MUST use ours, named for what we run (HIP-0144):</p>
<p>| service | image | |---|---| | <code>sql</code> | <code>oci.hanzo.ai/hanzoai/sql</code> | | <code>kv</code> | <code>oci.hanzo.ai/hanzoai/kv</code> | | <code>datastore</code> | <code>oci.hanzo.ai/hanzoai/datastore</code> | | <code>s3</code> | <code>oci.hanzo.ai/hanzoai/s3</code> |</p>
<p>There is no DocumentDB service and no MongoDB image; nothing in the fleet runs one, so a test standing one up is testing against an engine that will not be there. A test that needs no server SHOULD use the embedded SQLite path instead of a service container at all — it is faster and it is what the service runs.</p>
<h3>9. Branch protection</h3>
<p>All repositories MUST configure branch protection on <code>main</code>:</p>
<ol><li><strong>Required status checks</strong>: every job of the reusable workflow must pass</li><li><strong>Require PR review</strong>: At least one approving review before merge</li><li><strong>Require linear history</strong>: Squash or rebase merges only (no merge commits)</li><li><strong>Signed commits</strong>: Encouraged but not required (GPG or SSH signing)</li></ol>
<h3>Conventional Commits</h3>
<p>All commit messages MUST follow the <a href="https://www.conventionalcommits.org/">Conventional Commits</a> specification:</p>
<pre><code>&lt;type&gt;[optional scope]: &lt;description&gt;
Types:
feat: New feature (triggers minor version bump)
fix: Bug fix (triggers patch version bump)
docs: Documentation only
style: Formatting, no code change
refactor: Code change that neither fixes nor adds
perf: Performance improvement
test: Adding or fixing tests
ci: CI/CD changes
chore: Build process or auxiliary tool changes</code></pre>
<p>Semantic-release reads these to determine the next version number automatically. No manual version bumping.</p>
<h2>Implementation</h2>
<h3>Repository Structure</h3>
<p>Every Hanzo repository with CI/CD follows this structure:</p>
<pre><code>hanzo.yml # what to test, what to build (HIP-0142)
.hanzo/
workflows/
cicd.yml # ~7 lines: imports hanzoai/ci
Dockerfile # multi-stage, multi-target
compose.yml # local development (never docker-compose.yml)
Makefile # developer-facing commands</code></pre>
<p>There is no <code>.github/workflows/</code> directory. A repository that still has one has not finished §2, and the files in it either run by accident or do not run at all.</p>
<h3>Secrets a build may read</h3>
<p>The path convention is HIP-0136&#x27;s — the path names the app that READS the secret, the key is exactly the environment variable it becomes, and the environment is <code>prod</code>. A build reads under the release pipeline&#x27;s own path:</p>
<pre><code>hanzo/deploy/&lt;NAME&gt;@prod</code></pre>
<p><code>deploy</code> is a purpose rather than an app, and it is the one standing exception to HIP-0136&#x27;s rule, because nothing reads it but the release pipeline and the pipeline is not a deployed app. It stays until the pipeline is one.</p>
<p>What is <strong>not</strong> there any more, and must not come back: a registry mirror&#x27;s username and token, a cloud provider API token, and an SSH key for a compose host. The first has no second registry to authenticate to (§5); the second and third would let a build reach a cluster, which is the authority §Deployment removes.</p>
<h3>Deployment</h3>
<p><strong>The pipeline does not deploy.</strong> It publishes an image, and that is the end of its authority. It holds no cloud provider token, no kubeconfig and no SSH key, which is why a compromised build cannot reach a cluster.</p>
<p>What runs is declared in <code>hanzoai/universe</code> — <code>charts/app/values/&lt;ns&gt;/&lt;name&gt;.yaml</code> pins the semver tag — and <code>cd.hanzo.ai</code> reconciles the cluster toward that declaration within one poll. Promoting a build is therefore an edit to the declared state, reviewable as a diff, and rolling back is the same edit in reverse.</p>
<p><code>ci.hanzo.ai</code> reads the four values and never writes: no deploy, no retry, no promotion. Two readings it depends on are worth knowing, because both were wrong before they were fixed. A run&#x27;s <strong>jobs</strong> are read rather than its single conclusion — a run that fails at the gate built nothing, a run that fails at the receipt has already built, pinned and proved the release live, and both report <code>failure</code>. And a commit the forge never constructed a run for is <strong>absent</strong>, not failed: there is no log to open, so it is not drawn as a failure.</p>
<h2>Security</h2>
<h3>Threat Model</h3>
<p>| Threat | Mitigation | |--------|-----------| | Leaked secrets in git history | All secrets fetched from KMS at runtime; never written to files or env that persists | | Compromised runner | KMS access tokens are short-lived; the runner holds no persistent credential, and no cluster credential at all | | Supply chain attack via a third-party action | Pin to a full commit SHA, never a mutable tag | | Malicious PR running CI | PRs from forks do not have access to secrets; workflows use <code>pull_request_target</code> carefully | | Container image tampering | GHCR images are content-addressed by digest; Kubernetes can pin to digest | | Privilege escalation in deploy | The build cannot deploy: it has no cluster credential, and the declared state is a reviewed edit in <code>hanzoai/universe</code> | | A workflow that looks like CI and is not | One file in <code>.hanzo/workflows/</code> retires the whole <code>.github/workflows/</code> directory silently; §2 is how that is detected |</p>
<h3>Secret Hygiene Rules</h3>
<ol><li><strong>No secrets in git</strong>: Not in code, not in config files, not in <code>.env</code> files. All secrets come from KMS.</li><li><strong>One stored identity</strong>: the machine identity the build authenticates to KMS with. Everything else is fetched at build time. It is set <strong>on the forge</strong>, which is what executes these workflows; GitHub&#x27;s secret store is not in this path even for a repository whose workflows live under <code>.github/workflows/</code>.</li><li><strong>Mask all secrets</strong>: Every fetched secret MUST be masked with <code>::add-mask::</code> before use.</li><li><strong>Short-lived tokens</strong>: KMS access tokens expire in 15 minutes. If a build takes longer, re-authenticate.</li><li><strong>Audit trail</strong>: KMS logs every secret access. Anomalous patterns (unusual repo, unusual time) trigger alerts.</li></ol>
<h3>Image Scanning</h3>
<p>All Docker images SHOULD be scanned before push using Trivy:</p>
<pre><code class="lang-yaml">- name: Scan image
uses: aquasecurity/trivy-action@&lt;full-sha&gt; # v0.28.0
with:
image-ref: oci.hanzo.ai/hanzoai/${{ env.IMAGE }}:${{ env.VERSION }}
format: &#x27;table&#x27;
exit-code: &#x27;1&#x27;
severity: &#x27;CRITICAL,HIGH&#x27;</code></pre>
<p>Critical vulnerabilities SHOULD block the release; high vulnerabilities SHOULD be reviewed within seven days.</p>
<p>The scanner&#x27;s finding is the gate, read from its exit code. A SARIF upload to GitHub&#x27;s code-scanning surface is <strong>not</strong> available here — that is one of the GitHub-only surfaces §2 names — so a workflow that uploads SARIF and treats a successful upload as the check has no gate at all.</p>
<h3>Supply Chain Security</h3>
<ul><li><strong>Action pinning</strong>: Prefer SHA-pinned actions over tag references. Tags are mutable; a compromised action could be re-tagged to inject malicious code.</li><li><strong>Dependency updates</strong>: repositories SHOULD run automated dependency updates for their workflow&#x27;s third-party actions, with the same SHA-pinning rule applied to the update.</li><li><strong>Provenance</strong>: the build stamp and the bill of materials are HIP-0074&#x27;s; that HIP states what is emitted today and what is target-not-yet-served, and this one does not restate it.</li></ul>
<h2>Monitoring</h2>
<p><code>ci.hanzo.ai</code> answers one question per service: <strong>is what we wrote what is running?</strong> It reads four values that form one causal line, and reports the arrow that did not happen rather than a pass or a fail:</p>
<pre><code>head ──build──▶ built ──pin──▶ declared ──reconcile──▶ running</code></pre>
<p>| value | read from | |---|---| | <strong>head</strong> | the repository&#x27;s default branch | | <strong>built</strong> | the newest commit whose run produced an image | | <strong>declared</strong> | <code>charts/app/values/&lt;ns&gt;/&lt;name&gt;.yaml</code> in <code>hanzoai/universe</code> | | <strong>running</strong> | the workload&#x27;s image in the cluster, by digest |</p>
<p>Three matching values are not health, which is why head is read at all: built, declared and running can agree perfectly while <code>main</code> has moved on and nothing since has built. <code>unbuilt</code> is counted only once a build has STOPPED without producing an image, so a push in flight is not reported as drift.</p>
<p>It reads the cluster through its own ServiceAccount — <code>get</code> and <code>list</code> on workloads, nothing else, no stored credential — and it never writes: no deploy, no retry, no promotion.</p>
<h2>Migration status</h2>
<p>The cutover from <code>arcd</code> to <code>act_runner</code> is done and <code>arcd</code> is retired; the runbook and teardown live in <code>hanzoai/universe</code>. What remains is per-repository: every repository that still carries workflow files under <code>.github/workflows/</code> must sort them into revive / rewrite / drop and delete the directory (§2). Until a repository has done that, one of two things is true of it — either it is still running its GitHub-era pipeline on the forge by accident, or it landed one file in <code>.hanzo/workflows/</code> and silently stopped running everything else.</p>
<h2>References</h2>
<ol><li><a href="https://github.com/hanzoai/ci"><code>hanzoai/ci</code></a> -- the one reusable workflow</li><li><code>hanzoai/.github</code> -&gt; <code>RUNNERS.md</code> -- the runner label taxonomy, single source of truth</li><li><a href="./hip-0142-one-manifest-five-kinds.md">HIP-0142: One Manifest, Five Kinds</a> -- <code>hanzo.yml</code>, and every reader of it</li><li><a href="./hip-0033-container-registry-standard.md">HIP-0033: Container Registry Standard</a> -- where an image is published</li><li><a href="./hip-0027-secrets-management-standard.md">HIP-0027: Secrets Management Standard</a> -- where a build&#x27;s secrets come from</li><li><a href="./hip-0136-one-secret-one-path.md">HIP-0136: One Secret, One Path</a> -- how a secret is addressed</li><li><a href="./hip-0143-egress-outbound-trust-boundary.md">HIP-0143: Egress -- The Outbound Trust Boundary</a> -- why a runtime credential never reaches a build</li><li><a href="./hip-0014-application-deployment-standard.md">HIP-0014: Application Deployment Standard</a></li><li><a href="./hip-1122-deploy-gitops-plane.md">HIP-1122: Deploy -- The GitOps Plane</a> -- what reconciles the declared state</li><li><a href="https://www.conventionalcommits.org/">Conventional Commits Specification</a></li><li><a href="https://slsa.dev/">SLSA Supply Chain Security Framework</a></li></ol>
<h2>Copyright</h2>
<p>Copyright and related rights waived via <a href="https://creativecommons.org/publicdomain/zero/1.0/">CC0</a>.</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/hip-0036.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>