Skip to content

Restructure Agentic campaigns docs into subsections #7007

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mnkiefer merged 2 commits into from
Dec 19, 2025
Merged

Restructure Agentic campaigns docs into subsections #7007

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2c1635f
Initial plan
Copilot Dec 19, 2025
b6252ae
Restructure Agentic campaigns documentation with subsections
Copilot Dec 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion docs/astro.config.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,13 @@ export default defineConfig({
},
{
label: 'Agentic campaigns',
link: '/guides/campaigns/',
items: [
{ label: 'Overview', link: '/guides/campaigns/' },
{ label: 'Campaign Specs', link: '/guides/campaigns/specs/' },
{ label: 'Getting Started', link: '/guides/campaigns/getting-started/' },
{ label: 'Project Management', link: '/guides/campaigns/project-management/' },
{ label: 'CLI Commands', link: '/guides/campaigns/cli-commands/' },
],
},
{
label: 'Guides',
Expand Down
294 changes: 6 additions & 288 deletions docs/src/content/docs/guides/campaigns.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ If you are deciding whether you need an agentic campaign, start here.

Use an agentic campaign when you need to run a finite initiative and you want it to be easy to review, operate, and report on.

Example: “Upgrade a dependency across 50 repositories over two weeks, with an approval gate, daily progress updates, and a final summary.”
Example: "Upgrade a dependency across 50 repositories over two weeks, with an approval gate, daily progress updates, and a final summary."

| If you care about… | Use… |
|---|---|
Expand Down Expand Up @@ -100,294 +100,12 @@ The orchestrator/worker pattern enforces these principles:

These principles ensure workers can be reused across agentic campaigns and remain simple, while orchestrators handle all coordination complexity.

## Next Steps

Next: how gh-aw represents that “initiative layer” as a file you can review and version.

## Agentic campaign spec files

In this repository, agentic campaigns are defined as Markdown files under `.github/workflows/` with a `.campaign.md` suffix. Each file has a YAML frontmatter block describing the agentic campaign.

```yaml
# .github/workflows/framework-upgrade.campaign.md
id: framework-upgrade
version: "v1"
name: "Framework Upgrade"
description: "Move services to Framework vNext"

project-url: "https://github.com/orgs/ORG/projects/1"

workflows:
- framework-upgrade

tracker-label: "campaign:framework-upgrade"
state: "active"
owners:
- "platform-team"
```

Common fields you’ll reach for as the initiative grows:

- `project-url`: the GitHub Project URL used as the primary campaign dashboard
- `tracker-label`: the label that ties issues/PRs back to the agentic campaign
- `memory-paths` / `metrics-glob`: where baselines and metrics snapshots live on your repo-memory branch
- `approval-policy`: the expectations for human approval (required approvals/roles)

Once you have a spec, the remaining question is consistency: what should every agentic campaign produce so people can follow along?

## Recommended default wiring

To keep agentic campaigns consistent and easy to read, most teams use a predictable set of primitives:

- **Tracker label** (for example, `campaign:<id>`) applied to every issue/PR in the agentic campaign.
- **Epic issue** (often also labeled `campaign-tracker`) as the human-readable command center.
- **GitHub Project** as the dashboard (primary campaign dashboard).
- **Repo-memory metrics** (daily JSON snapshots) to compute velocity/ETAs and enable trend reporting.
- **Tracker IDs in worker workflows** (e.g., `tracker-id: "worker-name"`) to enable orchestrator discovery of worker-created assets.
- **Monitor/orchestrator** to aggregate and post periodic updates.
- **Custom date fields** (optional, for roadmap views) like `Start Date` and `End Date` to visualize campaign timeline.

If you want to try this end-to-end quickly, start with the minimal steps below.

## Quick start

1. Create an agentic campaign spec: `.github/workflows/<id>.campaign.md`.
2. Reference one or more workflows in `workflows:`.
3. Set `project-url` to the org Project v2 URL you use as the agentic campaign dashboard.
4. Add a `tracker-label` so issues/PRs can be queried consistently.
5. Run `gh aw compile` to validate campaign specs and compile workflows.

## Lowest-friction walkthrough (recommended)

The simplest, least-permissions way to run an agentic campaign is:

1. **Create the agentic campaign spec (in a PR)**
- **Option A (No-code)**: Use the "🚀 start an agentic campaign" issue form in the GitHub UI to capture intent with structured fields. The form creates an agentic campaign issue, and an agent can scaffold the spec file for you.
- **Option B (CLI)**: Use `gh aw campaign new <id>` to generate an agentic campaign spec file locally.
- **Option C (Manual)**: Author `.github/workflows/<id>.campaign.md` manually.

2. **Create the org Project board once (manual)**
- Create an org Project v2 in the GitHub UI and copy its URL into `project-url`.
- This avoids requiring a PAT or GitHub App setup just to provision boards.
- Minimum clicks (one-time setup):
- In GitHub: your org 0 **Projects** 0 **New project**.
- Give it a name (for example: `Code Health: <Campaign Name>`).
- Choose any starting layout (Table/Board). You can change views later.
- Copy the Project URL and set it as `project-url` in the agentic campaign spec.
- Optional but recommended for “kanban lanes”:
- Create a **Board** view and set **Group by** to a single-select field (commonly `Status`).
- Note: workflows can create/update fields and single-select options, but they do not currently create or configure Project views.

3. **Have workflows keep the board in sync using `GITHUB_TOKEN`**
- Enable the `update-project` safe output in the launcher/monitor workflows.
- Default behavior is **update-only**: if the board does not exist, the project job fails with instructions.

4. **Opt in to auto-creating the board only when you intend to**
- If you want workflows to create missing boards, explicitly set `create_if_missing: true` in the `update_project` output.
- For many orgs, you may also need a token override (`safe-outputs.update-project.github-token`) with sufficient org Project permissions.

When the spec has meaningful details (tracker label, workflows, memory paths, or a metrics glob), `gh aw compile` will also generate an orchestrator workflow named `.github/workflows/<id>.campaign.g.md` and compile it to a corresponding `.lock.yml`.

See [Agentic campaign specs and orchestrators](/gh-aw/setup/cli/#compile) for details.

## Using Project Roadmap Views with Custom Date Fields

GitHub Projects offers a [Roadmap view](https://docs.github.com/en/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/customizing-the-roadmap-layout) that visualizes work items along a timeline. To use this view with campaigns, you need to add custom date fields to track when work items start and end.

### Setting Up Custom Date Fields

**One-time manual setup** (in the GitHub Projects UI):

1. Open your campaign's Project board
2. Click the **+** button in the header row to add a new field
3. Create a **Date** field named `Start Date`
4. Create another **Date** field named `End Date`
5. Create a **Roadmap** view from the view dropdown
6. Configure the roadmap to use your date fields

Once these fields exist, orchestrator workflows can automatically populate them when adding or updating project items.

### Automatic Timestamp Population

**NEW**: Starting in this release, `update-project` automatically populates date fields from issue and pull request timestamps:

- **Start Date** is automatically set from `createdAt` (when the issue/PR was created)
- **End Date** is automatically set from `closedAt` (when the issue/PR was closed, if applicable)

This happens automatically for campaign project boards and requires no additional configuration. The system will:

1. Query the issue or PR to fetch `createdAt` and `closedAt` timestamps
2. Convert timestamps to ISO date format (YYYY-MM-DD)
3. Populate `Start Date` and `End Date` fields if they exist in the project and aren't already set
4. Respect any manually provided date values in the `fields` parameter

**Example:** When adding issue #123 (created on 2025-12-15, closed on 2025-12-18) to a project board with "Start Date" and "End Date" fields:

```yaml
update-project:
project: "https://github.com/orgs/myorg/projects/42"
content_number: 123
content_type: "issue"
# No fields specified - dates will be auto-populated!
```

Result:
- `Start Date` → `2025-12-15` (from createdAt)
- `End Date` → `2025-12-18` (from closedAt)

**Override automatic timestamps:** You can still explicitly set date values if needed:

```yaml
update-project:
project: "https://github.com/orgs/myorg/projects/42"
content_number: 123
content_type: "issue"
fields:
start_date: "2025-12-10" # Overrides automatic timestamp
end_date: "2025-12-20" # Overrides automatic timestamp
```

### Orchestrator Configuration for Date Fields

To have orchestrators set date fields automatically, modify the orchestrator's instructions or use the `fields` parameter in `update-project` outputs.

**Example workflow instruction:**

```markdown
When adding issues to the project board, set these custom fields:
- `Start Date`: Set to the issue's creation date
- `End Date`: Set to estimated completion date based on issue size and priority
- Small issues: 3 days from start
- Medium issues: 1 week from start
- Large issues: 2 weeks from start
```

**Example agent output for update-project:**

```yaml
update-project:
project: "https://github.com/orgs/myorg/projects/42"
item_url: "https://github.com/myorg/myrepo/issues/123"
fields:
status: "In Progress"
priority: "High"
start_date: "2025-12-19"
end_date: "2025-12-26"
```

### Best Practices for Campaign Date Fields

**Recommended field names:**
- `Start Date` or `start_date` - When work begins
- `End Date` or `end_date` - Expected or actual completion date
- `Target Date` - Optional milestone or deadline

**Date assignment strategies:**

- **For new issues**: Set `start_date` to current date, calculate `end_date` based on estimated effort
- **For in-progress work**: Keep original `start_date`, adjust `end_date` if needed
- **For completed work**: Update `end_date` to actual completion date

**Roadmap view benefits:**

- **Visual timeline**: See all campaign work laid out chronologically
- **Dependency identification**: Spot overlapping or sequential work items
- **Capacity planning**: Identify periods with too much concurrent work
- **Progress tracking**: Compare planned vs actual completion dates

### Example: Campaign with Roadmap Tracking

```yaml
# .github/workflows/migration-q1.campaign.md
id: migration-q1
name: "Q1 Migration Campaign"
project-url: "https://github.com/orgs/myorg/projects/15"
workflows:
- migration-worker
tracker-label: "campaign:migration-q1"
```

The orchestrator can set date fields when adding issues:

```markdown
## Campaign Orchestrator

When adding discovered issues to the project board:

1. Query issues with tracker-id: "migration-worker"
2. For each issue:
- Add to project board
- Set `status` to "Todo" (or "Done" if closed)
- Set `start_date` to the issue creation date
- Set `end_date` based on labels:
- `size:small` → 3 days from start
- `size:medium` → 1 week from start
- `size:large` → 2 weeks from start
- Set `priority` based on issue labels

Generate a report showing timeline distribution of all work items.
```

### Limitations and Considerations

- **Manual field creation**: Workflows cannot create custom fields; they must exist before workflows can update them
- **Field name matching**: Custom field names are case-sensitive; use exact names as defined in the project
- **Date format**: Use ISO 8601 format (YYYY-MM-DD) for date values
- **No automatic recalculation**: Date fields don't auto-update; orchestrators must explicitly update them
- **View configuration**: Roadmap views must be configured manually in the GitHub UI

## Try it with the CLI

From the root of the repo:

```bash
gh aw campaign
gh aw campaign status
gh aw campaign new my-campaign-id
gh aw campaign validate
```

For non-failing validation (useful in CI while you iterate):

```bash
gh aw campaign validate --no-strict
```

## Start an Agentic Campaign with GitHub Issue Forms

For a low-code/no-code approach, you can create an agentic campaign using the GitHub UI with the "🚀 Start an Agentic Campaign" issue form:

1. **Go to the repository's Issues tab** and click "New issue"
2. **Select "🚀 Start an Agentic Campaign"** from the available templates
3. **Fill in the structured form fields**:
- **Campaign Name** (required): Human-readable name (e.g., "Framework Upgrade Q1 2025")
- **Campaign Identifier** (required): Unique ID using lowercase letters, digits, and hyphens (e.g., "framework-upgrade-q1-2025")
- **Campaign Version** (required): Version string (defaults to "v1")
- **Project Board URL** (required): URL of the GitHub Project you created to serve as the agentic campaign dashboard
- **Campaign Type** (optional): Select from Migration, Upgrade/Modernization, Security Remediation, etc.
- **Scope** (optional): Define what repositories, components, or areas will be affected
- **Constraints** (optional): List any constraints or requirements (deadlines, approvals, etc.)
- **Prior Learnings** (optional): Share relevant learnings from past similar campaigns
4. **Submit the form** to create the agentic campaign issue

### What happens after submission

When you submit the issue form:

1. **an agentic campaign issue is created** - This becomes your campaign's central hub with the `campaign` and `campaign-tracker` labels
2. **An agent validates your project board** - Ensures the URL is accessible and properly configured
3. **an agentic campaign spec is generated** - Creates `.github/workflows/<id>.campaign.md` with your inputs as a PR
4. **The spec is linked to the issue** - So you can track the technical implementation
5. **Your project board is configured** - The agent sets up tracking labels and fields

You manage the agentic campaign from the issue. The generated workflow files are implementation details and should not be edited directly.

### Benefits of the issue form approach

- **Captures intent, not YAML**: Focus on what you want to accomplish, not technical syntax
- **Structured validation**: Form fields ensure required information is provided
- **Lower barrier to entry**: No need to understand campaign spec file format
- **Traceable**: Issue serves as the agentic campaign's command center with full history
- **Agent-assisted scaffolding**: Automated generation of spec files and workflows
- **[Campaign Specs](/gh-aw/guides/campaigns/specs/)** - Learn about spec files and configuration
- **[Getting Started](/gh-aw/guides/campaigns/getting-started/)** - Quick start guide and walkthrough
- **[Project Management](/gh-aw/guides/campaigns/project-management/)** - Using GitHub Projects with roadmap views
- **[CLI Commands](/gh-aw/guides/campaigns/cli-commands/)** - Command reference for campaign management

## Related Patterns

Expand Down
Loading