{"id":49486713,"url":"https://github.com/rshade/gh-aw-fleet","last_synced_at":"2026-05-01T02:04:24.943Z","repository":{"id":352244155,"uuid":"1214003090","full_name":"rshade/gh-aw-fleet","owner":"rshade","description":"Declarative fleet manager for GitHub Agentic Workflows. Reconciles workflow installations across repos via gh aw.","archived":false,"fork":false,"pushed_at":"2026-04-26T22:54:09.000Z","size":1367,"stargazers_count":2,"open_issues_count":14,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-27T00:25:23.380Z","etag":null,"topics":["agentic-workflows","ai-agents","ci-cd","claude-code","copilot","declarative","fleet-management","gh-aw","github-actions","github-actions-workflow","workflow-automation"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rshade.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-18T02:14:18.000Z","updated_at":"2026-04-26T22:54:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rshade/gh-aw-fleet","commit_stats":null,"previous_names":["rshade/gh-aw-fleet"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/rshade/gh-aw-fleet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rshade%2Fgh-aw-fleet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rshade%2Fgh-aw-fleet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rshade%2Fgh-aw-fleet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rshade%2Fgh-aw-fleet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rshade","download_url":"https://codeload.github.com/rshade/gh-aw-fleet/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rshade%2Fgh-aw-fleet/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32482460,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-workflows","ai-agents","ci-cd","claude-code","copilot","declarative","fleet-management","gh-aw","github-actions","github-actions-workflow","workflow-automation"],"created_at":"2026-05-01T02:04:24.246Z","updated_at":"2026-05-01T02:04:24.936Z","avatar_url":"https://github.com/rshade.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gh-aw-fleet\n\nDeclarative fleet manager for GitHub Agentic Workflows.\n\n[![Latest release](https://img.shields.io/github/v/release/rshade/gh-aw-fleet)](https://github.com/rshade/gh-aw-fleet/releases/latest)\n[![License](https://img.shields.io/github/license/rshade/gh-aw-fleet)](LICENSE)\n[![Go version](https://img.shields.io/github/go-mod/go-version/rshade/gh-aw-fleet)](go.mod)\n\n## Status\n\nReleased as **v0.1.0** (April 2026). Pre-1.0: public surfaces (CLI flags,\n`fleet.json` schema) may still change before v1.0. The core reconcile loop\n(`deploy`, `sync`, `upgrade`, `add`) plus read-only drift detection\n(`status`) is functional. `template fetch` works but is still being\nextended.\n\n## Why\n\nWhen you manage 3+ repositories that deploy agentic workflows—markdown-authored\nworkflows that compile to GitHub Actions and run AI agents—keeping them\nconsistent becomes tedious. Each repo independently pins a version of `gh-aw`,\ndrifts on its own, and requires manual sync cycles. `gh-aw-fleet` centralizes\nthat: a single `fleet.json` declares the desired state (which repos get which\nworkflows), and `deploy`, `sync`, and `upgrade` commands bring each repo in\nline via `gh aw add/update/upgrade` under the hood.\n\nWhen those workflows run under\n[usage-based Copilot billing](https://github.blog/news-insights/company-news/github-copilot-is-moving-to-usage-based-billing/)—which\nlands on 2026-06-01—every deployed workflow consumes credits at metered rates,\nand per-repo tools (`gh aw`, the GitHub Actions UI) can't see across the fleet\nto tell you where the credits went. The same `fleet.json` that declares which\nrepos get which workflows is also the natural place to attribute consumption:\nby repo, by profile, or by cost center. A `consumption` subcommand for that\nrollup is in flight\n([#57](https://github.com/rshade/gh-aw-fleet/issues/57)); see\n[ROADMAP.md](ROADMAP.md) for the broader billing-readiness arc.\n\n## Who is this for?\n\n**You'll get value if:**\n\n- You operate **3 or more repositories** that use (or want to use)\n  [`gh-aw`](https://github.com/github/gh-aw)-compiled agentic workflows.\n- You want one place to declare *which workflows belong on which repos*,\n  pinned to specific upstream refs, and a way to bring drifted repos back\n  in line.\n- You're comfortable with PR-based change flow — every fleet operation that\n  touches a repo opens a PR there; nothing force-pushes or commits directly\n  to `main`.\n\n**You probably don't need this if:**\n\n- You operate **one repo** — use `gh aw` directly; there's no fleet to\n  manage.\n- You want to **author** new workflows — that's `gh aw`'s job. This tool\n  only deploys what already exists upstream.\n- You want a **hosted SaaS or daemon** — this is a CLI you run on your\n  laptop or in CI; no server, no webhook, no background reconciler.\n\n## How It Works\n\n**1. gh-aw ships the compiler; `githubnext/agentics` ships the library.**\n`gh-aw` is the markdown→GitHub Actions compiler and an internal dogfooding\ntestbed. The curated, reusable workflows live in the `githubnext/agentics`\nrepository. The `default` profile sources workflows from agentics whenever\nan equivalent exists, falling back to gh-aw only for workflows that don't\nexist elsewhere (currently: `audit-workflows`, `docs-noob-tester`,\n`mergefest`).\n\n**2. The tool is a thin orchestrator.** It never rewrites workflow markdown.\nIt only invokes `gh aw init` (initializes the dispatcher agent in target\nrepos that don't yet have one), `gh aw add` (writes the `source:`\nfrontmatter pin), `gh aw upgrade` (bumps action SHAs + recompiles),\n`gh aw update` (pulls upstream workflow source + 3-way merge), and\n`git`/`gh` for branching, commits, and PRs. All value comes from answering\n*who gets what workflow, when, and from which profile*—not from file\nmanipulation.\n\n**3. Pin-per-profile.** Each profile declares a `sources` map keyed by\nupstream repository (e.g., `github/gh-aw`, `githubnext/agentics`), each\nwith its own ref. The shipped `default` profile pins `github/gh-aw` to a\ntagged release (e.g. `v0.68.3`) and `githubnext/agentics` to a specific\ncommit SHA — never `main`, since moving refs are forbidden by the\n[project constitution](CONTEXT.md). A profile advances atomically: bumping\none source ref re-pins every workflow in that profile sourced from that\nrepo.\n\n**4. Declarative reconcile.** `fleet.json` is the source of truth.\nCommands like `deploy`, `sync`, and `upgrade` compute diffs between desired\nand actual state, then apply them. Edits to `fleet.json` become commits;\nthe tool brings reality in line.\n\n### The reconcile loop at a glance\n\n```mermaid\nflowchart LR\n    A[\"fleet.json\u003cbr/\u003efleet.local.json\u003cbr/\u003e\u003ci\u003e(desired)\u003c/i\u003e\"]\n    B[\"gh-aw-fleet\u003cbr/\u003e\u003ci\u003e(diff + dispatch)\u003c/i\u003e\"]\n    C[\"gh aw\u003cbr/\u003einit / add / upgrade / update\"]\n    D[\"git\"]\n    E[\"gh\"]\n    F[\"Target repo\u003cbr/\u003e.github/workflows/\"]\n    G[(\"PR on target\u003cbr/\u003e\u003ci\u003ereview → merge\u003c/i\u003e\")]\n    A --\u003e B\n    B --\u003e|\"workflow changes\"| C\n    B --\u003e|\"branch + commit\"| D\n    B --\u003e|\"open PR\"| E\n    C --\u003e F\n    D --\u003e F\n    E --\u003e G\n```\n\n`gh-aw-fleet` itself never touches workflow markdown — it only computes\n*what* should change and dispatches the actual work to `gh aw`, `git`,\nand `gh`.\n\n### Concepts\n\n- **Profile** — a named bundle of workflows (`default`, `quality-plus`,\n  etc.) that can be applied to one or more repos. Defined in `fleet.json`\n  under `profiles.\u003cname\u003e`.\n- **Source** — the upstream repository a workflow comes from. Currently\n  either `github/gh-aw` (compiler + dogfooding workflows) or\n  `githubnext/agentics` (the curated library). Each profile pins each\n  source to a specific ref.\n- **Pin** — a fixed reference (tag like `v0.68.3` or commit SHA) that\n  locks a source to a known-good version. Moving refs like `main` are\n  forbidden by the [project constitution](CONTEXT.md).\n- **Spec** — an `owner/repo/path@ref` string (e.g.,\n  `github/gh-aw/.github/workflows/audit-workflows.md@v0.68.3`) that\n  uniquely identifies one workflow at one version. The tool resolves\n  profile + source + workflow name → spec, then passes it to `gh aw add`.\n- **Reconcile** — compute the diff between desired state (`fleet.json`)\n  and actual state (the target repo's `.github/workflows/` directory),\n  then apply just enough commands to bring them into agreement.\n- **Dry-run gate** — `deploy`, `sync`, and `upgrade` print what they would\n  do but make no changes unless `--apply` is passed. This is the default\n  safety mechanism for any operation that touches an external repo.\n\n## Why not just…?\n\n- **Hand-rolled bash loop over `gh aw add`?** Works for 1-2 repos. Past\n  that, you re-derive the loop, the dry-run flag, the profile-to-workflow\n  expansion, and the diagnostic hint patterns each time. This tool\n  packages all of that.\n- **Renovate or Dependabot?** They bump dependency manifests; they don't\n  speak agentic-workflow source pinning, profile composition, or `gh aw`'s\n  3-way merge semantics. Different abstraction.\n- **Terraform / Pulumi for workflow files?** Overkill — there's no\n  infrastructure here, just markdown files and PRs. And the actual\n  compilation and pin management lives in `gh aw`; wrapping it in HCL or\n  TypeScript would re-implement what `gh aw` already does.\n- **A `gh aw` extension that adds fleet semantics?** Plausible alternative\n  — listed as a possible future direction in [CONTEXT.md](CONTEXT.md). For\n  now, this lives outside `gh aw` to evolve independently of the upstream\n  tool's release cadence.\n\n## Quick Start\n\n### Prerequisites\n\n- `gh` CLI authed to your GitHub instance (`gh auth login`) with `repo`\n  and `workflow` scopes\n- `gh aw` extension installed: `gh extension install github/gh-aw` —\n  install a tagged release matching the `github/gh-aw` ref in your\n  `fleet.json` (the shipped `default` profile uses `v0.68.3`). Avoid\n  `main`: it often contains unreleased features that break this tool. To\n  upgrade later, `gh extension upgrade gh-aw` and verify the new tag still\n  matches your fleet pin.\n- Go 1.25.8+ **only if** installing via `go install` or building from\n  source\n\n### Install\n\n**Option 1 — Download a release binary (recommended).** Pre-built binaries\nare published for Linux, macOS, and Windows on amd64 and arm64:\n\n```bash\n# Example: Linux amd64\ngh release download --repo rshade/gh-aw-fleet --pattern '*linux_amd64.tar.gz'\ntar -xzf gh-aw-fleet_*_linux_amd64.tar.gz\nsudo mv gh-aw-fleet /usr/local/bin/\n```\n\nSee the\n[latest release](https://github.com/rshade/gh-aw-fleet/releases/latest)\nfor all available platform archives and checksums.\n\n**Option 2 — `go install`.** Installs into `$(go env GOPATH)/bin`:\n\n```bash\ngo install github.com/rshade/gh-aw-fleet@latest\n```\n\n**Option 3 — Build from source.** For contributors and anyone working off\n`main`:\n\n```bash\ngit clone https://github.com/rshade/gh-aw-fleet.git\ncd gh-aw-fleet\ngo build -o gh-aw-fleet .\n```\n\n\u003e **Note on examples below:** all command examples use bare `gh-aw-fleet`\n\u003e (assumes the binary is on your `PATH`, which is the case for Options 1\n\u003e and 2). If you built from source via Option 3 and didn't install the\n\u003e binary, prefix every `gh-aw-fleet` command with `./` to run it from the\n\u003e build directory.\n\n### Example Workflow\n\nList tracked repos and their resolved workflow sets:\n\n```bash\ngh-aw-fleet list\n```\n\nFetch the upstream catalog (templates.json) so you can review new\nworkflows:\n\n```bash\ngh-aw-fleet template fetch\n```\n\nOnboard a new repo into `fleet.local.json` with a profile (`acme/widgets`\nis a placeholder — substitute your `\u003cowner\u003e/\u003crepo\u003e`). Dry-run first, then\n`--apply`:\n\n```bash\n# dry-run; prints planned change\ngh-aw-fleet add acme/widgets --profile default\n# interactive: prompts for confirmation\ngh-aw-fleet add acme/widgets --profile default --apply\n# non-interactive (CI / scripts): skips prompt\ngh-aw-fleet add acme/widgets --profile default --apply --yes\n```\n\nThe repo entry is written to **`fleet.local.json`** (the private,\ngitignored config), not `fleet.json` (the committed example). See\n[Two config files](#two-config-files) below.\n\nDry-run a deploy to one repo (shows what would be added, no changes\nmade):\n\n```bash\ngh-aw-fleet deploy acme/widgets\n```\n\nApply the deploy (commits, pushes, opens a PR in the target repo):\n\n```bash\ngh-aw-fleet deploy acme/widgets --apply\n```\n\nReconcile a repo (add missing workflows, flag unexpected ones):\n\n```bash\ngh-aw-fleet sync HavenTrack/goa-service-shared --apply\n```\n\nUpgrade all repos to the latest gh-aw and agentics versions:\n\n```bash\ngh-aw-fleet upgrade --all --apply\n```\n\nCheck drift across the fleet without cloning anything (exits 0 only when\nevery repo is aligned — chain it before a deploy in CI):\n\n```bash\ngh-aw-fleet status\ngh-aw-fleet status -o json \\\n  | jq '.result.repos | map(select(.drift_state == \"drifted\")) | length'\n```\n\n## Commands\n\n| Command | Description |\n| --- | --- |\n| `list` | List tracked repos and their resolved workflow sets |\n| `add \u003cowner/repo\u003e` | Add a repo to `fleet.local.json` (dry-run by default) |\n| `deploy \u003crepo\u003e` | Deploy the declared workflow set via `gh aw add` + PR |\n| `sync \u003crepo\u003e` | Reconcile to declared profile (add missing, flag drift) |\n| `upgrade [repo\\|--all]` | Bump profile pins + run `gh aw upgrade` |\n| `template fetch` | Refresh `templates.json` from gh-aw and agentics |\n| `status [repo]` | Diff desired vs actual workflow refs (read-only, no clones) |\n\n## Configuration\n\n### Global flags\n\nAll commands accept these persistent flags:\n\n- **`--dir \u003cpath\u003e`** (default: `.`) — Directory containing `fleet.json` /\n  `fleet.local.json`.\n- **`--log-level \u003clevel\u003e`** (default: `info`) — Log verbosity: `trace`,\n  `debug`, `info`, `warn`, `error`. Use `debug` to see every subprocess\n  invocation, timing, and exit code.\n- **`--log-format \u003cformat\u003e`** (default: `console`) — Log format: `console`\n  (human-readable on stderr) or `json` (structured logs for `jq` /\n  aggregators).\n- **`-o`, `--output \u003cformat\u003e`** (default: `text`) — Output format: `text`\n  (tabular human view) or `json` (machine-readable envelopes for\n  scripting). Supported on `list`, `deploy`, `sync`, `upgrade`, and\n  `status` (`upgrade --all` emits NDJSON). Rejected with a clear error on\n  `template fetch` and `add`.\n\nFor multi-repo failure debugging,\n[`skills/fleet-deploy/SKILL.md`](skills/fleet-deploy/SKILL.md) recommends\n`--log-level=debug --log-format=json 2\u003e/tmp/log.json` and traversing\nsubprocess events with `jq`.\n\n### Two config files\n\n`gh-aw-fleet` reads from up to two files in the working directory:\n\n1. **`fleet.json`** — the committed base config. The repo ships one\n   tracking only `rshade/gh-aw-fleet` itself (the dogfood case); use it\n   as a reference for schema, or replace it with your own committed\n   fleet if you want shared state across collaborators.\n2. **`fleet.local.json`** — a private, gitignored *overlay* on top of\n   `fleet.json`. This is where the `add` command writes by default, and\n   where you can keep entries that shouldn't be committed (private repos,\n   in-flight changes, personal overrides).\n\nWhen both files exist, they are **merged** — `fleet.local.json` profiles,\nrepos, and defaults add to or override matching entries in `fleet.json`.\nWhen only one exists, that one is used directly. The stderr line\n`(loaded fleet.json + fleet.local.json)` (or `(loaded fleet.json)` /\n`(loaded fleet.local.json)` when only one is present) printed at the\nstart of every command tells you which mode is active.\n\nTo start from scratch, copy `fleet.example.json` to `fleet.local.json`\n(or to `fleet.json` if you want it committed) and edit, or use\n`gh-aw-fleet add` to generate entries.\n\n### fleet.json schema\n\nThe declarative desired state. Top-level keys:\n\n- **`version`**: Schema version (currently `1`).\n- **`defaults`**: Fleet-wide defaults. Currently: `engine` (e.g.,\n  `\"copilot\"` for all repos unless overridden).\n- **`profiles`**: Named bundles of workflows. See\n  [Bundled Profiles](#bundled-profiles) below.\n- **`repos`**: Per-repo desired state (profiles, excludes, extras,\n  overrides).\n\nExample fragment:\n\n```json\n{\n  \"version\": 1,\n  \"defaults\": {\n    \"engine\": \"copilot\"\n  },\n  \"profiles\": {\n    \"default\": {\n      \"description\": \"Baseline every tracked repo gets.\",\n      \"sources\": {\n        \"github/gh-aw\": { \"ref\": \"v0.68.3\" },\n        \"githubnext/agentics\": {\n          \"ref\": \"96b9d4c39aa22359c0b38265927eadb31dcf4e2a\"\n        }\n      },\n      \"workflows\": [\n        { \"name\": \"audit-workflows\", \"source\": \"github/gh-aw\" },\n        { \"name\": \"ci-doctor\", \"source\": \"githubnext/agentics\" }\n      ]\n    }\n  },\n  \"repos\": {\n    \"acme/widgets\": {\n      \"profiles\": [\"default\"],\n      \"extra\": [\n        {\n          \"name\": \"shadow-engineer\",\n          \"source\": \"local\",\n          \"path\": \".github/workflows/shadow-engineer.md\"\n        }\n      ]\n    }\n  }\n}\n```\n\n### RepoSpec\n\nPer-repo configuration. Keys:\n\n- **`profiles`** (required): List of profile names to apply.\n- **`engine`** (optional): AI engine override (e.g., `\"gpt-4\"`). Defaults\n  to `defaults.engine`.\n- **`extra`** (optional): Additional workflows not from any profile.\n  Source can be `\"local\"` (lives in the target repo) or an upstream repo\n  name.\n- **`exclude`** (optional): List of workflow names to skip (useful when a\n  profile mostly fits but one or two workflows don't).\n- **`overrides`** (optional): Map of workflow name → custom path (if the\n  upstream path doesn't match convention).\n\n## Bundled Profiles\n\nEach entry below lists what the profile adds, who it's for, and the\nunderlying workflow set.\n\n### `default` — baseline; every tracked repo\n\nLow-noise, broadly useful. 12 workflows (3 gh-aw + 9 agentics).\n\n- **gh-aw**: `audit-workflows`, `docs-noob-tester`, `mergefest`.\n- **agentics**: `ci-doctor`, `code-simplifier`, `daily-doc-updater`,\n  `daily-malicious-code-scan`, `pr-fix`, `weekly-issue-summary`,\n  `issue-arborist`, `sub-issue-closer`, `dependabot-pr-bundler`.\n\n### `quality-plus` — PR-generating quality agents\n\nNoisier. Best for actively-developed repos. 3 agentics workflows:\n`daily-test-improver`, `daily-perf-improver`,\n`repository-quality-improver`.\n\n### `security-plus` — SAST, secret scanning, outbound-traffic audits\n\nBest for repos handling sensitive data. Layers on top of `default`'s\n`daily-malicious-code-scan`. 3 gh-aw workflows: `daily-semgrep-scan`,\n`daily-secrets-analysis`, `daily-firewall-report`.\n\n### `docs-plus` — heavier docs maintenance\n\nBest for repos with a `docs/` directory or published docs site. 6\nagentics workflows: `glossary-maintainer`, `unbloat-docs`, `update-docs`,\n`link-checker`, `markdown-linter`, `daily-multi-device-docs-tester`.\n\n### `community-plus` — contributor-facing helpers\n\nCommand-triggered, dormant when idle. Best for public repos with\nexternal contributors. 4 agentics workflows: `grumpy-reviewer`,\n`pr-nitpick-reviewer`, `archie`, `repo-ask`.\n\n## templates.json\n\nUpstream catalog cache. Populated by `template fetch`. Lists every\nworkflow available from each source (gh-aw, agentics), with parsed\nfrontmatter, descriptions, triggers, tools, permissions, and full body\ntext. This is reviewable inline—humans or LLMs can evaluate new workflows\nand diffs without re-fetching from GitHub. When `template fetch` detects\nnew or changed workflows, it suggests pointing Claude at `templates.json`\nfor evaluation and profile recommendations.\n\n## Design Choices\n\n**Thin orchestrator, not re-implementation.** The tool delegates workflow\ncompilation to `gh aw`, not a homegrown parser. This means improvements\nto `gh aw` flow through automatically; there's no separate maintenance\nburden.\n\n**Asymmetry in deploy vs upgrade.** `deploy` uses the pins from\n`fleet.json`. `upgrade` follows the workflow's own frontmatter pin (the\n`source:` field written by `gh aw add`), then bumps that. This is\nintentional: it allows independent per-workflow decisions while `deploy`\nenforces fleet-wide consistency. To force a re-pin from `fleet.json`\nafter editing it, run `gh-aw-fleet sync --apply --force \u003crepo\u003e` rather\nthan `upgrade` — `upgrade` will not pick up `fleet.json` changes on its\nown.\n\n**Dry-run by default.** `deploy`, `sync`, and `upgrade` default to\ndry-run mode. Pass `--apply` to commit, push, and open PRs. This prevents\nsurprises.\n\n**Conventional Commits.** All generated commits follow the format\n`ci(workflows): \u003cdescription\u003e`, making them easy to filter from\nchangelogs.\n\n## Diagnostic Hints\n\nWhen a command fails (e.g., `gh aw add` returns an error), the tool scans\noutput for known error patterns and surfaces remediation hints. Examples:\n\n- `Unknown property: mount-as-clis` → \"This workflow uses an unreleased\n  gh-aw feature. Upgrade your CLI or pin to a tagged release.\"\n- `HTTP 404` → \"Check the spec—github/gh-aw workflows live under\n  `.github/workflows/`; githubnext/agentics workflows live under\n  `workflows/`.\"\n- `gpg failed to sign` → \"Unlock gpg-agent in your shell and re-run.\" See\n  [Troubleshooting](#troubleshooting) below for the manual-finish recipe.\n\n## Troubleshooting\n\n### gpg signing failed during `--apply`\n\nThis is the most common `--apply` failure mode. The tool runs\n`git commit` non-interactively, so a signing-required git config that\nneeds a passphrase prompt has nowhere to surface it. **The tool never\nbypasses signing** (no `--no-gpg-sign`, no `commit.gpgsign=false`) — it\npreserves the in-progress clone so you can finish the commit in your own\nshell where gpg-agent can prompt you.\n\nWhen `--apply` fails on gpg signing:\n\n1. The clone directory is preserved at\n   `/tmp/gh-aw-fleet-\u003cowner\u003e-\u003crepo\u003e-\u003ctimestamp\u003e/` with all files staged\n   on the deploy branch.\n2. `cd` into that directory and finish manually:\n\n   ```bash\n   cd /tmp/gh-aw-fleet-\u003cowner\u003e-\u003crepo\u003e-\u003ctimestamp\u003e\n   git commit -m 'ci(workflows): add \u003cN\u003e agentic workflows via gh-aw-fleet'\n   # branch is fleet/deploy-\u003ctimestamp\u003e\n   git push -u origin \u003cbranch-name\u003e\n   gh pr create \\\n     --title \"ci(workflows): add \u003cN\u003e agentic workflows via gh-aw-fleet\" \\\n     --body \"...\"\n   ```\n\n3. The full template (with body, conventional-commits validation rules,\n   and edge-case handling for `gh aw init` and skipped workflows) is in\n   [`skills/fleet-deploy/SKILL.md`](skills/fleet-deploy/SKILL.md).\n\n### `Unknown property: mount-as-clis` and similar pre-flight failures\n\nA workflow uses a feature that is in upstream `gh-aw` `main` but not yet\nin your installed CLI. Either upgrade the CLI\n(`gh extension upgrade gh-aw`), or — preferably — pin the source ref in\n`fleet.json` to a tagged release and run\n`gh-aw-fleet sync --apply --force \u003crepo\u003e` to re-pin.\n\n### Resuming after a partial failure\n\nThe `--work-dir \u003cpath\u003e` flag points `deploy` / `upgrade` / `sync` at an\nexisting clone instead of cloning fresh. Use it with the\n`/tmp/gh-aw-fleet-*` directory preserved from a failed run to re-attempt\nwithout re-cloning.\n\nWhen `deploy --apply --work-dir \u003cpath\u003e` is run against a preserved clone\nthat has staged workflow changes, the tool resumes at the commit gate\n(skipping clone, `gh aw init`, and `gh aw add`). If the user manually\ncommitted after a GPG failure, the tool detects the unpushed commits and\nresumes at the push gate, proceeding directly to `git push` and\n`gh pr create`.\n\n## Known Limitations \u0026 Roadmap\n\n- **Sync dry-run doesn't do deploy preflight.** `sync --dry-run` computes\n  the diff but doesn't pre-validate that the workflows would deploy\n  successfully.\n- **No GitHub extension packaging yet.** `gh-aw-fleet` is distributed as\n  a standalone CLI (release binary, `go install`, or build from source —\n  see [Install](#install)), not as a `gh` extension. Extension packaging\n  is planned.\n\n## Further reading\n\n- **[CONTEXT.md](CONTEXT.md)** — the project constitution. Architectural\n  identity, hard scope boundaries, and what this tool deliberately does\n  *not* do. Read before proposing features.\n- **[ROADMAP.md](ROADMAP.md)** — what's actively being built within those\n  boundaries.\n- **[CHANGELOG.md](CHANGELOG.md)** — release history (managed via\n  [release-please](https://github.com/googleapis/release-please)).\n- **`skills/`** — operator playbooks codifying recurring workflows. Each\n  is a complete runbook with the three-turn dry-run → approval → apply\n  pattern:\n  - [`fleet-deploy`](skills/fleet-deploy/SKILL.md) — deploy a profile to\n    one repo (includes the gpg manual-finish recipe).\n  - [`fleet-upgrade-review`](skills/fleet-upgrade-review/SKILL.md) — bump\n    source pins and review the resulting PR.\n  - [`fleet-onboard-repo`](skills/fleet-onboard-repo/SKILL.md) — add a\n    brand-new repo to the fleet.\n  - [`fleet-eval-templates`](skills/fleet-eval-templates/SKILL.md) —\n    evaluate upstream template catalog for new workflows.\n  - [`fleet-build-profile`](skills/fleet-build-profile/SKILL.md) —\n    materialize a chosen workflow set as a `fleet.json` profile.\n- **[CLAUDE.md](CLAUDE.md)** — invariants for AI coding agents working\n  in this repo. Useful for human contributors too as a quick reference.\n\n## Contributing \u0026 Development\n\nSee [ROADMAP.md](ROADMAP.md) for what's actively in flight, and the\n[issue tracker](https://github.com/rshade/gh-aw-fleet/issues) for places\nto start. Before opening a PR, run the full local gate:\n\n```bash\nmake ci         # fmt-check + vet + lint + test (the same gate CI runs)\n```\n\nOr step by step:\n\n```bash\nmake fmt        # apply gofmt\nmake lint       # golangci-lint — can take 5+ minutes; do not skip\nmake test       # full test suite\n```\n\nIf `make ci` passes locally, CI will pass.\n\n**For AI coding agents** working in this repo, see [CLAUDE.md](CLAUDE.md)\nfor the invariants (no bypassing gpg signing, no direct git invocations,\netc.) and `.claude/settings.json` for the shell-command allowlist that\nlets subagents run without prompting.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frshade%2Fgh-aw-fleet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frshade%2Fgh-aw-fleet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frshade%2Fgh-aw-fleet/lists"}