Improve and restructure campaigns documentation with separate Creating Campaigns page

[Copilot]

The campaigns documentation lacked a clear conceptual bridge from agentic workflows and had a disjointed structure that made it difficult for both new and experienced users to consume.

Changes

Content Improvements

• Opening definition: Changed first sentence to "GitHub agentic campaigns are..." and positioned campaigns as orchestration workflows that coordinate multiple agentic workflows
• Conceptual parallel: Drew explicit connection between workflows (natural language instructions + safe outputs → agent) and campaigns (specs + objectives → orchestrator agent)

Page Restructure

• Removed feature cards: The 2x2 FeatureGrid interrupted reading flow. Replaced with scannable bullet lists integrated into the narrative.
• Reorganized sections for natural decision flow:
  1. What are Agentic Campaigns? - Definition with workflow parallel
  2. When to Use Campaigns (NEW) - Clear decision criteria checklist
  3. How Campaigns Work (NEW) - Concise 4-step process with key concepts
  4. Next steps - Links to deeper documentation
• Created separate page: Moved "Creating Campaigns" content to a dedicated page (creating-campaigns.md) that appears as its own item in the left sidebar navigation

Campaign Creation Documentation

Created standalone Creating Campaigns page documenting all three creation methods in priority order:

• CLI Interactive wizard (Recommended): Use gh aw campaign new --interactive for guided campaign creation

  • Prompts for campaign objective and description
  • Repository scope and workflow discovery
  • Owners, stakeholders, and risk assessment
  • Project board creation
  • Easiest way to create well-configured campaigns with all required fields

• Custom agent via Copilot Chat (Alternative): Use /agent create campaign: <goal> in GitHub Copilot Chat

  • Opens Copilot Chat and describes campaign goal with /agent command
  • Agent analyzes goal, discovers workflows, generates Project board, spec, and PR
  • Links to Getting Started guide for detailed walkthrough

• CLI Manual mode (Advanced): For users who prefer direct control

  • gh aw campaign new <id> --project --owner <owner> command
  • Requires manual configuration of all fields
  • Links to CLI Commands reference

• Example: Security Alert Campaign: Shows complete flow from goal description to generated campaign spec

Sidebar Navigation Structure

The new sidebar structure provides better organization:

• About Campaigns (overview)
• Creating Campaigns (NEW - separate page)
• Getting Started (detailed tutorial)
• Campaign Specs (configuration)
• Campaign Lifecycle (execution)
• CLI Commands (command reference)

Accessibility Improvements

• First-time readers: "When to Use Campaigns" provides clear entry criteria before diving into details
• Experienced users: Can quickly scan the 4-step process and navigate directly to Creating Campaigns page
• Removed verbose explanatory paragraphs and inline glossary definitions that slowed reading momentum

Before:

[**Agentic campaigns**](/gh-aw/reference/glossary/#agentic-campaign) help you coordinate 
**[agentic workflows](/gh-aw/reference/glossary/#agentic-workflow)** toward a shared goal.

After:

**GitHub agentic campaigns** are AI-powered orchestration workflows that coordinate multiple 
**[agentic workflows](/gh-aw/reference/glossary/#agentic-workflow)** toward a shared goal 
across one or more repositories.

Just as [agentic workflows](/gh-aw/introduction/overview/) use natural language instructions 
to give an AI agent tasks and [safe outputs](/gh-aw/reference/safe-outputs/) to enable 
controlled GitHub operations, campaigns use **[campaign specs](/gh-aw/guides/campaigns/specs/)** 
to give an **orchestrator agent** high-level strategic instructions.

Screenshots

About Campaigns page (overview):

Creating Campaigns page (separate sidebar entry):

Original prompt

Improve Campaigns docs page. First sentence should be GitHub agentic campaigns are ... Also have a better narrative and draw/parallels with agentic workflows/build on knowledge from before (i.e. agentic workflows have safe outputs and give agent instructions, campaigns have specs and give orchestrator agent instructions).

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[mnkiefer]

@copilot Restructure page. Should the cards be kept or do they break the flow? Is the order of the topics/sections natural? The page should be easy to consume for someone that is seeing this material for the first time but also not bore a user that has more background on agentic workflows and wants to use campaigns.

[Copilot]

@copilot Restructure page. Should the cards be kept or do they break the flow? Is the order of the topics/sections natural? The page should be easy to consume for someone that is seeing this material ...

Restructured the page in commit 693d5aa:

Removed the cards - They interrupted reading flow. Replaced with scannable bullet lists.

New section order:

1. What are Agentic Campaigns? (definition)
2. When to Use Campaigns (decision criteria - new)
3. How Campaigns Work (4-step process - new)
4. From Natural Language to Campaign (example)
5. Next steps

Flow improvements:

• First-timers: Clear "when to use" checklist before diving into details
• Experienced users: Can skim the 4-step process, skip to the example
• Removed inline definitions that broke reading momentum
• Consolidated explanatory paragraphs into structured lists

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: /opt/hostedtoolcache/node/24.13.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build (dns block)
  • Triggering command: /opt/hostedtoolcache/node/24.13.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro preview (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[mnkiefer]

@copilot From natural language to campaign specs is now outdated. This how as the custom agent (campaign designer) or. the cli cmds. Rewrite accordingly and add a section "Creating campaigns" (for spec/designer walkthrough) and refer to section CLI commands for creating campaigns via CLI.

[Copilot]

@copilot From natural language to campaign specs is now outdated. This how as the custom agent (campaign designer) or. the cli cmds. Rewrite accordingly and add a section "Creating campaigns" (for spe...

Updated in commit 68b87f6:

Rewrote "Creating Campaigns" section (formerly "From Natural Language to Campaign"):

1. Issue-based creation (Recommended) - Documents the custom agent (campaign designer) workflow:

   • Create issue with campaign goal
   • Apply create-agentic-campaign label
   • Custom agent generates Project board, spec file, and PR
   • Links to Getting started

2. CLI-based creation (Advanced) - For manual control:

   • gh aw campaign new command with examples
   • Links to CLI commands

Example section now shows: "Issue description you provide" → "Generated campaign spec" flow

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: /opt/hostedtoolcache/node/24.13.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build (dns block)
  • Triggering command: /opt/hostedtoolcache/node/24.13.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro preview (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[mnkiefer]

@copilot Creating campaigns should already be a separate section in the left hand side toc.

[Copilot]

@copilot Creating campaigns should already be a separate section in the left hand side toc.

Done in commit e83da86:

Created separate page: /docs/src/content/docs/guides/campaigns/creating-campaigns.md

The "Creating Campaigns" content is now a standalone page that appears in the left sidebar navigation under the Campaigns section (between "About Campaigns" and "Getting Started").

New sidebar structure:

• About Campaigns
• Creating Campaigns ← NEW separate page
• Getting Started
• Campaign Specs
• Campaign Lifecycle
• CLI Commands

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: /opt/hostedtoolcache/node/24.13.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build (dns block)
  • Triggering command: /opt/hostedtoolcache/node/24.13.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro preview (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[mnkiefer]

@copilot Issues based creation no longer exists. We replaced this approach by CLI command or custom agent.

[Copilot]

@copilot Issues based creation no longer exists. We replaced this approach by CLI command or custom agent.

Fixed in commit 4965577:

Removed outdated issue-based creation (creating issue with create-agentic-campaign label)

Updated to current methods:

1. Recommended: Custom agent via Copilot Chat

   • Use /agent create campaign: <goal> in Copilot Chat
   • Agent generates Project board, spec, and PR

2. Advanced: CLI-based creation

   • Use gh aw campaign new my-campaign-id --project --owner @me

Updated both creating-campaigns.md and getting-started.md for consistency.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: /opt/hostedtoolcache/node/24.13.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[mnkiefer]

@copilot Also mention interactive cmd for campaign creation.

[Copilot]

@copilot Also mention interactive cmd for campaign creation.

Added in commit 63b9d89:

Interactive CLI wizard mode - gh aw campaign new --interactive

The page now documents three creation methods:

1. Recommended: Custom agent - /agent create campaign: <goal> in Copilot Chat
2. CLI Interactive wizard - gh aw campaign new --interactive with guided prompts for:
   • Campaign objective and description
   • Repository scope and workflow discovery
   • Owners, stakeholders, and risk assessment
   • Project board creation
3. CLI Manual mode - gh aw campaign new <id> --project --owner <owner> for direct control

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: /opt/hostedtoolcache/node/24.13.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[mnkiefer]

@copilot Make CLI Interactive wizard the recommended way.

[Copilot]

@copilot Make CLI Interactive wizard the recommended way.

Done in commit 16b242d:

CLI Interactive wizard is now the recommended method

The Creating Campaigns page now prioritizes:

1. Recommended: CLI Interactive wizard - gh aw campaign new --interactive
2. Alternative: Custom agent - /agent create campaign: <goal> via Copilot Chat
3. CLI Manual mode - gh aw campaign new <id> --project --owner <owner> for advanced users

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: /opt/hostedtoolcache/node/24.13.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)