From 33caf2a112f033b9bb2fdd1902017e9b34bd15e1 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 25 Mar 2026 01:29:05 +0000 Subject: [PATCH 1/2] Initial plan From 5a9e5e205970364b0d87a3beec17604c0c473c78 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 25 Mar 2026 01:40:15 +0000 Subject: [PATCH 2/2] Add notes about actions: read permission and setup-cli requirement for gh aw logs/audit workflow steps Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> Agent-Logs-Url: https://github.com/github/gh-aw/sessions/f48ba19b-7de5-48ed-8f28-38de57b51ea9 --- .github/aw/debug-agentic-workflow.md | 20 ++++++++++++++++++++ .github/aw/github-agentic-workflows.md | 20 ++++++++++++++++++++ .github/aw/runbooks/workflow-health.md | 2 ++ 3 files changed, 42 insertions(+) diff --git a/.github/aw/debug-agentic-workflow.md b/.github/aw/debug-agentic-workflow.md index 26a36a95b72..b0293ed6c52 100644 --- a/.github/aw/debug-agentic-workflow.md +++ b/.github/aw/debug-agentic-workflow.md @@ -64,6 +64,26 @@ Report back with specific findings and actionable fixes. - `gh aw audit --json` → investigate a specific run with JSON output - `gh aw status` → show status of agentic workflows in the repository +> [!IMPORTANT] +> **When using `gh aw logs` or `gh aw audit` as steps inside a generated workflow** (not from a local machine): +> +> 1. Add `actions: read` to the workflow `permissions:` block — these commands need read access to GitHub Actions run data. +> 2. Install the `gh-aw` extension **before** the step that calls `gh aw`, using the `setup-cli` action: +> +> ```yaml +> permissions: +> actions: read +> steps: +> - name: Install gh-aw +> uses: github/gh-aw/actions/setup-cli@ +> with: +> version: +> - name: Download logs +> run: gh aw logs ... +> ``` +> +> Steps that call `gh aw` placed **before** the `setup-cli` install step will fail with `unknown command "aw" for "gh"`. + > [!NOTE] > **Alternative: agentic-workflows Tool** > diff --git a/.github/aw/github-agentic-workflows.md b/.github/aw/github-agentic-workflows.md index 820ae378394..791c04f3b96 100644 --- a/.github/aw/github-agentic-workflows.md +++ b/.github/aw/github-agentic-workflows.md @@ -2144,6 +2144,26 @@ This example demonstrates using the agentic-workflows tool to analyze workflow e Monitor workflow execution and costs using the `logs` command: +**⚠️ IMPORTANT**: When using `gh aw logs` or `gh aw audit` as steps inside a generated workflow (not from a local machine), the workflow **must**: + +1. Include `actions: read` in the `permissions:` block — these commands read GitHub Actions run data. +2. Call the `setup-cli` action **before** any step that uses `gh aw` — the extension is not available by default on runners. + +```yaml +permissions: + actions: read + +steps: + - name: Install gh-aw + uses: github/gh-aw/actions/setup-cli@ + with: + version: + - name: Download logs + run: gh aw logs ... +``` + +Steps that call `gh aw` placed **before** the `setup-cli` install step will fail with `unknown command "aw" for "gh"`. + ```bash # Download logs for all agentic workflows gh aw logs diff --git a/.github/aw/runbooks/workflow-health.md b/.github/aw/runbooks/workflow-health.md index 269b1781149..2ca9c2ba096 100644 --- a/.github/aw/runbooks/workflow-health.md +++ b/.github/aw/runbooks/workflow-health.md @@ -54,6 +54,8 @@ Use this runbook when: Use the `gh aw logs` command to download and analyze workflow logs: +> **Note**: The commands below are meant to be run from a local machine or a Copilot coding agent session. If you include `gh aw logs` or `gh aw audit` as steps inside a generated workflow, you must add `actions: read` to `permissions:` and install the extension with the `setup-cli` action before calling these commands — see [Logs and Metrics](../github-agentic-workflows.md#logs-and-metrics) for details. + ```bash # Download logs from last 24 hours gh aw logs --start-date -1d -o /tmp/workflow-logs