A GitHub Action that diagrams every pull request

Here’s a pull request most reviewers have seen. It’s called something like “Retry charges idempotently”. It touches a payments client and a background job, adds forty-odd lines, and the tests pass. The diff is perfectly readable, one file at a time.

What the diff doesn’t show you is the thing you actually need to review: the flow. When does a charge get retried? What happens on a 402 versus a timeout? Who finds out when the retry finally gives up? The answers are spread across two files and the order things happen in, so every reviewer rebuilds that flow in their head, and each of them builds it slightly differently.

We built a GitHub Action so nobody has to.

One comment, one diagram

Comment /flostep on a pull request. The bot reacts 👀, reads the change, and replies with a picture of the flow the PR changes. The picture links to the full walkthrough, where you step through the change one interaction at a time.

In the video, the PR changes payments_client.rb and reconcile_charge_job.rb. The diagram that comes back has 19 steps across checkout, the payments client, the payment provider, the ledger, the job queue, a reconcile job, the database, the mailer and the customer. You can see straight away that a 402 is raised with no retry, that a timeout or 5xx is retried, and that after the last failure the client hands the order to ReconcileChargeJob. That job looks the charge up by its idempotency key instead of charging again. That last part is the whole point of the PR, and it’s the easiest thing to miss reading the diff file by file.

Here’s the same diagram, live. Press Start, then Next:

Where the steps come from

The action has two ways to get a diagram, and it picks the right one for each PR.

1. From committed .flostep files
If your repo keeps flows as .flostep files (plain text, one Who -> Whom: what happens line per step) and the PR changes one, the action previews that file as it stands in the PR. No model is called. When the PR merges to your default branch, the file’s live diagram is updated in place. It’s keyed by the file’s path, so its share link stays the same from one merge to the next, and every doc that embeds it stays current.

2. From the diff, with a model you choose
If the PR doesn’t touch a .flostep file, the action asks a model to read the change and write the steps. It sends the PR’s title and description, the list of changed files and the diff, along with Flostep’s step grammar. Lockfiles, vendored and generated code are left out, and you can add your own exclusions with paths-ignore. If the answer doesn’t parse, the model gets one retry with the parser’s error. And if nothing in the change is flow-shaped, the model says so instead of inventing a diagram.

There is no default model. Which LLM reads your code is your call: Claude, OpenAI, Gemini, Azure OpenAI, Groq, Mistral, OpenRouter, or a self-hosted Ollama or vLLM on your own runner. If you already have something that describes flows, such as an internal tool or gateway, point steps-file at its output and the action publishes that instead of calling a model.

Setting it up

Three steps:

1. Create a Flostep API key with Read & write access at flostep.dev/api-keys, and save it as a repository secret called FLOSTEP_TOKEN.
2. For the AI mode, save your model provider’s API key as a secret too, for example LLM_API_KEY.
3. Add the action to a workflow that runs on issue comments:

- uses: flostep/flostep-action@v1
  with:
    flostep-token: ${{ secrets.FLOSTEP_TOKEN }}
    llm-provider: anthropic
    llm-model: claude-opus-5-5
    llm-api-key: ${{ secrets.LLM_API_KEY }}

Leave out the three llm- inputs and it uses committed .flostep files only. The action’s README has the complete workflow, including the permissions it needs and the trigger that cleans up a PR’s diagrams when it closes. There’s a short version in the CLI docs too.

The details that matter in review

A few choices we made deliberately:

• It runs when someone asks, not on every push. A diagram on every commit is noise. The next /flostep refreshes the same diagram at the same link. If you’d like the comment to say when it’s out of date (“2 commits behind”), add synchronize to the workflow’s pull_request types.
• Hand edits are safe. If someone tidies the diagram in Flostep, the next /flostep leaves their edits alone and says so. /flostep regenerate is the explicit way to overwrite them.
• Cleaning up is one comment. /flostep delete removes the PR’s diagrams and the bot’s comment.
• Only people with write access can run it. That includes a PR’s author only if they have write access to the repository.
• The bot tells you how it went. It reacts 👀 when it starts, then 🚀 when it’s done or 😕 if something went wrong.

Why a walkthrough, and not just a picture

A static diagram of a 19-step flow is a hairball. You can see it in the bot’s preview image, and you’d see it on any whiteboard. What makes it reviewable is order: one interaction at a time, in the sequence they happen, with everything else dimmed. It’s the same idea as explaining a system design step by step, applied to a pull request.

Try it

Add the action to one repository and comment /flostep on the next PR that touches more than one file. If you’d rather drive Flostep from your editor or an agent, the MCP server and the CLI build the same diagrams. And if you just want to see what a walkthrough feels like, try one in your browser. No account needed.