Guides

Workflows

Moa runs six GitHub-native workflows on one engine. Each is a recipe for a real job — triage, solve, review, fix CI, address feedback, merge. Start any of them from the CLI, a dashboard button, or a GitHub event.

Read-only workflows (triage, review) never touch code. The writing workflows put changes on a branch and open or update a PR — they never push to main directly. Every CLI command below takes --watch to stream the live step timeline.

Triage an incoming issue#

Reads a new issue, categorizes it, applies the right labels, and leaves a comment. Pure reasoning over the issue — no branch, no code.

bash

moa wf triage your-org/your-repo 7

It also fires automatically: when an issue is opened, Moa can triage it. Labeling an issue moa escalates straight to solve (below).

Turn an issue into a PR#

The headline workflow. Moa branches, the agent writes the fix, the verify-gate runs (typecheck, lint, build), and a PR opens — only if the gate passes.

bash

moa wf solve your-org/your-repo 7 --watch

Tip.Prefer no terminal? Add the moa label to the issue on GitHub and this same workflow runs from the webhook.

Review a pull request#

Reads the diff, leaves specific inline comments, and gives a clear approve or request-changes verdict. Read-only — the agent never touches the branch.

bash

moa wf review your-org/your-repo 12

PRs that are opened, reopened, or pushed to are auto-reviewed — except commits from Moa's own bot account, so it never reviews itself.

Fix failing CI#

Reads the failing checks and their logs, fixes the real cause, runs the local verify-gate, and pushes. CI re-runs — expected green.

bash

moa wf fix-ci your-org/your-repo 12

Address review comments#

Reads the open review threads, pushes a fix for each requested change, and replies in the conversation so reviewers can see what moved.

bash

moa wf address your-org/your-repo 12

To converge a PR to approval in one shot — review, then address, then re-review until green — use the combined loop where available; otherwise run review and address in turn.

Merge when green#

Once checks are green and the review approves, Moa merges. You decide whether merging is automatic or stays a manual click — the engine does the same work either way.

bash

moa wf merge your-org/your-repo 12

What never changes#

The agent only reasons; the harness does every git and gh action.
Writing workflows work on an isolated branch and open or update a PR — never a direct push to main.
Nothing merges until the verify-gate passes and CI is green.

Note.Every command here maps to an entry in the CLI reference. To understand why the work is split this way, read How Moa works.