diff --git a/docs/src/content/docs/guides/campaigns/getting-started.mdx b/docs/src/content/docs/guides/campaigns/getting-started.mdx new file mode 100644 index 0000000000..a4b926b4dd --- /dev/null +++ b/docs/src/content/docs/guides/campaigns/getting-started.mdx @@ -0,0 +1,117 @@ +--- +title: Getting Started with Campaigns +description: Quick start guide and examples for creating your first agentic campaign. +sidebar: + label: Getting Started +banner: + content: '⚠️ Experimental: This feature is under active development and may change or behave unpredictably.' +--- + +## Quick Start + +**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 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. + +## Example: Dependabot Burner (the smallest useful campaign) + +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 +--- +name: Dependabot Burner +on: + schedule: daily + skip-if-no-match: 'is:pr is:open author:app/dependabot' + workflow_dispatch: + +permissions: + issues: read + pull-requests: read + +imports: + - shared/campaign.md +--- + +# Dependabot Burner + +- Project URL: https://github.com/orgs/githubnext/projects/144 +- Campaign ID: dependabot-burner + +- Find all open Dependabot PRs and add them to the project. +- Create bundle issues for each runtime + manifest file. +- Add bundle issues to the project and assign to Copilot. +``` + +Key features: +- **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 + +## More Examples + +For a complete campaign workflow example, see: +- [Security Scanner Campaign](/gh-aw/examples/campaigns/security-scanner/) - Demonstrates vulnerability scanning with safe-output limits + +## 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 + +- [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/guides/campaigns/index.mdx b/docs/src/content/docs/guides/campaigns/index.mdx index 8e0d56b271..3d74de21a1 100644 --- a/docs/src/content/docs/guides/campaigns/index.mdx +++ b/docs/src/content/docs/guides/campaigns/index.mdx @@ -7,72 +7,19 @@ 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 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 - -**Prerequisites:** -- Repository with GitHub Agentic Workflows installed -- GitHub Actions enabled -- A GitHub Projects board (or create one during setup) +Agentic Campaigns are workflows that coordinate work across one or more repositories to drive progress toward a shared goal and make that progress easy to track. -**Create a campaign workflow:** +They run on a schedule and include: +- **Natural language coordination** with defaults being imported from `shared/campaign.md` +- **Progress tracking** with optional automatic [GitHub Projects](/gh-aw/reference/glossary/#github-projects-projects-v2) -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 ---- +## Getting Started -# My Campaign +To create your first campaign workflow with step-by-step instructions, see the [Getting Started guide](/gh-aw/guides/campaigns/getting-started/). -- 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 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 +## How it works The `shared/campaign.md` import provides: @@ -82,68 +29,4 @@ The `shared/campaign.md` import provides: ## When should this just be a workflow? -Use this decision table to determine if you need a campaign (agent coordination) or just a regular workflow: - -| **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 | - **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 (the smallest useful campaign) - -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 ---- -name: Dependabot Burner -on: - schedule: daily - skip-if-no-match: 'is:pr is:open author:app/dependabot' - workflow_dispatch: - -permissions: - issues: read - pull-requests: read - -imports: - - shared/campaign.md ---- - -# Dependabot Burner - -- Project URL: https://github.com/orgs/githubnext/projects/144 -- Campaign ID: dependabot-burner - -- Find all open Dependabot PRs and add them to the project. -- Create bundle issues for each runtime + manifest file. -- Add bundle issues to the project and assign to Copilot. -``` - -Key features: -- **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 - -- [Project Tracking Example](/gh-aw/examples/project-tracking/) - Complete guide with examples -- [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Project operations documentation