From 1944cf248e1aba7eaae1eee626c8000966805b97 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 30 Apr 2026 04:10:06 +0000 Subject: [PATCH] docs: unbloat examples/project-tracking.md Remove redundant bullets, configuration table, thin "How this fits" section, verbose per-pattern descriptions, and replace three Symptoms/ Solutions subsections with a compact troubleshooting table. Also trim two duplicate section-specific See Also links. Co-Authored-By: Claude Sonnet 4.6 --- .../content/docs/examples/project-tracking.md | 66 ++----------------- 1 file changed, 7 insertions(+), 59 deletions(-) diff --git a/docs/src/content/docs/examples/project-tracking.md b/docs/src/content/docs/examples/project-tracking.md index c270345f7a2..117ad810e86 100644 --- a/docs/src/content/docs/examples/project-tracking.md +++ b/docs/src/content/docs/examples/project-tracking.md @@ -5,7 +5,7 @@ sidebar: badge: { text: 'Project', variant: 'tip' } --- -The `update-project` and `create-project-status-update` safe-output tools enable automatic tracking of workflow-created items in GitHub Projects boards. Configure these tools in the `safe-outputs` section of your workflow frontmatter to enable project management capabilities including item addition, field updates, and status reporting. +Use `update-project` and `create-project-status-update` safe-outputs to automatically track workflow items in GitHub Projects boards, with support for field updates and status reporting. ## Quick Start @@ -28,10 +28,6 @@ safe-outputs: --- ``` -This enables: -- **update-project** - Add items to projects, update fields (status, priority, etc.) -- **create-project-status-update** - Post status updates to project boards - ## Configuration ### Update Project Configuration @@ -56,7 +52,7 @@ Supported operations: `add` (add items), `update` (update fields), `create_field ### Project Status Update Configuration -Configure `create-project-status-update` to post status updates — useful for progress reports, milestone summaries, and workflow health indicators: +Configure `create-project-status-update` to post project status updates: ```yaml safe-outputs: @@ -66,13 +62,6 @@ safe-outputs: github-token: ${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }} ``` -| Field | Type | Default | Description | -|-------|------|---------|-------------| -| `project` | string | (required) | GitHub Project URL for update-project or create-project-status-update | -| `max` | integer | 10 | Maximum operations per run (update-project) or 1 (create-project-status-update) | -| `github-token` | string | `GITHUB_TOKEN` | Custom token with Projects permissions | -| `views` | array | - | Optional auto-created views for update-project (with name, layout, filter) | - See [Safe Outputs: Project Board Updates](/gh-aw/reference/safe-outputs/#project-board-updates-update-project) for complete configuration details. ### Authentication @@ -160,21 +149,10 @@ When a pull request is opened or reviews are requested: - Default → "Low" ``` -## How this fits - -- **Projects & Monitoring:** 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/) -- [Orchestration](/gh-aw/patterns/orchestration/) - ## Common Patterns ### Progressive Status Updates -Move items through workflow stages: - ```aw Analyze the issue and determine its current state: - If new and unreviewed → status="Needs Triage" @@ -187,8 +165,6 @@ Update the project item with the appropriate status. ### Priority Assignment -Set priority based on content analysis: - ```aw Examine the issue for urgency indicators: - Contains "critical", "urgent", "blocker" → priority="High" @@ -200,8 +176,6 @@ Update the project item with the assigned priority. ### Field-Based Routing -Use custom fields for workflow routing: - ```aw Determine the team that should handle this issue: - Security-related → team="Security" @@ -214,41 +188,15 @@ Update the project item with the team field. ## Troubleshooting -### Items Not Added to Project - -**Symptoms**: Workflow runs successfully but items don't appear in project board - -**Solutions**: -- Verify project URL is correct (check browser address bar) -- Confirm token has Projects: Read & Write permissions -- Check that organization allows Projects access for the token -- Review workflow logs for safe_outputs job errors - -### Permission Errors - -**Symptoms**: Workflow fails with "Resource not accessible" or "Insufficient permissions" - -**Solutions**: -- For organization projects: Use fine-grained PAT with organization Projects permission -- For user projects: Use classic PAT with `project` scope -- Ensure token is stored in correct secret name -- Verify repository settings allow Actions to access secrets - -### Token Not Resolved - -**Symptoms**: Workflow fails with "invalid token" or token appears as literal string - -**Solutions**: -- Use GitHub expression syntax: `${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }}` -- Don't quote the expression in YAML -- Ensure secret name matches exactly (case-sensitive) -- Check secret is set at repository or organization level +| Issue | Symptom | Solution | +|-------|---------|----------| +| Items not added | Items don't appear despite a successful run | Verify project URL, confirm token has Projects: Read & Write permission, review `safe_outputs` job logs | +| Permission errors | "Resource not accessible" or "Insufficient permissions" | Use fine-grained PAT with org Projects permission, or classic PAT with `project` scope; verify secret name and repository settings | +| Token not resolved | "invalid token" or literal `${{...}}` string in output | Use `${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }}` syntax without quotes; check secret name is exact (case-sensitive) | ## See Also - [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Complete safe-outputs documentation -- [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 - [Project token authentication](/gh-aw/patterns/project-ops/#project-token-authentication) - Token setup guide - [Projects & Monitoring](/gh-aw/patterns/monitoring/) - Design pattern guide - [Orchestration](/gh-aw/patterns/orchestration/) - Design pattern guide