docs: enhance existing pages with audit cross-references and glossary entries by Copilot · Pull Request #24453 · github/gh-aw

Copilot · 2026-04-04T06:50:43Z

Several documentation pages lacked cross-references to the audit feature, reducing discoverability for users arriving via related topics (network, MCP, cost, monitoring, debugging).

Glossary (`reference/glossary.md`)

Added Audit (gh aw audit) — single-run analysis command
Added Behavior Fingerprint — multi-dimensional run characterization (network, tools, tokens, assessments)
Added Firewall Analysis — per-run breakdown of allowed/blocked domains with policy attribution
Updated Audit Diff and Cross-Run Audit Report — link to /reference/audit/ instead of the generic CLI reference; expanded descriptions to cover MCP and metrics dimensions

Monitoring (`patterns/monitoring.md`)

Replaced the 3-bullet operational monitoring list with a proper section: audit commands, code examples, and a tip on automating trend monitoring with gh aw logs --format markdown

Network (`reference/network.md`)

Added gh aw audit and gh aw audit diff to the Troubleshooting section for inspecting and comparing firewall behavior per run
Added [Audit Commands] to Related Documentation

MCP Gateway (`reference/mcp-gateway.md`)

Added a tip block after §8.2 (Health Check Behavior) pointing to gh aw audit for runtime MCP server health inspection and audit diff for regression detection
Added [gh-aw-audit] to Informative References

Debugging (`troubleshooting/debugging.md`)

Expanded the audit section: behavior fingerprint, per-server MCP health, and token/cost metrics now appear in the output description
Cross-run examples use gh aw logs --format for trend analysis

Cost Management (`reference/cost-management.md`)

Added a paragraph in the Monitoring Costs section directing users to gh aw audit for single-run cost deep-dives and gh aw logs --format markdown for cross-run trends

Agent-Logs-Url: https://github.com/github/gh-aw/sessions/3fc36686-b218-400c-92b7-61c9a808d60f Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

pelikhan

@copilot gh aw audit report is removed. Use gh aw logs instead

…kdown Agent-Logs-Url: https://github.com/github/gh-aw/sessions/1963eb3c-8c61-43d8-8a58-55ccfdc71795 Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot · 2026-04-04T07:09:40Z

@copilot gh aw audit report is removed. Use gh aw logs instead

Fixed in 4c0a871 — replaced gh aw audit report with gh aw logs --format markdown in the monitoring.md tip.

Copilot

Pull request overview

Enhances documentation discoverability for the gh aw audit feature by adding cross-references, expanding troubleshooting/monitoring guidance, and introducing related glossary entries.

Changes:

Added/expanded audit-related guidance in debugging, network troubleshooting, MCP gateway references, monitoring patterns, and cost management.
Introduced new glossary entries (Audit, Behavior Fingerprint, Firewall Analysis) and updated existing audit-related glossary definitions/links.
Replaced/updated multi-run “trend” guidance to emphasize gh aw logs --format markdown.

Show a summary per file

File	Description
docs/src/content/docs/troubleshooting/debugging.md	Expands `gh aw audit` output description and updates cross-run guidance to `gh aw logs --format`.
docs/src/content/docs/reference/network.md	Adds troubleshooting guidance for using `gh aw audit` / `gh aw audit diff` for firewall behavior.
docs/src/content/docs/reference/mcp-gateway.md	Adds an audit tip for MCP health inspection and adds an informative reference link to audit docs.
docs/src/content/docs/reference/glossary.md	Adds new audit-related glossary entries and updates audit-related links/descriptions.
docs/src/content/docs/reference/cost-management.md	Adds a cost-focused pointer to `gh aw audit` for single-run deep dives and `gh aw logs --format` for trends.
docs/src/content/docs/patterns/monitoring.md	Reworks operational monitoring into an audit-centric section with commands, examples, and automation tip.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files reviewed: 6/6 changed files
Comments generated: 2

Copilot · 2026-04-04T07:14:06Z

docs/src/content/docs/reference/glossary.md

 ### Cross-Run Audit Report (`gh aw logs --format`)

-A feature of `gh aw logs` that aggregates firewall data across multiple workflow runs to produce a cross-run security report. The report includes an executive summary, domain inventory, and per-run breakdown. Designed for security reviews, compliance checks, and feeding debugging or optimization agents. Outputs markdown by default (suitable for `$GITHUB_STEP_SUMMARY`), or pretty/JSON format. See [CLI Reference](/gh-aw/setup/cli/#logs).
+A feature of `gh aw logs` that aggregates firewall, MCP, and metrics data across multiple workflow runs to produce a security and performance report. Includes an executive summary, domain inventory, and per-run breakdown with anomaly detection. Designed for security reviews, compliance checks, and feeding optimization agents. See [Audit Commands](/gh-aw/reference/audit/#gh-aw-logs-format-fmt).


The glossary link to the gh aw logs --format <fmt> section likely uses the wrong autogenerated heading anchor. In reference/audit.md the heading text includes --format, which typically slugifies to an anchor with extra hyphens (e.g., gh-aw-logs---format-fmt), so /gh-aw/reference/audit/#gh-aw-logs-format-fmt may 404. Consider either linking to /gh-aw/reference/audit/ without an anchor or updating the anchor to match the generated slug (or adding an explicit heading ID in reference/audit.md and linking to that).

Suggested change

A feature of `gh aw logs` that aggregates firewall, MCP, and metrics data across multiple workflow runs to produce a security and performance report. Includes an executive summary, domain inventory, and per-run breakdown with anomaly detection. Designed for security reviews, compliance checks, and feeding optimization agents. See [Audit Commands](/gh-aw/reference/audit/#gh-aw-logs-format-fmt).

A feature of `gh aw logs` that aggregates firewall, MCP, and metrics data across multiple workflow runs to produce a security and performance report. Includes an executive summary, domain inventory, and per-run breakdown with anomaly detection. Designed for security reviews, compliance checks, and feeding optimization agents. See [Audit Commands](/gh-aw/reference/audit/).

Copilot · 2026-04-04T07:14:06Z

docs/src/content/docs/reference/mcp-gateway.md

 5. Update readiness based on critical server status

+> [!TIP]
+> To inspect MCP server health for a specific workflow run at runtime, use `gh aw audit <run-id>`. The **MCP Server Health** section of the audit report shows connection failures, timeout errors, tool call counts, and error rates per server — providing a post-run view of gateway behavior. For recurring MCP failures, `gh aw audit diff` compares MCP tool usage between two runs to identify regressions. See [Audit Commands](/gh-aw/reference/audit/).


This TIP says you can inspect MCP server health "at runtime" via gh aw audit <run-id>, but gh aw audit is a post-run analysis command (it downloads artifacts/logs from a completed run). Rewording to avoid implying live/runtime introspection would prevent confusion (e.g., "for a specific workflow run" / "after the run completes").

Suggested change

> To inspect MCP server health for a specific workflow run at runtime, use `gh aw audit <run-id>`. The **MCP Server Health** section of the audit report shows connection failures, timeout errors, tool call counts, and error rates per server — providing a post-run view of gateway behavior. For recurring MCP failures, `gh aw audit diff` compares MCP tool usage between two runs to identify regressions. See [Audit Commands](/gh-aw/reference/audit/).

> To inspect MCP server health for a specific workflow run after the run completes, use `gh aw audit <run-id>`. The **MCP Server Health** section of the audit report shows connection failures, timeout errors, tool call counts, and error rates per server — providing a post-run view of gateway behavior. For recurring MCP failures, `gh aw audit diff` compares MCP tool usage between two runs to identify regressions. See [Audit Commands](/gh-aw/reference/audit/).

Initial plan

5bf4180

Copilot AI assigned Copilot and pelikhan Apr 4, 2026

Copilot AI linked an issue Apr 4, 2026 that may be closed by this pull request

docs: enhance existing pages with audit cross-references and glossary entries #23959

Closed

Copilot started work on behalf of pelikhan April 4, 2026 06:50 View session

docs: enhance pages with audit cross-references and glossary entries

eeb047a

Agent-Logs-Url: https://github.com/github/gh-aw/sessions/3fc36686-b218-400c-92b7-61c9a808d60f Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Enhance existing pages with audit cross-references and glossary entries~~ docs: enhance existing pages with audit cross-references and glossary entries Apr 4, 2026

Copilot AI requested a review from pelikhan April 4, 2026 07:02

Copilot finished work on behalf of pelikhan April 4, 2026 07:02

pelikhan reviewed Apr 4, 2026

View reviewed changes

Copilot started work on behalf of pelikhan April 4, 2026 07:05 View session

docs: replace removed gh aw audit report with gh aw logs --format mar…

4c0a871

…kdown Agent-Logs-Url: https://github.com/github/gh-aw/sessions/1963eb3c-8c61-43d8-8a58-55ccfdc71795 Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot AI requested a review from pelikhan April 4, 2026 07:10

Copilot finished work on behalf of pelikhan April 4, 2026 07:10

pelikhan marked this pull request as ready for review April 4, 2026 07:10

Copilot AI review requested due to automatic review settings April 4, 2026 07:10

pelikhan merged commit 88d063e into main Apr 4, 2026
3 checks passed

pelikhan deleted the copilot/add-audit-glossary-entries branch April 4, 2026 07:11

Copilot started reviewing on behalf of pelikhan April 4, 2026 07:11 View session

Copilot AI reviewed Apr 4, 2026

View reviewed changes

github-actions bot mentioned this pull request Apr 4, 2026

Smoke Test: Copilot - 23979248713 #24485

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: enhance existing pages with audit cross-references and glossary entries#24453

docs: enhance existing pages with audit cross-references and glossary entries#24453
pelikhan merged 3 commits intomainfrom
copilot/add-audit-glossary-entries

Copilot AI commented Apr 4, 2026 •

edited

Loading

Uh oh!

pelikhan left a comment

Uh oh!

Copilot AI commented Apr 4, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Copilot AI Apr 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	A feature of `gh aw logs` that aggregates firewall, MCP, and metrics data across multiple workflow runs to produce a security and performance report. Includes an executive summary, domain inventory, and per-run breakdown with anomaly detection. Designed for security reviews, compliance checks, and feeding optimization agents. See [Audit Commands](/gh-aw/reference/audit/#gh-aw-logs-format-fmt).
	A feature of `gh aw logs` that aggregates firewall, MCP, and metrics data across multiple workflow runs to produce a security and performance report. Includes an executive summary, domain inventory, and per-run breakdown with anomaly detection. Designed for security reviews, compliance checks, and feeding optimization agents. See [Audit Commands](/gh-aw/reference/audit/).

Conversation

Copilot AI commented Apr 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Glossary (reference/glossary.md)

Monitoring (patterns/monitoring.md)

Network (reference/network.md)

MCP Gateway (reference/mcp-gateway.md)

Debugging (troubleshooting/debugging.md)

Cost Management (reference/cost-management.md)

Uh oh!

pelikhan left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Apr 4, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Apr 4, 2026 •

edited

Loading

Glossary (`reference/glossary.md`)

Monitoring (`patterns/monitoring.md`)

Network (`reference/network.md`)

MCP Gateway (`reference/mcp-gateway.md`)

Debugging (`troubleshooting/debugging.md`)

Cost Management (`reference/cost-management.md`)