Agentic campaigns

Overview

Agentic campaigns coordinate one or more agentic workflows toward a single goal.

Why use campaigns?

Strategic Goals

Define objectives with measurable KPIs that track progress automatically

Unified Tracking

GitHub Project board shows all work items and real-time status

Built-in Governance

Rate limits and safety controls keep automation predictable and safe

Reuse Workflows

Coordinate existing agentic workflows without modification

Workflow

1. Define - Write a .campaign.md spec with objectives and workflows
2. Compile - Generate the orchestrator with gh aw compile
3. Execute - Orchestrator coordinates work (passive tracking or active execution)
4. Track - GitHub Project board shows real-time progress

When compiled, this generates an orchestrator that discovers work, tracks progress on the GitHub Project board, and coordinates worker workflows to execute upgrades.

Note that there are two orchestration modes: Passive coordination (default): Discover and track work created by independent workflows. Active execution (execute-workflows: true): Run workflows directly, create missing workflows, and drive progress.

Apart from this spec file, a campaign is composed of: Orchestrator (.campaign.lock.yml) - Auto-generated coordinator workflow Workers - Your existing agentic workflows (no changes needed)

The orchestrator discovers work, updates your project board, and delegates to workers. Workers stay focused on their specific tasks while the orchestrator handles coordination.

Example campaign

A campaign is defined by a Campaign Spec .campaign.md. Here is an example of such a file for a simple framework upgrade campaign:

---
id: framework-upgrade
name: "Framework Upgrade"
project-url: "https://github.com/orgs/myorg/projects/42"
tracker-label: "campaign:framework-upgrade"

objective: "Upgrade all services to Framework vNext"
kpis:
  - id: services_upgraded
    name: "Services upgraded"
    priority: primary
    target: 50

workflows:
  - framework-scanner
  - framework-upgrader

# Enable active workflow execution
execute-workflows: true

governance:
  max-project-updates-per-run: 20
---

With execute-workflows: true, the orchestrator will:

• Run framework-scanner (create it if doesn’t exist)
• Test newly created agentic workflows before use
• Execute framework-upgrader using scanner outputs
• Track all progress on the GitHub Project board

Common use cases

Migration Projects

systematic

Coordinate changes across repositories with automated tracking

Security Fixes

time-bound

Resolve vulnerabilities systematically with clear progress metrics

Quality Improvements

ongoing

Enhance test coverage and documentation incrementally

Large Refactorings

phased

Execute architectural changes with milestone tracking

Next steps

• Quick start - Create your first campaign in 5 steps
• Campaign specs - Learn the specification format and configuration options
• Project management - Set up GitHub Project boards for campaign dashboards
• CLI commands - Reference for campaign compilation and management