Sweeping every repo in your org

A sweep is a type for one instruction that needs to land in more than one repository — bump a dependency everywhere, roll out a lint rule, rename an environment variable across every service. Instead of filing a separate task per repo yourself, you file one sweep with a single objective, and its discover stage does the fan-out for you: it matches your repos, files one child task per match, and hands each of them off to build independently. Reach for a sweep whenever the same instruction applies across many repos and you’d otherwise be copy-pasting a task description into a dozen separate tasks.

Filing a sweep

Create it like any other task, with --type sweep:

ch task create --title "Bump the Go toolchain to 1.23" --type sweep

You don’t pass --repo — a sweep doesn’t build against one repo itself; discovery finds the repos it applies to. From the web app, open the New task form and pick Sweep from the type list.

A sweep takes one field beyond the ones every task has: objective. It isn’t available at creation time — ch task create only takes the native flags (--title, --type, --priority, and the rest) — so fill it in afterwards:

ch task edit <taskId> --objective-file objective.md

or inline for something short:

ch task edit <taskId> --objective "Bump the go directive in go.mod to 1.23 and run go mod tidy."

Writing a good objective

objective is the instruction the discover stage hands to every child task it files — the same text becomes each child’s brief, applied against that child’s own repo. Write it the way you’d write a task description for a single repo, without naming a repo in it: describe the change, not the target. CodeHerder rejects an empty or near-empty objective, so a placeholder word won’t get you past discover — write the real instruction before you file the sweep, or fill it in as soon as you do.

What discovery does

The discover stage is the only stage on a sweep that runs an agent. It:

Enumerates the repositories visible in your git host org through the host CLI.
Lists the repositories already registered in your workspace (see Connecting repositories).
Matches the two lists, and files one sweep_child task per match — each carrying your objective and pointed at that repo.
Writes a discovery_report naming every repo it matched, and every one it didn’t.

A sweep can’t leave discover until objective, discovery_report, and at least one child task all exist — the same kind of stage gate that holds a story or feature at plan until its required fields are written. See How work flows for how stage gates work in general.

Unregistered repos are skipped, not registered automatically

Discovery only files a child for a repo that’s already registered in your workspace. A repo that exists in your git host org but isn’t registered here is left out — named as skipped in the discovery report, never registered on your behalf. Registering a repo is a decision for a human to make deliberately, not something a sweep does as a side effect. If you want that repo included next time, register it first (see Connecting repositories) and file a new sweep.

The 50-child cap

A sweep can have at most 50 direct children, the same fan-out cap that applies to any parent task in CodeHerder. If discovery matches more than 50 repos, it stops filing once it hits the cap and names every repo it didn’t get to in the discovery report, so you know what was left out and can follow up with a second sweep for the rest.

While children are running

Once discovery has filed at least one child, the sweep moves to in_progress and stays there — the same non-executable holding state an epic or initiative sits in while its children are worked (see Core concepts). No agent runs on the sweep itself at this stage; it’s purely a container waiting on its children.

The sweep completes on its own once every child reaches done. If a child instead ends up somewhere else terminal — cancelled, for instance — the sweep doesn’t close automatically; it’s left for a human to look at rather than reporting a fan-out as finished when part of it didn’t land.

What each child task does

Each sweep_child runs the same lightweight pipeline as a plain task: todo → code → merge → done. It starts itself — you never need to move it off todo by hand — builds your objective against its own repo, opens its own merge request, and lands it, ending in its own done. One sweep with ten matching repos produces ten separate merge requests, one per repo. A sweep_child’s only allowed parent is a sweep — it’s the type discovery files for you, not one you’d normally create by hand.

Before you file one

Discovery and every child it files need the same things any build task needs, just across more repos at once:

Every repo you want in scope is already registered in your workspace.
A device with the git-host CLI installed and signed in (gh for GitHub, glab for GitLab) — the same requirement covered in Connecting repositories.
An agent whose launch config can run the top model tier — discover asks for it, the same way any other stage names a required capability. See Capabilities and Assigning and claiming work.

When nothing matches

If none of your org’s repos matches one registered in your workspace, discovery has nothing to file. Rather than leaving the sweep sitting at in_progress with no children, it cancels the sweep itself, with a reason pointing at the discovery report so you can see why nothing was filed — register the repos you expected to see, and file the sweep again.

Watching progress

A sweep’s task page lists its children the same way any parent task does — see Understanding the task hierarchy for the breadcrumb, parent row, and children list. ch task children <taskId> lists them from the CLI, and ch task tree <taskId> renders the whole sweep with every child underneath it. The Tasks page’s List and Board views, and the task’s own activity feed, show the same per-child progress — see Finding and tracking your work.

Understanding the task hierarchy — the sweep → sweep_child nesting level, and navigating a sweep’s children
Writing tasks an agent can build — choosing a type and filling required fields
Connecting repositories — registering a repo so discovery can match it
Customising workflows — the full built-in type catalog
Finding and tracking your work — watching a sweep’s children move
Assigning and claiming work — auto-staffing and the capabilities that route work