The walkthrough bot

What it exercises, and how to run one — WALKTHROUGH.md

Walkthroughs

Three kinds now, and the first is the one to reach for.

The maintained set lives in the console, at /guides — twenty-one of them, shipped inside the console image so they version with the pages they describe, and published as a static site at site/ in this repository. A test resolves every link in every guide against the router, so a guide naming a renamed route fails the build rather than 404ing for a reader.

The two documents below are records rather than manuals: each is an account of something that happened on a particular day, kept in that form deliberately. Where they overlap a guide, the guide is the one that is maintained.

The platform, exercised end to end by a bot, out loud. In Zulip:

@walkthrough static          a static site to production, then a pull request through a
                             review environment and a merge to the same URL (~12 min)
@walkthrough rails           a Rails service, its worker, its docs site and its database,
                             from a template to production (~15 min; no review environment)
@walkthrough teardown        remove what the walkthroughs created (all | static | rails)
@walkthrough status          what is running, and the host's memory

Everything lands in the #walkthroughs stream, one topic per run, one message per step. Each message is the same shape: what was done, a spoiler with the log lines pulled for exactly that step — project-flow's own lines for the walkthrough's trace, every build stage's last lines, the controller-manager's lines about the binding — and the links: repository, commit, pull request, Argo, the build page, the trace, the component, the URL.

Those last few used to read "the Build dashboard, the build viewer, the component's 360". apps/buildviewer is deleted and builds.devtools.jung.town does not resolve; project-flow kept the viewer key and retargeted it at the console, and component_360 was superseded by the component page. Only the labels were left behind.

The closing message links the whole run as one trace; that trace links every build's trace, and every build's head span links back.

What it touches

How it works

The bot only talks to project-flow (apps/zulip-bots/bots/platform_api.py), which grew the primitives: POST /projects/scaffold (render the template from platform-eng/templates, create the repo, commit, hook, apply, pin), POST /projects/teardown, POST /git/commit|pr|merge, GET /builds, GET /evidence/build/<run>, GET /evidence/binding/<name>, GET /evidence/flow?trace_id=, GET /host, and a lock so only one walkthrough runs at a time. Every wait is the bot polling a read endpoint; nothing in the controller blocks.

A commit made through /git/commit carries the walkthrough's traceparent, which project-flow remembers against the SHA — so when the push webhook arrives and the build's head span is written, that span links to the walkthrough's trace.

Memory

The host has 32GB and five clusters. The static walkthrough wants 1.5GB free, the rails one 3.5GB (GET /host reads node_memory_MemAvailable_bytes); below that it refuses to start. A phase that times out posts everything it collected and stops — nothing is torn down on failure, because the point is to look at it. OC_MAX_REVIEW_ENVS is 2 so the static walkthrough's review environment fits beside one real PR — though the deployed value is 1 on this host, and a second open pull request is told so on the pull request rather than silently given nothing.