diff --git a/.github/workflows/shared/campaign.md b/.github/workflows/shared/campaign.md index 1923891b6c..674ced1fcf 100644 --- a/.github/workflows/shared/campaign.md +++ b/.github/workflows/shared/campaign.md @@ -1,5 +1,5 @@ --- -# Shared safe-outputs defaults for campaign orchestrators. +# Shared safe-outputs defaults for campaign orchestator. # Intended to be included via frontmatter `imports:`. # Workflows may override any specific safe-output type by defining it at top-level. diff --git a/docs/src/content/docs/examples/campaigns.md b/docs/src/content/docs/examples/campaigns.md deleted file mode 100644 index 0a261ce1ab..0000000000 --- a/docs/src/content/docs/examples/campaigns.md +++ /dev/null @@ -1,197 +0,0 @@ ---- -title: Campaign Examples -description: Example campaign workflows with worker patterns and idempotency -sidebar: - badge: { text: 'Examples', variant: 'note' } -banner: - content: '⚠️ Experimental: This feature is under active development and may change or behave unpredictably.' ---- - -Example campaigns demonstrating worker coordination, standardized contracts, and idempotent execution patterns. - -## Security Audit Campaign - -**Security Audit 2026** demonstrates: - -- Worker discovery via tracker labels -- Dispatch-only worker design -- Standardized input contracts (`campaign_id`, `payload`) -- Idempotent execution with deterministic keys -- KPI tracking for vulnerability metrics - -The campaign coordinates three workers (scanner, fixer, reviewer) that create security-related issues and pull requests. Workers use deterministic branch names and titles to prevent duplicates. - -### Key patterns - -**Orchestrator responsibilities (dispatch-only):** -- Runs discovery precomputation (writes a manifest for the agent) -- Dispatches workers on schedule -- Coordinates work by dispatching allowlisted workflows - -**Worker responsibilities:** -- Accepts `workflow_dispatch` only -- Uses standardized inputs -- Generates deterministic keys -- Checks for existing work -- Labels outputs with the campaign tracker label (defaults to `z_campaign_`) - -## Security Scanner Worker - -[**Security Scanner**](/gh-aw/examples/campaigns/security-scanner/) shows worker implementation: - -```yaml -on: - workflow_dispatch: - inputs: - campaign_id: - description: 'Campaign identifier' - required: true - type: string - payload: - description: 'JSON payload with work item details' - required: true - type: string -``` - -The worker: -1. Receives dispatch from orchestrator -2. Scans for vulnerabilities -3. Generates deterministic key: `campaign-{id}-{repo}-{vuln_id}` -4. Checks for existing PR with that key -5. Creates PR only if none exists -6. Labels PR with `z_campaign_{id}` - -## Worker design patterns - -### Standardized contract - -All campaign workers accept the same inputs: - -```yaml -inputs: - campaign_id: - description: 'Campaign identifier' - required: true - type: string - payload: - description: 'JSON payload with work details' - required: true - type: string -``` - -The payload contains work item details in JSON format. - -### Idempotency - -Workers prevent duplicate work using deterministic keys: - -``` -campaign-{campaign_id}-{repository}-{work_item_id} -``` - -Used in: -- Branch names: `campaign-security-audit-myorg-myrepo-vuln-123` -- PR titles: `[campaign-security-audit] Fix vulnerability 123` -- Issue titles: `[campaign-security-audit] Security finding 123` - -Before creating items, workers search for existing items with the same key. - -### Dispatch-only triggers - -Workers in the campaign's `workflows` list must use only `workflow_dispatch`: - -```yaml -# Correct -on: - workflow_dispatch: - inputs: ... - -# Incorrect - campaign-controlled workers should not have other triggers -on: - schedule: daily - workflow_dispatch: - inputs: ... -``` - -Workflows with schedules or event triggers should run independently and let the campaign discover their outputs. - -## File organization - -``` -.github/workflows/ -├── security-audit.md # Campaign orchestrator workflow -├── security-audit.lock.yml # Compiled orchestrator -├── security-scanner.md # Worker workflow -├── security-fixer.md # Worker workflow -└── security-reviewer.md # Worker workflow -``` - -Workers are regular workflows, not in campaign-specific folders. The dispatch-only trigger indicates campaign ownership. - -## Campaign lifecycle integration - -### Startup - -1. Orchestrator dispatches workers -2. Workers create issues/PRs with campaign labels -3. Next run discovers these items -4. Items added to project board - -### Ongoing execution - -1. Orchestrator dispatches workers (new work) -2. Discovers outputs from previous runs -3. Updates project board incrementally -4. Reports progress against KPIs - -### Completion - -1. All work items processed -2. Final status update with metrics -3. Campaign state set to `completed` -4. Orchestrator disabled - -## Idempotency example - -```yaml -# Worker checks for existing PR before creating -- name: Check for existing PR - id: check - run: | - KEY="campaign-${{ inputs.campaign_id }}-${{ github.repository }}-vuln-123" - EXISTING=$(gh pr list --search "$KEY in:title" --json number --jq '.[0].number') - echo "existing=$EXISTING" >> $GITHUB_OUTPUT - -- name: Create PR - if: steps.check.outputs.existing == '' - uses: ./actions/safe-output - with: - type: create_pull_request - title: "[$KEY] Fix vulnerability 123" - body: "Automated security fix" - labels: "z_campaign_${{ inputs.campaign_id }}" -``` - -## Independent workflows - -Workflows not in the campaign's `workflows` list can run independently with their own triggers: - -```yaml -# Independent worker - keeps its schedule -on: - schedule: - - cron: '0 2 * * *' - workflow_dispatch: - -# Creates items with campaign label for discovery -labels: ["z_campaign_security-audit", "security"] - -The recommended campaign tracking label format is `z_campaign_`. If you need compatibility with older tooling that filters `campaign:*` labels, you can optionally apply both labels. -``` - -The campaign discovers these via tracker labels without controlling execution. - -## Further reading - -- [Campaign guides](/gh-aw/guides/campaigns/) - Setup and configuration -- [Safe outputs](/gh-aw/reference/safe-outputs/) - dispatch_workflow configuration diff --git a/docs/src/content/docs/examples/project-tracking.md b/docs/src/content/docs/examples/project-tracking.md index 0f09f8cef0..535cecff2a 100644 --- a/docs/src/content/docs/examples/project-tracking.md +++ b/docs/src/content/docs/examples/project-tracking.md @@ -233,9 +233,9 @@ safe-outputs: ## Relationship with Campaigns -The `project` field brings project tracking capabilities from [campaign orchestrators](/gh-aw/examples/campaigns/) to regular agentic workflows: +The `project` field brings project tracking capabilities from [campaign coordinators](/gh-aw/guides/campaigns/) to regular agentic workflows: -**Campaign orchestrators** (campaign.md files): +**Campaign coordinators** (campaign.md files): - Use `project-url` in campaign spec - Automatically coordinate multiple workflows - Track campaign-wide progress @@ -337,4 +337,4 @@ Update the project item with the team field. - [update-project](/gh-aw/reference/safe-outputs/#project-board-updates-update-project) - Detailed update-project configuration - [create-project-status-update](/gh-aw/reference/safe-outputs/#project-status-updates-create-project-status-update) - Status update configuration - [GitHub Projects V2 Tokens](/gh-aw/reference/tokens/#gh_aw_project_github_token-github-projects-v2) - Token setup guide -- [Campaigns](/gh-aw/examples/campaigns/) - Campaign orchestrator documentation +- [Campaigns](/gh-aw/guides/campaigns/) - Campaign coordination documentation diff --git a/docs/src/content/docs/guides/campaigns/getting-started.md b/docs/src/content/docs/guides/campaigns/getting-started.md deleted file mode 100644 index 0827eb2637..0000000000 --- a/docs/src/content/docs/guides/campaigns/getting-started.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: Getting started -description: Quick start guide for creating campaign workflows -banner: - content: '⚠️ Experimental: This feature is under active development and may change or behave unpredictably.' ---- - -This guide shows how to create a campaign workflow that coordinates work across repositories. - -## Prerequisites - -- Repository with GitHub Agentic Workflows installed -- GitHub Actions enabled -- A GitHub Projects board (or create one during setup) - -## Create a campaign workflow - -1. **Create a new workflow file** at `.github/workflows/my-campaign.md`: - -```yaml wrap ---- -name: My Campaign -on: - schedule: daily - workflow_dispatch: - -permissions: - issues: read - pull-requests: read - -imports: - - shared/campaign.md ---- - -# My Campaign - -- Project URL: https://github.com/orgs/myorg/projects/1 -- Campaign ID: my-campaign - -Your campaign instructions here... -``` - -2. **Set up authentication** for project access: - -```bash -gh aw secrets set GH_AW_PROJECT_GITHUB_TOKEN --value "YOUR_PROJECT_TOKEN" -``` - -See [GitHub Projects V2 Tokens](/gh-aw/reference/tokens/#gh_aw_project_github_token-github-projects-v2) for token setup. - -3. **Compile the workflow**: - -```bash -gh aw compile -``` - -4. **Commit and push**: - -```bash -git add .github/workflows/my-campaign.md -git add .github/workflows/my-campaign.lock.yml -git commit -m "Add my campaign workflow" -git push -``` - -## How it works - -The campaign workflow: - -1. Imports standard orchestration rules from `shared/campaign.md` -2. Runs on schedule to discover work items -3. Processes items according to your instructions -4. Updates the GitHub Project board with progress -5. Reports status via project status updates - -## Campaign orchestration - -The `imports: [shared/campaign.md]` provides: - -- **Safe-output defaults**: Pre-configured limits for project operations -- **Execution phases**: Discover → Decide → Write → Report -- **Best practices**: Deterministic execution, pagination budgets, cursor management -- **Project integration**: Standard field mappings and status updates - -## Example: Dependabot Burner - -See the [Dependabot Burner](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/dependabot-burner.md) workflow for a complete example: - -- Discovers open Dependabot PRs -- Creates bundle issues for upgrades -- Tracks everything in a GitHub Project -- Runs daily with smart conditional execution - -## Best practices - -- **Use imports** - Include `shared/campaign.md` for standard orchestration -- **Define campaign ID** - Include a clear Campaign ID in your workflow -- **Specify project URL** - Document the GitHub Projects board URL -- **Test manually** - Use `workflow_dispatch` trigger to test before scheduling -- **Monitor progress** - Check your project board to see tracked items - -## Next Steps - -- [Campaign Orchestration](/gh-aw/guides/campaigns/) - Overview and patterns -- [Project Tracking Example](/gh-aw/examples/project-tracking/) - Complete configuration reference -- [Safe Outputs](/gh-aw/reference/safe-outputs/) - Available project operations -- [Trigger Events](/gh-aw/reference/triggers/) - Workflow trigger options diff --git a/docs/src/content/docs/guides/campaigns/index.mdx b/docs/src/content/docs/guides/campaigns/index.mdx index 662d4914f9..8e0d56b271 100644 --- a/docs/src/content/docs/guides/campaigns/index.mdx +++ b/docs/src/content/docs/guides/campaigns/index.mdx @@ -1,67 +1,105 @@ --- title: About Campaigns -description: Coordinate workflows to track progress in GitHub Projects using standard orchestration patterns. +description: Agent workflows that orchestrate work and track progress. sidebar: label: Campaigns banner: content: '⚠️ Experimental: This feature is under active development and may change or behave unpredictably.' --- +## Campaigns in one line + +**Campaigns coordinate multiple autonomous agents working toward a shared goal, with built-in progress tracking via GitHub Projects.** + ## What are Agentic Campaigns? Agentic Campaigns are workflows that coordinate autonomous agents across one or more repositories to drive progress toward a shared goal and make that progress easy to track. They run on a schedule and use: -- `imports` to include standard campaign orchestration from `shared/campaign.md` +- `imports` to include standard agent coordination rules from `shared/campaign.md` - `project` to optionally track work with automatic [GitHub Projects](/gh-aw/reference/glossary/#github-projects-projects-v2) integration ## Quick Start -Add `project` and `imports` to your workflow frontmatter: +**Prerequisites:** +- Repository with GitHub Agentic Workflows installed +- GitHub Actions enabled +- A GitHub Projects board (or create one during setup) + +**Create a campaign workflow:** + +1. **Create a new workflow file** at `.github/workflows/my-campaign.md`: ```yaml wrap --- -name: Dependabot Burner +name: My Campaign on: schedule: daily workflow_dispatch: +permissions: + issues: read + pull-requests: read + imports: - shared/campaign.md --- -# Dependabot Burner +# My Campaign - Project URL: https://github.com/orgs/myorg/projects/1 -- Campaign ID: dependabot-burner +- Campaign ID: my-campaign -Find all open Dependabot PRs and add them to the project. +Your campaign instructions here... ``` -The `imports: [shared/campaign.md]` includes standard campaign orchestration rules and safe-output defaults. +2. **Set up authentication** for project access: -## Campaign Orchestration Pattern +```bash +gh aw secrets set GH_AW_PROJECT_GITHUB_TOKEN --value "YOUR_PROJECT_TOKEN" +``` + +See [GitHub Projects V2 Tokens](/gh-aw/reference/tokens/#gh_aw_project_github_token-github-projects-v2) for token setup. + +3. **Compile and deploy**: + +```bash +gh aw compile +git add .github/workflows/my-campaign.md .github/workflows/my-campaign.lock.yml +git commit -m "Add my campaign workflow" +git push +``` + +The `imports: [shared/campaign.md]` includes standard agent coordination rules and safe-output defaults. + +## Agent Coordination Pattern The `shared/campaign.md` import provides: - **Safe-output defaults** - Pre-configured limits for project updates, issues, and status updates -- **Orchestration rules** - Best practices for discovery, deterministic execution, and reporting +- **Coordination rules** - Best practices for discovery, deterministic execution, and reporting - **Project integration** - Standard patterns for tracking work in GitHub Projects -## When to Use Campaigns +## When should this just be a workflow? -Use the campaign pattern when you need: +Use this decision table to determine if you need a campaign (agent coordination) or just a regular workflow: -- **Coordinated work** - Manage related tasks across multiple repositories -- **Progress visibility** - Track all work items in a central project board -- **Systematic execution** - Discover, process, and update work items on a schedule -- **Team coordination** - Share progress with stakeholders through project updates +| **Scenario** | **Use Campaign** | **Use Regular Workflow** | +|--------------|------------------|--------------------------| +| **Work spans multiple repos** | ✅ Yes - coordinate across repos | ❌ No - unless each repo is independent | +| **Need central progress tracking** | ✅ Yes - GitHub Projects integration | ❌ No - unless simple status updates suffice | +| **Coordinating multiple agents** | ✅ Yes - agent coordination pattern | ❌ No - single agent is simpler | +| **Systematic, recurring work** | ✅ Yes - scheduled discovery + updates | ⚠️ Maybe - simple schedules work too | +| **Team visibility required** | ✅ Yes - shared project board | ❌ No - notifications may be enough | +| **One-off automation task** | ❌ No - too much overhead | ✅ Yes - regular workflow is simpler | +| **Simple trigger → action** | ❌ No - over-engineered | ✅ Yes - regular workflow is cleaner | +| **No progress tracking needed** | ❌ No - unnecessary complexity | ✅ Yes - keep it simple | -**Don't need orchestration?** A simple workflow without `imports` is simpler if you just need basic project tracking. +**Rule of thumb:** If you're not tracking work items in a GitHub Project or coordinating multiple agents, you probably just need a regular workflow. -## Example: Dependabot Burner +## Example: Dependabot Burner (the smallest useful campaign) -The [Dependabot Burner workflow](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/dependabot-burner.md) demonstrates the campaign pattern: +The [Dependabot Burner workflow](https://github.com/githubnext/gh-aw/blob/main/.github/workflows/dependabot-burner.md) is **the smallest useful campaign** - it demonstrates the essential campaign pattern with minimal complexity: ```yaml --- @@ -90,13 +128,22 @@ imports: ``` Key features: -- **Imports orchestration** - Uses `shared/campaign.md` for standard rules +- **Imports coordination** - Uses `shared/campaign.md` for standard rules - **Scheduled execution** - Runs daily to process new Dependabot PRs - **Smart discovery** - Only runs if matching PRs exist (`skip-if-no-match`) - **Project tracking** - Adds discovered items to GitHub Projects board +## How it works + +The campaign workflow: + +1. Imports standard agent coordination rules from `shared/campaign.md` +2. Runs on schedule to discover work items +3. Processes items according to your instructions +4. Updates the GitHub Project board with progress +5. Reports status via project status updates + ## Next Steps -- [Getting Started](/gh-aw/guides/campaigns/getting-started/) - Create your first campaign - [Project Tracking Example](/gh-aw/examples/project-tracking/) - Complete guide with examples - [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Project operations documentation diff --git a/docs/src/content/docs/reference/glossary.md b/docs/src/content/docs/reference/glossary.md index 2b906fce7e..b86a401f06 100644 --- a/docs/src/content/docs/reference/glossary.md +++ b/docs/src/content/docs/reference/glossary.md @@ -38,7 +38,9 @@ An AI-powered workflow that can reason, make decisions, and take autonomous acti ### Agentic Campaign -An initiative that coordinates multiple agentic workflows toward a shared goal. +Workflows that coordinate one or more workers toward a shared goal, with built-in progress tracking. + +See the [Campaigns Guide](/gh-aw/guides/campaigns/) for implementation patterns. ### Agentic Engine or Coding Agent @@ -282,53 +284,6 @@ AI-powered GitHub Projects board management that automates issue triage, routing See the [ProjectOps Guide](/gh-aw/examples/issue-pr-events/projectops/) for implementation details. -### Agentic campaign - -An initiative that coordinates multiple agentic workflows toward a shared goal. Agentic campaigns can be enterprise-scale, with explicit ownership, approval gates, and executive visibility. - -:::caution[File format deprecated] -The `.campaign.md` file format is **deprecated**. Use the `project` field in workflow frontmatter for project tracking instead. See [Project Tracking](/gh-aw/reference/frontmatter/#project-tracking-project). -::: - -Campaigns previously used `.campaign.md` files where YAML frontmatter defined configuration (project URL, workflows, scope, governance) and the markdown body defined narrative context (objective, KPIs, timeline). The current approach uses the `project` field in regular workflow frontmatter: - -```yaml -# Current approach - workflow frontmatter with project field ---- -on: - schedule: - - cron: "0 0 * * *" -project: - url: https://github.com/orgs/myorg/projects/1 - workflows: - - framework-scanner - - framework-upgrader ---- - -# Framework Upgrade - -## Objective - -Upgrade all services to Framework vNext. - -## KPIs - -### Primary KPI: Services upgraded -- **Target**: 50 -``` - -**Key characteristics:** - -- Finite duration (days to months) with clear start and end -- Named owners and executive sponsors -- Formal approval gates and change control -- Budget tracking with ROI metrics -- Stateful execution using repo-memory for audit trails -- Cross-team and cross-repository coordination -- Executive dashboards and KPI reporting - -See the [Agentic campaigns Guide](/gh-aw/guides/campaigns/) for implementation patterns (note: guides describe deprecated format). - ### Command Triggers Special triggers that respond to slash commands in issue and PR comments (e.g., `/review`, `/deploy`). Configured using the `slash_command:` section with a command name. diff --git a/docs/src/content/docs/reference/safe-outputs.md b/docs/src/content/docs/reference/safe-outputs.md index 6fa82ffb00..b876d600a0 100644 --- a/docs/src/content/docs/reference/safe-outputs.md +++ b/docs/src/content/docs/reference/safe-outputs.md @@ -894,7 +894,7 @@ When using `target: "*"`, the agent must provide `discussion_number` in the outp ### Workflow Dispatch (`dispatch-workflow:`) -Triggers other workflows in the same repository using GitHub's `workflow_dispatch` event. This enables workflow orchestration and task delegation patterns, such as campaign workflows that coordinate multiple worker workflows. +Triggers other workflows in the same repository using GitHub's `workflow_dispatch` event. This enables agent orchestration patterns, such as campaign workflows that coordinate multiple worker workflows. **Shorthand Syntax:** ```yaml wrap diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md index df60e1cad9..b85ce59a5d 100644 --- a/docs/src/content/docs/setup/cli.md +++ b/docs/src/content/docs/setup/cli.md @@ -417,7 +417,7 @@ Manage campaign definitions. See [Agentic Campaigns Guide](/gh-aw/guides/campaig **Options:** `--json` -Alternative: create an issue with the `create-agentic-campaign` label to trigger automated campaign creation ([docs](/gh-aw/guides/campaigns/getting-started/)). +Alternative: create an issue with the `create-agentic-campaign` label to trigger automated campaign creation ([docs](/gh-aw/guides/campaigns/)). ### Management