diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index fd09641c61..71abeddf71 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -184,7 +184,6 @@ export default defineConfig({ { label: 'SideRepoOps', link: '/patterns/siderepoops/' }, { label: 'SpecOps', link: '/patterns/specops/' }, { label: 'TrialOps', link: '/patterns/trialops/' }, - { label: 'Monitoring', link: '/patterns/monitoring/' }, { label: 'Orchestration', link: '/patterns/orchestration/' }, ], }, diff --git a/docs/src/content/docs/examples/project-tracking.md b/docs/src/content/docs/examples/project-tracking.md index c073a10408..a91eaf3c7e 100644 --- a/docs/src/content/docs/examples/project-tracking.md +++ b/docs/src/content/docs/examples/project-tracking.md @@ -227,11 +227,11 @@ Use for progress reports, milestone summaries, or workflow health indicators. ## How this fits -- **Projects & Monitoring:** Use `update-project` to track work items and `create-project-status-update` to publish run summaries. +- **ProjectOps:** Use `update-project` to track work items and `create-project-status-update` to publish run summaries. - **Orchestration:** An orchestrator can dispatch workers and use the same project safe-outputs to keep a shared board updated. See: -- [Projects & Monitoring](/gh-aw/patterns/monitoring/) +- [ProjectOps](/gh-aw/patterns/projectops/) - [Orchestration](/gh-aw/patterns/orchestration/) ## Common Patterns @@ -324,5 +324,5 @@ 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 -- [Projects & Monitoring](/gh-aw/patterns/monitoring/) - Design pattern guide +- [ProjectOps](/gh-aw/patterns/projectops/) - Design pattern guide - [Orchestration](/gh-aw/patterns/orchestration/) - Design pattern guide diff --git a/docs/src/content/docs/patterns/monitoring.md b/docs/src/content/docs/patterns/monitoring.md deleted file mode 100644 index 6b122d9d03..0000000000 --- a/docs/src/content/docs/patterns/monitoring.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: Projects & Monitoring -description: Use GitHub Projects + safe-outputs to track and monitor workflow work items and progress. ---- - -Use this pattern when you want a durable “source of truth” for what your agentic workflows discovered, decided, and did. - -## What this pattern is - -- **Projects** are the dashboard: a GitHub Projects v2 board holds issues/PRs and custom fields. -- **Monitoring** is the behavior: workflows continuously add/update items, and periodically post status updates. - -## Building blocks - -### 1) Track items with `update-project` - -Enable the safe output and point it at your project URL: - -```yaml -safe-outputs: - update-project: - project: https://github.com/orgs/myorg/projects/123 - max: 10 - github-token: ${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }} -``` - -- Adds issues/PRs to the board and updates custom fields. -- Can also create views and custom fields when configured. - -See the full reference: [/reference/safe-outputs/#project-board-updates-update-project](/gh-aw/reference/safe-outputs/#project-board-updates-update-project) - -### 2) Post run summaries with `create-project-status-update` - -Use project status updates to communicate progress and next steps: - -```yaml -safe-outputs: - create-project-status-update: - project: https://github.com/orgs/myorg/projects/123 - max: 1 - github-token: ${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }} -``` - -This is useful for scheduled workflows (daily/weekly) or orchestrator workflows. - -See the full reference: [/reference/safe-outputs/#project-status-updates-create-project-status-update](/gh-aw/reference/safe-outputs/#project-status-updates-create-project-status-update) - -### 3) Correlate work with a Tracker Id field - -If you want to correlate multiple runs, add a custom field like **Tracker Id** (text) and populate it from your workflow prompt/output (for example, a run ID, issue number, or “initiative” key). - -## Operational monitoring - -- Use `gh aw status` to see which workflows are enabled and their latest run state. -- Use `gh aw logs` and `gh aw audit` to inspect tool usage, errors, MCP failures, and network patterns. - -See: [/setup/cli/](/gh-aw/setup/cli/) diff --git a/docs/src/content/docs/patterns/orchestration.md b/docs/src/content/docs/patterns/orchestration.md index 1c92b857e1..33a79046fd 100644 --- a/docs/src/content/docs/patterns/orchestration.md +++ b/docs/src/content/docs/patterns/orchestration.md @@ -37,4 +37,4 @@ If your workers need shared context, pass an explicit input such as `tracker_id` - Set conservative `max` limits on dispatch to prevent accidental fan-out. - Prefer Projects + status updates for **monitoring** over ad-hoc labels. -See also: [/patterns/monitoring/](/gh-aw/patterns/monitoring/) +See also: [/patterns/projectops/](/gh-aw/patterns/projectops/) diff --git a/docs/src/content/docs/patterns/projectops.md b/docs/src/content/docs/patterns/projectops.md index c1378c731a..96cc7db945 100644 --- a/docs/src/content/docs/patterns/projectops.md +++ b/docs/src/content/docs/patterns/projectops.md @@ -1,6 +1,6 @@ --- title: ProjectOps -description: Automate GitHub Projects board management with AI-powered workflows (triage, routing, and field updates) +description: Automate GitHub Projects board management with AI-powered workflows (triage, routing, field updates, and monitoring) sidebar: badge: { text: 'Event-triggered', variant: 'success' } --- @@ -11,6 +11,15 @@ When a new issue or pull request arrives, the agent analyzes it and determines w Safe outputs handle all project operations in separate, scoped jobs with minimal permissions—the agent job never sees the Projects token, ensuring secure automation. +## Pattern Overview + +ProjectOps combines two complementary aspects: + +- **Projects** are the dashboard: a GitHub Projects v2 board holds issues/PRs and custom fields +- **Monitoring** is the behavior: workflows continuously add/update items, and periodically post status updates + +Use this pattern when you want a durable "source of truth" for what your agentic workflows discovered, decided, and did. + ## Prerequisites 1. **Create a Project**: Before you wire up a workflow, you must first create the Project in the GitHub UI (user or organization level). Keep the Project URL handy (you'll need to reference it in your workflow instructions). @@ -120,6 +129,30 @@ Each safe output operates in a separate job with minimal, scoped permissions. Se See the [Safe Outputs reference](/gh-aw/reference/safe-outputs/#project-board-updates-update-project) for project field and view configuration. +## Monitoring and Tracking + +ProjectOps workflows can serve as a monitoring system by maintaining a project board that tracks workflow activity and progress. + +### Correlate work with Tracker ID + +To correlate multiple workflow runs or coordinate across workflows, add a custom **Tracker Id** field (text type) to your project board and populate it from your workflow prompt or output. This enables: + +- Linking related issues/PRs across multiple workflow runs +- Tracking progress of multi-step initiatives +- Coordinating work between orchestrator and worker workflows + +**Example**: Use a run ID, issue number, or initiative key as the tracker ID to group related work items. + +### Operational Monitoring with CLI Tools + +Monitor your ProjectOps workflows and diagnose issues using the gh-aw CLI: + +- `gh aw status` - See which workflows are enabled and their latest run state +- `gh aw logs` - Download and analyze workflow logs for debugging +- `gh aw audit` - Inspect tool usage, errors, MCP failures, and network patterns + +See the [CLI Commands reference](/gh-aw/setup/cli/) for complete details. + ## When to Use ProjectOps ProjectOps complements [GitHub's built-in Projects automation](https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/using-the-built-in-automations) with AI-powered intelligence: @@ -165,8 +198,7 @@ ProjectOps complements [GitHub's built-in Projects automation](https://docs.gith ## Additional Resources - [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Complete safe output configuration and API details -- [Projects & Monitoring](/gh-aw/patterns/monitoring/) - Design pattern guide -- [Orchestration](/gh-aw/patterns/orchestration/) - Design pattern guide +- [Orchestration](/gh-aw/patterns/orchestration/) - Design pattern guide for coordinating multiple workflows - [Trigger Events](/gh-aw/reference/triggers/) - Event trigger configuration options - [IssueOps](/gh-aw/patterns/issueops/) - Related issue automation patterns - [Token Reference](/gh-aw/reference/tokens/#gh_aw_project_github_token-github-projects-v2) - GitHub Projects token setup diff --git a/docs/src/content/docs/reference/safe-outputs.md b/docs/src/content/docs/reference/safe-outputs.md index 0c9f62dffc..9d986beaba 100644 --- a/docs/src/content/docs/reference/safe-outputs.md +++ b/docs/src/content/docs/reference/safe-outputs.md @@ -451,7 +451,7 @@ Optionally include `item_url` (GitHub issue URL) to add the issue as the first p > - **Fine-grained PAT**: Organization permissions → Projects: Read & Write > [!NOTE] -> You can configure views directly during project creation using the `views` field (see above), or later using `update-project` to add custom fields and additional views. For pattern guidance, see [Projects & Monitoring](/gh-aw/patterns/monitoring/). +> You can configure views directly during project creation using the `views` field (see above), or later using `update-project` to add custom fields and additional views. For pattern guidance, see [ProjectOps](/gh-aw/patterns/projectops/). ### Project Board Updates (`update-project:`) @@ -1350,7 +1350,7 @@ Common combinations: - **Orchestration:** `dispatch-workflow` (orchestrator/worker pattern), optionally paired with Projects updates See: -- [Projects & Monitoring](/gh-aw/patterns/monitoring/) +- [ProjectOps](/gh-aw/patterns/projectops/) - [Orchestration](/gh-aw/patterns/orchestration/) ## Custom Messages (`messages:`)