8.1 KiB
Hanzo Git Runner — github.com/hanzoai/git-runner
The agent that executes Actions jobs for git.hanzo.ai. A fork of Gitea's
act_runner, which is itself a daemon wrapped around a vendored nektos/act
(here act/, our fork of it) that runs a workflow's steps in containers.
Shape
main.go→internal/app/cmd— two commands that matter:register(trade a registration token for an identity, write.runner) anddaemon(declare, then poll).internal/app/poll— one poller; asks for work, hands each task tointernal/app/run, bounded byrunner.capacity.internal/app/run— turns a task into anactworkflow and runs it.internal/pkg/report— streams the job's log and step state back.internal/pkg/client— the forge protocol. See below.act/— the vendored executor. Everything above talks to it; it does not talk back to the forge.
The forge protocol
Five operations under /v1/runner on the forge — register, declare, task,
state, log — spoken as ZAP, the house wire. This is not JSON over HTTP with
a house-shaped URL: it is zip.Call, the op-call plane, so the body carries the
same bytes both ends hold in memory.
The forge paths the runner names are /v1/runner/<operation> and zip's own
/.well-known/zip/op/<name> for its traffic, and /v1/artifact/ for a job's
(ACTIONS_RESULTS_URL is the bare forge origin — see artifacts, below). None of
them carries an /api segment.
- The address IS the operation, and the name is derived, not spelled. The
forge registers
POST /v1/runner/<name>; zip derivespost_runner_<name>from it (the leading version segment drops out, so/v1/costs nothing in the name) and the client calls that.TestOpNamespins the client's five literals againstzip.ID, so the two cannot drift. - The messages are
github.com/hanzoai/git/modules/actions/runner, a nested module inside the forge whoserequireblock is empty. It is the ONE definition of the protocol: the forge's handlers declare these very types. Requiring the whole forge module instead does not work — it pinsgo.yaml.in/yaml/v4forward with areplacethat a dependent does not inherit, andactionlintthen fails to compile. - Two rules govern every field on this wire, and both were measured. A
mapis REFUSED at encode ("map cannot cross the plane"), so name/value data travels as[]Pair. Atime.Timeis accepted and then arrives as the ZERO time with no error at all — every field oftime.Timeis unexported, and the encoder skips those — so every timestamp is anint64of unix NANOSECONDS. Nanoseconds because the stored log format keeps 100ns ticks. - The credential is an embedded
forge.Credentialon the four authenticated inputs, declared once and serving both faces: HTTP headers over REST, ordinary arguments over the call plane.client.Forgestamps it, so no caller carries it.registeris the one operation without one, and it doubles as the reachability check — there is no ping. - A refusal arrives as the
*zip.HTTPErrorthe forge returned, status intact, so a caller branches on a value. client.takecopies every string and[]byteout of a reply. This is not belt-and-braces. ZAP reads text zero-copy (zap.Object.Textis anunsafe.Stringover the message) andzip.Callreturns the response to fasthttp's pool as it returns, so a reply's strings point at memory the next call overwrites. Measured on this wire: a token registered asrunner-secretread back1.2.3r-secretone call later, the version string of the call in between laid over its first five bytes, and the forge answered 401 to a runner that was registered.TestOwnpins it. When zip copies on decode, delete this.client.dialregisters its own transport scheme (forge) rather than takinghttp/https: registering a scheme REPLACES what is under that name, and zip's built-in entries carry a Serve half this one does not. It exists because azip.Callcannot be cancelled once it is on the wire — a context deadline fails it before the first byte and never after — so the wait for an answer has to be a ceiling on the transport. That ceiling isrunner.fetch_timeout, and it now bounds every call, not only the one that asks for a job.- There is no long poll and there never was.
taskanswers immediately, always.TaskIn.Queueis the queue version this runner last saw; a forge whose version still matches has queued nothing and answers without opening the assignment transaction. Cadence belongs to the poller (fetch_interval, jitter, capped backoff). ATaskOutwith a nilTaskis an idle forge; an error is an error. Those were once the same thing, and a forge answering in six seconds against a five second wait was therefore indistinguishable from an idle one in every log line and every metric — while resetting the error counter that would have raised the alarm.TestPoller_TimeoutIsAnError. Task.Contextis a struct, not a map. It has to be — a map is refused — and it should be: as a map, the forge sentgit_runtime_tokenwhile the runner readgitea_runtime_tokenand silently fell back to the task token, soACTIONS_RUNTIME_TOKENwas the wrong secret and the mask covered nothing. A field is a compile error; a key is a shrug.- The forge and this fleet share the wire, so they are deployed together. Neither side negotiates a version and there is no shim: a protocol change lands in both repos or in neither, and a rollout takes the forge first and the runners second. In the gap a runner's operations fail, the poller backs off, and jobs queue on the forge until the fleet catches up.
.runneris unchanged by any of this. Not one of its fields came from the old wire, and the two that matter —uuidandtoken— are exactly the credential the new one sends, so a registration made before the cutover keeps working after it.
Artifacts belong to the JavaScript, not to us
The runner does not implement artifact upload; it only tells a job where to send it, and the two protocols place that differently:
ACTIONS_RUNTIME_URL—actions/upload-artifact@v3and its download counterpart concatenate_apis/pipelines/…onto this value verbatim, so the whole base is ours. It is<forge>/v1/artifact/, and the trailing slash is part of the contract.ACTIONS_RESULTS_URL—@actions/artifactv2 (upload-artifact@v4+) reduces this tonew URL(…).originand appends its owntwirp/github.actions.results.api.v1.ArtifactService/…, so nothing about that path is ours to place.- That same library throws
GHESNotSupportedErrorunless the host isgithub.com,*.ghe.comor*.localhost. Ongit.hanzo.aievery v4 step therefore fails before opening a connection. Workflows that need artifacts pin@v3.
Working here
make helplists the development targets.make fmtformats.gofiles,make lint-golints them,make tidyafter anygo.modchange.- One test:
go test -run '^TestName$' ./modulepath/. - A new
.gofile carries the current year in its copyright header. - No trailing whitespace in edited files.
- Preserve existing code comments; do not remove or rewrite one that is still relevant.
go test ./internal/...is fast and covers the poller, the reporter, workflow generation and the wire itself:internal/pkg/clientstands a realzip.Appup on a socket and exercises all five operations against it, so an encode that refuses or a value that does not survive the wire fails here rather than in production.internal/pkg/client/mocksis a hand-written testify double — every operation has the same shape, soanswerdoes the work once.- Do not add a second way to reach the forge.
client.Clientis the interface; everything goes through it.
Conventions inherited from upstream act_runner
- Never force-push, amend, or squash unless asked. Use new commits and normal push for pull request updates.
- Include authorship attribution in issue and pull request comments.
- Commit attribution is set by the git hook; don't add co-author trailers.