Text of github.github.com › gh-aw › reference › audit as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Auditing Workflows | GitHub Agentic Workflows

Skip to main content Auditing Workflows The gh aw audit commands download workflow run artifacts and logs, analyze MCP tool usage and network behavior, and produce structured reports suited for security reviews, debugging, and feeding to AI agents. gh aw audit <run-id-or-url> [<run-id-or-url>...] Section titled “gh aw audit <run-id-or-url> [<run-id-or-url>...]” Audit one or more workflow runs. When a single run is provided, a detailed Markdown report is generated.

When two or more runs are provided, the first is used as the base (reference) run and the remaining runs are compared against it, producing a diff report. Add --group to aggregate findings instead of diffing runs. Arguments: each <run-id-or-url> accepts a numeric run ID, a standard or short run URL, a job URL, or a job URL with a step anchor (GitHub Enterprise URLs included). Additional arguments are compared against the first (diff mode).

In single-run mode, a job URL without a step anchor extracts the first failing step’s output; a step-anchored URL extracts that specific step. In diff mode, any job or step-specific URL is normalized to its parent run ID, so comparisons always happen at run scope. Self-comparisons and duplicate run IDs are rejected. Flags: Flag Default Description -o, --output <dir> ./logs Directory to write downloaded artifacts and report files --json off Output report as JSON to stdout --parse off Run JavaScript parsers on agent and firewall logs, writing log.md and firewall.md (single-run only) --repo <owner/repo> current repository Specify repository when the run ID is not from a URL --stdin off Read run IDs or URLs from stdin (one per line) instead of positional arguments --verbose off Print detailed progress information --format <fmt> pretty Diff output format: pretty or markdown (multi-run only) --group off Group audit findings so each [run, code] pair appears once with an occurrence count and representative entry --no-baseline off Skip baseline lookup and comparison for single-run audits; the Comparison section reports no baseline found --search <query> off Retrieve relevant unified-session evidence with local BM25 ranking (single-run only; incompatible with --group and job/step URLs) --search-limit <n> 5 Maximum evidence groups returned by --search , from 1 to 20 Top-level fields in --json output are stable; nested sub-fields may be extended but are not removed without deprecation.

Add --parse to populate behavior_fingerprint and agentic_assessments . By default a single-run audit renders a Comparison section against an earlier run of the same workflow. Use --no-baseline when that baseline is unrepresentative or to avoid the extra downloads. A --no-baseline result is never written to the audit cache, so it cannot suppress the Comparison section of a later default audit. Durable session continuation Section titled “Durable session continuation” For durable workflows, durable_session separates checkpoint restoration from observed native startup.

It reports status , started , engine, storage, available parent-run, artifact and native session IDs, and the unified-session evidence path. resumed requires matching restoration and native-start records from the audited run and attempt. restored without started confirms only restoration; restore_failed records a restoration error. Missing events, unsupported or invalid session files, and mismatched lineage report unavailable with a reason, never a successful continuation.

The info,usage artifact selection contains the required evidence. Cached audits re-read it, and health --logs-dir reuses the same raw session evidence for its current-revision sample. These records do not establish restored workspace edits, exactly-once effects, or agent task completion. Health exposes durable_sessions with resumed_runs , fresh_runs , restored_runs , restore_failed_runs , unavailable_runs , and per-run session reports.

Fresh runs count only observed native starts; restoration without a start is reported separately. Missing or budget-skipped cached evidence stays unavailable, including when every known-durable sample is unavailable. This is a cached evidence inventory, not a continuation rate, and does not change workflow health classifications or download artifacts. Retry history Section titled “Retry history” When unified-session retry evidence is available, --json includes a retries object. agent_retries and detection_retries count observed harness and startup retries separately for the main agent and threat detection. attempts retains harness and startup attempts, including interrupted attempts, with available IDs, timestamps, strategy, backoff, exit code, failure classes, and outcome.

Checkpoint and completion records for the same attempt are deduplicated. engine_retries and detection_engine_retries count native engine retries separately; engine_retry_history preserves their available metadata and source references. Native retries are associated with harness attempts only when the recorded evidence supports that association. Missing evidence does not prove that no retries occurred, and a missing exit code is not a successful exit.

Retry history does not change token accounting or classify ordinary continuations as retries. See the Unified Agent Session Specification for harness.attempt records and Harness Retry Policy for execution behavior. Invocation skip decisions Section titled “Invocation skip decisions” Invocation skip decisions appear in retries.decisions and as searchable harness.decision unified-session events. Each records the proposed attempt, question outcomes, sanitized errors, latency, and whether an invocation was avoided. retries.avoided_invocations counts denied invocations separately from executed attempts and retries; a skip does not count as an agent retry.

The Actions step summary shows a collapsible skip-if-decision section before the unified-session trace, including skipped invocation totals and a per-check table of outcomes, question counts, latency, and sanitized errors. It also appears when the initial invocation is skipped and no agent conversation exists. The section is omitted when no decision events were recorded and respects the existing summary byte limit. For example, this --json excerpt records a denied initial invocation.

Question 1 abstained because its referenced file could not be read, but question 2 was evaluated and denied, so no attempt executed: { "retries" : { "agent_retries" : 0 , "detection_retries" : 0 , "attempts" : [], "engine_retries" : 0 , "detection_engine_retries" : 0 , "decisions" : [ { "proposedAttempt" : 1 , "outcome" : " deny " , "questions" : [ { "question" : 1 , "outcome" : " unknown " , "error" : " file_reference_failed " }, { "question" : 2 , "outcome" : " deny " } ], "latencyMs" : 20 , "timestamp" : 1794096000000 , "avoidedInvocation" : true , "phase" : " agent " , "path" : " agent/harness_retry.json " , "index" : 1 } ], "avoided_invocations" : 1 } } Searching session evidence Section titled “Searching session evidence” Terminal window gh aw audit 1234567890 --search " api.example.com ERR_AUTH_401 " --json gh aw audit 1234567890 --search " github.issue_read timeout " --search-limit 3 --search adds an evidence_search section without replacing the full audit.

It indexes actual events from the downloaded, redacted usage/aw_session.jsonl (or root aw_session.jsonl ), not raw engine logs or synthesized run summaries. Narrowed --artifacts selections automatically include usage . Missing, malformed, unsupported, oversized, or symlinked unified-session inputs produce an error rather than a partial search presented as complete. Search accepts queries up to 1,024 bytes and sessions up to 64 MiB, 20,000 events, and 256 distinct stages.

Decoded data is bounded to 64 nesting levels. Ranking uses an in-memory BM25 index with no model calls, embeddings, external search service, or persistent index. Paths, tool names, domains, and error codes are indexed both as full

The rest of this page is on the live site.