From local graph to GitHub comment
PR Lens’s publication problem begins after the graph is valid and the SVG is stable: how do those artifacts reach a reviewer without losing their identity or being replaced by an older run? This chapter follows the path from local files to a GitHub comment, then compares the CLI, coding-agent skill, and GitHub Action as different operating choices. The goal is not to memorize commands, but to understand why artifact provenance, cache-safe addresses, freshness checks, and comment ownership are part of a correct review aid.
The comment must describe the picture that exists
The CLI separates creation from publication. analyze produces a graph from a diff. render turns that graph into light and dark SVGs, a manifest, and a drawn.graph.json. comment then composes Markdown from the drawn document and manifest. It does not post anything by itself; the caller decides whether to use GitHub CLI, an Action, another automation tool, or a different host for the assets.
That separation solves a subtle consistency problem. Rendering is where repository corrections are applied. An exclusion can remove a node, every edge attached to it, a flow that no longer has enough participants, or a view whose selection is now empty. If comment composition used the original graph from analysis, the text could promise a drill-down section whose picture was never written. The manifest records the assets that were actually produced, while drawn.graph.json records the corrected graph those assets represent.
Before composing, the CLI compares the content hash of the graph with the hash recorded in the manifest. A mismatch is refused. This is stronger than matching file names because two files can have plausible names and still come from different runs or different corrections. The hash check turns the pair into a provenance claim: these pictures came from this graph. If an operator accidentally passes the pre-correction graph, the comment step reports the problem instead of building a polished description of nonexistent diagrams.
The resulting comment is designed for GitHub’s narrow reading surface. A wide architecture picture is scaled to fit the comment column, and the image links to itself so a reviewer can open it at the size its labels require. Theme-specific assets are paired with <picture>: the dark source is selected in a dark GitHub theme, while a light image remains the fallback for clients that do not make that choice. Nested details sections carry the narrower views, so a reviewer can begin with the overview and open the new path or retired path only when needed.
This packaging preserves the graph’s different kinds of attention. The heading and summary state what changed. The headline chips can show scale. The overview diagram supplies context. The details tree supplies controlled drill-down. A data-flow image can then show the order of behavior rather than asking the reader to infer it from the architecture layout.