DEV Community

Richard Shade
Richard Shade

Posted on • Originally published at rshade.github.io

introducing gh-aw-fleet

#projects #agents #ai #finops

I started using GitHub Agentic Workflows a couple months ago: small Claude/Copilot agents that run inside your CI for code review, daily doc updates, malicious-code scans, and PR fixes. You author them in markdown, they compile to GitHub Actions, and an AI agent does the work on each run.

Got the first few repos working and hit the question: how am I actually tracking what's deployed on each of these? What version? What profile? What's drifted?

So I built a tool.

what it is

gh-aw-fleet is a declarative fleet manager for GitHub Agentic Workflows. One fleet.json declares your repos and which "profiles" of workflows they get; the CLI reconciles (deploy, sync, upgrade, add), all dry-run by default. It's a thin orchestrator around gh aw, gh, and git, not a fork.

It never rewrites workflow markdown. It answers one question (who gets what workflow, when, and from which profile) and dispatches the actual file work to gh aw. Every operation that touches a repo opens a PR there. Nothing force-pushes or commits to main.

# check drift across the whole fleet, no clones, read-only
gh-aw-fleet status

# bring a repo in line with its declared profile (PR, after a dry-run)
gh-aw-fleet sync acme/widgets --apply
Enter fullscreen mode Exit fullscreen mode

The dry-run gate is the part I lean on most. deploy, sync, and upgrade print exactly what they'd do and change nothing until you add --apply. When you're touching a dozen repos at once, "show me first" is the difference between a tool you trust and one you babysit.

the part I didn't see coming

Usage-based Copilot billing lands 2026-06-01. Every deployed workflow burns credits at metered rates, and the per-repo tools (gh aw, the Actions UI) can't see across the fleet to tell you where the credits went.

The same fleet.json that declares which repos get which workflows turns out to be the natural place to attribute that consumption: by repo, by profile, or by cost center. A consumption rollup is in flight. I went in solving a drift-tracking problem and walked out with a FinOps one.

what's shipped since launch

v0.1.0 shipped April 21 with the core reconcile loop. It's at v0.2.0 now, and the gap is mostly about trusting the tool against more repos:

  • status / drift detection: see what's out of line across the fleet without cloning anything, and gate a CI job on it.
  • JSON output + structured logging: -o json on the read commands, zerolog underneath, so you can pipe results into jq or an aggregator.
  • resumable deploys: pick a half-finished deploy back up at the commit or push gate instead of starting over.
  • a Layer-1 security scanner: secrets and structural rules checked before anything ships.
  • observability-plus profile + an HTTP 402 billing diagnostic: early groundwork for the billing story above.
  • HuJSON config: comments and trailing commas in fleet.json, so you can document why a pin is set right next to the pin.

where it's at

v0.2.0, still pre-1.0: the CLI flags and the fleet.json schema may move before 1.0. But I'm already using it to manage my own repos, and it's working great.

Top comments (0)