From d1c7008b23758737fb7b650998c006c07348dc2a Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 12 Feb 2026 15:39:39 +0000
Subject: [PATCH 1/3] Initial plan


From f9d833e4d40db5213626054b60c2dbc636342116 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 12 Feb 2026 15:45:41 +0000
Subject: [PATCH 2/3] Document role requirements for audit/logs tools in
 agentic workflows

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 docs/src/content/docs/setup/mcp-server.md | 35 ++++++++++++++++++++++-
 1 file changed, 34 insertions(+), 1 deletion(-)

diff --git a/docs/src/content/docs/setup/mcp-server.md b/docs/src/content/docs/setup/mcp-server.md
index a5dc05bdc8..741e30a8dc 100644
--- a/docs/src/content/docs/setup/mcp-server.md
+++ b/docs/src/content/docs/setup/mcp-server.md
@@ -178,6 +178,10 @@ Compile Markdown workflows to GitHub Actions YAML with optional static analysis.
 
 Download and analyze workflow logs with timeout handling and size guardrails.
 
+> [!WARNING]
+> Role Requirement
+> This tool requires the workflow actor to have **write, maintain, or admin** repository role. Actors with read or triage access will receive a permission denied error.
+
 **Parameters:**
 - `workflow_name` (optional): Workflow name to download logs for (empty for all)
 - `count` (optional): Number of workflow runs to download (default: 100)
@@ -204,6 +208,10 @@ Download and analyze workflow logs with timeout handling and size guardrails.
 
 Investigate a workflow run, job, or specific step and generate a detailed report.
 
+> [!WARNING]
+> Role Requirement
+> This tool requires the workflow actor to have **write, maintain, or admin** repository role. Actors with read or triage access will receive a permission denied error.
+
 **Parameters:**
 - `run_id_or_url` (required): One of:
   - Numeric run ID: `1234567890`
@@ -328,6 +336,31 @@ Check workflow status, download logs, and audit failures.
 ```
 
 > [!CAUTION]
-> Required Permission
+> Required Permissions and Roles
+> 
+> **GitHub Actions Permission:**
 > The `agentic-workflows` tool requires `actions: read` permission to access GitHub Actions workflow logs and run data.
+> 
+> **Repository Role Requirements:**
+> The `logs` and `audit` tools require the workflow actor to have **write, maintain, or admin** role in the repository. These tools check the actor's repository permissions using the GitHub API before allowing access.
+> 
+> - **Minimum role:** write, maintain, or admin
+> - **Environment variable:** `GITHUB_ACTOR` must be set (automatically provided in GitHub Actions)
+> - **Permission check:** Runtime validation via GitHub API `/repos/{owner}/{repo}/collaborators/{username}/permission`
+> 
+> **Permission Denied Errors:**
+> 
+> If the actor has insufficient permissions (e.g., read or triage access), the tools will return:
+> ```json
+> {
+>   "error": "insufficient repository permissions",
+>   "actor": "username",
+>   "repository": "owner/repo",
+>   "role": "read",
+>   "required": "write, maintain, or admin",
+>   "reason": "Actor username has read access to owner/repo. This tool requires at least write access."
+> }
+> ```
+> 
+> **Other tools** (status, compile, mcp-inspect, add, update, fix) are available to all users regardless of repository role.
 

From b1c9f94613a01c524a439030911909d724486513 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 12 Feb 2026 15:47:33 +0000
Subject: [PATCH 3/3] Add role requirements to reference documentation for
 agentic-workflows tool

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 docs/src/content/docs/reference/permissions.md | 2 +-
 docs/src/content/docs/reference/tools.md       | 3 +++
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/docs/src/content/docs/reference/permissions.md b/docs/src/content/docs/reference/permissions.md
index bf1ab77a77..803786bd5f 100644
--- a/docs/src/content/docs/reference/permissions.md
+++ b/docs/src/content/docs/reference/permissions.md
@@ -172,7 +172,7 @@ Custom jobs and safe outputs jobs can have their own permission requirements bas
 
 Some tools require specific permissions to function:
 
-- **`agentic-workflows`**: Requires `actions: read` to access workflow logs and run data
+- **`agentic-workflows`**: Requires `actions: read` to access workflow logs and run data. Additionally, the `logs` and `audit` tools require the workflow actor to have **write, maintain, or admin** repository role.
 - **GitHub Model Context Protocol (MCP) toolsets**: See [Tools](/gh-aw/reference/tools/) for GitHub API permission requirements
 
 The compiler validates these requirements and provides clear error messages when permissions are missing.
diff --git a/docs/src/content/docs/reference/tools.md b/docs/src/content/docs/reference/tools.md
index 98d8d4dd13..a51eba18b7 100644
--- a/docs/src/content/docs/reference/tools.md
+++ b/docs/src/content/docs/reference/tools.md
@@ -196,6 +196,9 @@ tools:
   agentic-workflows:
 ```
 
+> [!NOTE]
+> The `logs` and `audit` tools require the workflow actor to have **write, maintain, or admin** repository role. Other tools (status, compile, mcp-inspect, add, update, fix) are available to all users.
+
 See [MCP Server](/gh-aw/setup/mcp-server/#using-as-agentic-workflows-tool) for available operations.
 
 ### Cache Memory (`cache-memory:`)