gh-aw-fleet: A Declarative Fleet Management Tool for GitHub Agentic Workflows

Core Overview

gh-aw-fleet is a declarative fleet manager for centrally managing GitHub Agentic Workflows across multiple repositories, supporting cross-repo workflow deployment, synchronization, and upgrades via a single configuration file.

Basic Information

• Original Author/Maintainer: rshade
• Source Platform: GitHub
• Original Link: https://github.com/rshade/gh-aw-fleet
• Release Time: June 2026
• Current Version: v0.1.0 (released in April 2026)

With the popularity of GitHub Agentic Workflows across multiple repositories, maintaining consistency faces challenges:

1. Configuration Drift: Each repository fixes the gh-aw version independently, leading to inconsistent configurations that require manual synchronization.
2. Cost Tracking Difficulties: GitHub Copilot switched to a usage-based billing model on June 1, 2026. Per-repo tools cannot view credit consumption across the fleet, making cost management complex.

When managing 3 or more repositories using Agentic Workflows, decentralized management becomes cumbersome.

gh-aw-fleet achieves centralized management through the following mechanisms:

1. Declarative Configuration: Use the fleet.json file to declare the desired state (mapping between repositories and workflows) and pin upstream versions.
2. Coordination Commands:
   • deploy: Deploy workflows to specified repositories
   • sync: Synchronize configurations to all repositories
   • upgrade: Upgrade workflows to new versions
   • add: Add new repositories to the fleet
3. Drift Detection: The status command can detect repositories where configurations deviate from the desired state.
4. Cost Tracking: fleet.json supports attributing consumption by repository/config file/cost center. A consumption subcommand will be launched in the future (see Issue #57).

PR-Based Workflow

Each fleet operation opens a PR in the target repository, with no force pushes or direct commits to the main branch, ensuring changes are reviewable and traceable.

Relationship with gh-aw

They complement each other:

• gh-aw is responsible for compiling Markdown workflows into GitHub Actions and running AI agents;
• gh-aw-fleet is responsible for deploying existing upstream workflows and does not involve creating new workflows.

Suitable For

• Operating 3 or more repositories using or planning to use gh-aw-compiled Agentic Workflows;
• Wanting to centrally declare the mapping between workflows and repositories and pin upstream versions;
• Needing to synchronize repositories that deviate from the desired state;
• Familiar with PR-based change processes.

Not Suitable For

• Operating only 1 repository (use gh aw directly);
• Needing to create new workflows (responsibility of gh aw);
• Wanting to use a hosted/centralized service (this tool is a local CLI with no server components).

Project Status

The current version is v0.1.0 (released in April 2026). Public interfaces (CLI flags, fleet.json schema) may change before v1.0. Core commands (deploy/sync/upgrade/add), drift detection (status), and template fetch features are available.

Practical Value

• Configuration Consistency: Ensure all repositories use the correct version of workflows;
• Reduced Management Overhead: Shift from per-repo management to centralized declarative management;
• Cost Visibility: Lay the foundation for cross-repo Copilot usage tracking;
• Secure Changes: Ensure changes are reviewable via PR processes.

gh-aw-fleet represents a paradigm shift in infrastructure management: from imperative (individual operations) to declarative (describing desired states). This paradigm has been validated in tools like Kubernetes and Terraform, and is now applied to GitHub workflow management.

For teams adopting GitHub Agentic Workflows, especially those using Copilot's usage-based billing model, gh-aw-fleet provides the necessary management layer to help maintain control as scale increases.