From f53f528e77a9938ecd47dec77bbb61a5fac1e1fa Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 29 Apr 2026 06:24:43 +0000
Subject: [PATCH 1/3] Initial plan


From 799d466ecc1a473b088f0da5a07178c9908c7494 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 29 Apr 2026 06:30:03 +0000
Subject: [PATCH 2/3] docs: add workflow_run trigger examples for DevOps
 monitoring scenarios

Add a new "Creating Monitoring Workflows" section to .github/aw/create-agentic-workflow.md
placed after "Creating Command Workflows". The section includes:

- Intro explaining workflow_run for GitHub Actions-internal monitoring
- Clarification on deployment_status vs workflow_run distinction
- Key context variables table (conclusion, name, id, html_url, head_branch, commit message)
- Example 1: minimal CI failure notification (no pre-steps)
- Example 2: full DevOps monitoring with log fetching, root-cause analysis, and dedup
- Guidance for when to use workflow_run vs deployment_status
- Agent guidance for responding to DevOps monitoring requests

Closes #<issue>

Agent-Logs-Url: https://github.com/github/gh-aw/sessions/71971270-4764-4836-beee-b7c0d1e6e7bd

Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>
---
 .github/aw/create-agentic-workflow.md | 121 ++++++++++++++++++++++++++
 1 file changed, 121 insertions(+)

diff --git a/.github/aw/create-agentic-workflow.md b/.github/aw/create-agentic-workflow.md
index 4135fb00291..88d32ef1490 100644
--- a/.github/aw/create-agentic-workflow.md
+++ b/.github/aw/create-agentic-workflow.md
@@ -664,6 +664,127 @@ This gives users the choice of triggering via comment (`/deploy`) or via label,
 - `slash_command` full reference: https://github.github.com/gh-aw/reference/command-triggers/
 - `label_command` and LabelOps: https://github.github.com/gh-aw/patterns/label-ops/
 
+## Creating Monitoring Workflows
+
+Monitoring workflows react automatically to pipeline events. The primary trigger for **GitHub Actions-internal** monitoring is `workflow_run`. Use it when you want to detect failures in another workflow in the same repository and take action — for example, posting a comment, opening an issue, or sending a notification. This is the recommended pattern for **DevOps monitoring** scenarios such as CI/CD failure detection.
+
+> **`deployment_status` vs `workflow_run`**: Use `deployment_status` for **external deployment services** (Heroku, Vercel, Railway, Fly.io, etc.) that post status back to GitHub via the Deployments API. Use `workflow_run` for **GitHub Actions-internal** pipelines. See `@.github/aw/deployment-status.md` for the `deployment_status` pattern.
+
+### workflow_run: React to CI/CD pipeline results
+
+`workflow_run` fires whenever a named workflow completes (or starts). Pair it with an `if:` condition on `github.event.workflow_run.conclusion` to act only on failures.
+
+**Key context variables available in the prompt:**
+
+| Expression | Description |
+|---|---|
+| `${{ github.event.workflow_run.conclusion }}` | Final result: `success`, `failure`, `cancelled`, `skipped`, `timed_out` |
+| `${{ github.event.workflow_run.name }}` | Name of the workflow that ran |
+| `${{ github.event.workflow_run.id }}` | Run ID (use with `gh run view`) |
+| `${{ github.event.workflow_run.html_url }}` | Direct link to the run |
+| `${{ github.event.workflow_run.head_branch }}` | Branch the run was triggered on |
+| `${{ github.event.workflow_run.head_commit.message }}` | Commit message of the triggering commit |
+
+**Example 1 — Notify on CI failure (minimal, no pre-steps):**
+
+This is the simplest monitoring workflow. It activates whenever the "CI" workflow completes with a failure and posts a comment on the triggering PR.
+
+```aw wrap
+---
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+if: ${{ github.event.workflow_run.conclusion == 'failure' }}
+permissions:
+  contents: read
+tools:
+  github:
+    toolsets: [default]
+safe-outputs:
+  add-comment:
+    max: 1
+---
+
+The CI workflow failed for branch `${{ github.event.workflow_run.head_branch }}`.
+
+Run details:
+- **Run ID**: ${{ github.event.workflow_run.id }}
+- **Conclusion**: ${{ github.event.workflow_run.conclusion }}
+- **Link**: ${{ github.event.workflow_run.html_url }}
+
+Use the GitHub MCP tools to find the open pull request for branch `${{ github.event.workflow_run.head_branch }}`. Post a concise comment on that PR summarising the failure and suggesting next steps for the author.
+```
+
+**Example 2 — Fetch CI logs, diagnose root cause, and notify (with pre-steps):**
+
+This pattern fetches the workflow logs before the agent runs, keeping the agent focused on analysis rather than API calls. Suitable for DevOps teams that need actionable failure summaries with root-cause analysis.
+
+```aw wrap
+---
+on:
+  workflow_run:
+    workflows: ["CI", "Deploy"]
+    types: [completed]
+if: ${{ github.event.workflow_run.conclusion == 'failure' }}
+permissions:
+  contents: read
+  actions: read        # required to download workflow run logs
+tools:
+  github:
+    toolsets: [default]
+  cache-memory: true   # deduplication: skip already-diagnosed run IDs
+steps:
+  - name: Fetch failed run logs
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      RUN_ID: ${{ github.event.workflow_run.id }}
+    run: |
+      mkdir -p /tmp/gh-aw/agent
+      gh run view "$RUN_ID" --log-failed > /tmp/gh-aw/agent/ci-logs.txt 2>&1 || true
+      tail -500 /tmp/gh-aw/agent/ci-logs.txt > /tmp/gh-aw/agent/ci-logs-trimmed.txt
+safe-outputs:
+  add-comment:
+    max: 1
+---
+
+The `${{ github.event.workflow_run.name }}` workflow failed on branch `${{ github.event.workflow_run.head_branch }}`.
+
+**Run details:**
+- Run ID: ${{ github.event.workflow_run.id }}
+- Link: ${{ github.event.workflow_run.html_url }}
+- Commit: ${{ github.event.workflow_run.head_commit.message }}
+
+**Instructions:**
+
+1. Check `/tmp/gh-aw/cache-memory/seen-runs.json`. If `${{ github.event.workflow_run.id }}` is already listed, stop — this run was already processed.
+
+2. Read `/tmp/gh-aw/agent/ci-logs-trimmed.txt` and identify the root cause of the failure.
+
+3. Use GitHub MCP tools to find the open pull request for branch `${{ github.event.workflow_run.head_branch }}`.
+
+4. Post a comment on that PR with:
+   - A one-sentence summary of what failed
+   - The likely root cause
+   - Suggested next steps for the author
+   - A link to the failed run: ${{ github.event.workflow_run.html_url }}
+
+5. Append `${{ github.event.workflow_run.id }}` to `/tmp/gh-aw/cache-memory/seen-runs.json` so this run is not re-processed on retries.
+```
+
+**When to use `workflow_run` for monitoring:**
+
+- ✅ Monitoring GitHub Actions CI pipelines (test, lint, build workflows)
+- ✅ Monitoring deploy workflows that run inside GitHub Actions
+- ✅ Alerting on `timed_out` or `cancelled` runs in addition to `failure`
+- ✅ Creating issues or posting comments automatically on pipeline failure
+- ⚠️ Only works for workflows in the **same repository**
+- ❌ Not suitable for external deployment services — use `deployment_status` instead
+
+**Guiding the user when they ask for DevOps monitoring:**
+
+When a user asks for "notify me when my pipeline fails", "alert on CI failures", "deployment failure notification", or similar — default to this `workflow_run` pattern. Ask which workflow(s) to monitor (the `workflows:` list) and whether they want log-based root-cause analysis (Example 2) or a lightweight notification (Example 1).
+
 ## Best Practices
 
 ### Improver Coding Agents in Large Repositories

From 59dc8064c075ebd46a4527844b13852037280910 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 29 Apr 2026 06:31:01 +0000
Subject: [PATCH 3/3] docs: address review feedback on workflow_run examples
 section

Agent-Logs-Url: https://github.com/github/gh-aw/sessions/71971270-4764-4836-beee-b7c0d1e6e7bd

Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>
---
 .github/aw/create-agentic-workflow.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/aw/create-agentic-workflow.md b/.github/aw/create-agentic-workflow.md
index 88d32ef1490..e5e7bc7324f 100644
--- a/.github/aw/create-agentic-workflow.md
+++ b/.github/aw/create-agentic-workflow.md
@@ -668,7 +668,7 @@ This gives users the choice of triggering via comment (`/deploy`) or via label,
 
 Monitoring workflows react automatically to pipeline events. The primary trigger for **GitHub Actions-internal** monitoring is `workflow_run`. Use it when you want to detect failures in another workflow in the same repository and take action — for example, posting a comment, opening an issue, or sending a notification. This is the recommended pattern for **DevOps monitoring** scenarios such as CI/CD failure detection.
 
-> **`deployment_status` vs `workflow_run`**: Use `deployment_status` for **external deployment services** (Heroku, Vercel, Railway, Fly.io, etc.) that post status back to GitHub via the Deployments API. Use `workflow_run` for **GitHub Actions-internal** pipelines. See `@.github/aw/deployment-status.md` for the `deployment_status` pattern.
+> **`deployment_status` vs `workflow_run`**: Use `deployment_status` for **external deployment services** (Heroku, Vercel, Railway, Fly.io, etc.) that post status back to GitHub via the Deployments API. Use `workflow_run` for **GitHub Actions-internal** pipelines. See reference: @.github/aw/deployment-status.md for the `deployment_status` pattern.
 
 ### workflow_run: React to CI/CD pipeline results
 
@@ -757,7 +757,7 @@ The `${{ github.event.workflow_run.name }}` workflow failed on branch `${{ githu
 
 **Instructions:**
 
-1. Check `/tmp/gh-aw/cache-memory/seen-runs.json`. If `${{ github.event.workflow_run.id }}` is already listed, stop — this run was already processed.
+1. Check `/tmp/gh-aw/cache-memory/seen-runs.json` (a JSON array of run ID strings, e.g. `["12345","67890"]`). If `${{ github.event.workflow_run.id }}` is already listed, stop — this run was already processed.
 
 2. Read `/tmp/gh-aw/agent/ci-logs-trimmed.txt` and identify the root cause of the failure.