Skip to content
gh-aw-fleet

Reconcile Workflow

gh-aw-fleet is a thin orchestrator around gh aw, git, and gh. It does not rewrite workflow markdown. It resolves desired state from fleet.json and fleet.local.json, then delegates the actual workflow operations upstream.

The loop

Section titled “The loop”
  1. Load config and resolve each repo’s profiles, extras, exclusions, engine, and source refs.
  2. Compare desired state with the target repo’s current workflow files.
  3. Run the relevant gh aw operation in a scratch clone.
  4. Commit workflow changes in the target repo clone.
  5. Open a pull request for review.

All mutating commands are dry-run by default. Nothing is pushed unless you pass --apply.

deploy

Section titled “deploy”

deploy installs the declared workflow set into a repo that may not already have it.

Terminal window
gh-aw-fleet deploy acme/widgets
gh-aw-fleet deploy acme/widgets --apply

The dry-run exercises the same upstream surface used by apply, including gh aw init and gh aw add, but does not push a branch or open a PR.

sync

Section titled “sync”

sync reconciles a repo back to the declared profile set. It adds missing workflows and reports drift where reality no longer matches the fleet definition.

Terminal window
gh-aw-fleet sync acme/widgets
gh-aw-fleet sync acme/widgets --apply

Use --force when you intentionally want the fleet pin to overwrite existing workflow frontmatter.

upgrade

Section titled “upgrade”

upgrade refreshes installed workflows and fleet init artifacts.

Terminal window
gh-aw-fleet upgrade acme/widgets
gh-aw-fleet upgrade --all
gh-aw-fleet upgrade --all --apply

One asymmetry matters: gh aw update follows each workflow’s own frontmatter source: line. Editing fleet.json pins alone does not re-pin already-installed workflows during upgrade; use sync --apply --force when you need installed workflow frontmatter to match current fleet refs.

The three-turn pattern

Section titled “The three-turn pattern”

Any command that mutates external repositories follows this operator flow:

  1. Dry-run and read the plan.
  2. Give explicit approval in the next turn.
  3. Run the same command with --apply.

That pattern keeps branch pushes and PR creation auditable. The tool never force-pushes or commits directly to main.

Failure breadcrumbs

Section titled “Failure breadcrumbs”

Scratch clones under /tmp/gh-aw-fleet-* are preserved after an apply failure. Do not delete them while debugging. Re-run with --work-dir <clone> to resume an interrupted apply once the cause is fixed.

Diagnostics

Section titled “Diagnostics”

Known upstream failure patterns are surfaced with actionable hints. Examples include unknown workflow properties, missing upstream refs, GPG signing failures, and GitHub API 404s.

Use debug logging when you need the subprocess trace:

Terminal window
gh-aw-fleet deploy acme/widgets --log-level=debug --log-format=json