GitHub Agentic Workflows upload several artifacts during workflow execution. This reference documents every artifact name, its contents, and how to access the data — especially for downstream workflows that use gh run download directly instead of gh aw logs.

Caution

Deprecated

The gh aw logs and gh aw audit commands support --artifacts to download only specific artifact groups:

# Download only firewall artifacts
gh aw logs <run-id> --artifacts firewall

# Download agent and firewall artifacts
gh aw logs <run-id> --artifacts agent --artifacts firewall

# Download everything (default)
gh aw logs <run-id>

The firewall-audit-logs artifact is uploaded by all firewall-enabled workflows. It contains AWF (Agent Workflow Firewall) structured audit and observability logs.

! Important: This artifact is separate from the agent artifact. Token usage data (token-usage.jsonl) lives here, not in the agent artifact.

firewall-audit-logs/
├── api-proxy-logs/
│   ├── token-usage.jsonl        ← Token usage data (input/output/cache tokens per API request)
│   └── token-diag.log           ← Token diagnostics JSONL (only when AWF_DEBUG_TOKENS=1)
├── squid-logs/
│   └── access.log               ← Network policy log (domain allow/deny decisions)
├── audit.jsonl                  ← Firewall audit trail (policy matches, rule evaluations)
└── policy-manifest.json         ← Policy configuration snapshot

token-diag.log is written by the AWF api-proxy diag() path (containers/api-proxy/token-persistence.js) to $AWF_TOKEN_LOG_DIR/token-diag.log (default /var/log/api-proxy/token-diag.log). It is only emitted when AWF_DEBUG_TOKENS=1, so set that environment variable on the workflow step that runs with AWF enabled when you need token diagnostics.

Recommended: Use gh aw logs

# Download and analyze firewall data
gh aw logs <run-id> --artifacts firewall

# Output as JSON for scripting
gh aw logs <run-id> --artifacts firewall --json

Direct download with gh run download:

# Download the firewall-audit-logs artifact
gh run download <run-id> -n firewall-audit-logs

# Token usage data is at:
cat firewall-audit-logs/api-proxy-logs/token-usage.jsonl

# Network access log is at:
cat firewall-audit-logs/squid-logs/access.log

# Audit trail is at:
cat firewall-audit-logs/audit.jsonl

# Policy manifest is at:
cat firewall-audit-logs/policy-manifest.json

Downstream workflows sometimes download agent-artifacts or agent expecting to find token-usage.jsonl. This will silently return no data — the token usage file is only in the firewall-audit-logs artifact.

# ✗ WRONG — token-usage.jsonl is NOT in the agent artifact
gh run download <run-id> -n agent
cat agent/token-usage.jsonl  # File not found!

# ✓ CORRECT — download from firewall-audit-logs
gh run download <run-id> -n firewall-audit-logs
cat firewall-audit-logs/api-proxy-logs/token-usage.jsonl

The JSONL files in this artifact are described by versioned JSON Schemas published by github/gh-aw-firewall. Each record includes a _schema field (for example "audit/v0.26.0") so consumers can identify the record type and AWF version.

Use releases/latest/download/ in place of a specific tag to track the most recent published release. Schemas are versioned by AWF release tag; consumers should match _schema by prefix (for example _schema.startsWith("audit/")) so additive changes remain non-breaking.

The unified agent artifact contains agent job outputs:

• Agent execution logs
• Safe output data (agent_output.json)
• GitHub API rate limit logs (github_rate_limits.jsonl)
• Token usage summary (agent_usage.json) — aggregated totals only; per-request data is in firewall-audit-logs
• otel.jsonl — OTLP span mirror written by gh-aw’s JavaScript span exporters when observability.otlp is configured

For OTLP configuration, runtime environment variables, and span semantics, see the OpenTelemetry guide.

The activation artifact contains activation job outputs:

• aw_info.json — Engine configuration and workflow metadata
• prompt.txt — The generated prompt sent to the AI agent
• github_rate_limits.jsonl — Rate limit data from the activation job

The detection artifact is conditional:

• Inline engine (default): detection.log, the threat-detection analysis output. Legacy name: threat-detection.log.
• External gh-aw-detection engine (the default, or features.gh-aw-detection: true): detection_result.json and step-summary.md.

Caution

The experiment artifact is uploaded by the activation job only when the workflow frontmatter declares one or more experiments entries. It contains:

• state.json — Cumulative per-variant invocation counters used to balance A/B assignments across runs

# Download the experiment artifact for a specific run
gh aw audit <run-id> --artifacts experiment

# Display the A/B experiment section in the audit report
gh aw audit <run-id>

The A/B Experiments section of the audit report shows the variant chosen for the run and the cumulative counts:

 A/B Experiments
  • style = concise (cumulative: concise:5, detailed:4)

See A/B Experiments for how to declare experiments in workflow frontmatter.

The usage artifact is a compact conclusion-job artifact with workflow-run metadata and token-usage files for lightweight reporting and forecasting, so downstream tools can read aggregated usage data without downloading the full agent artifact.

Its activity/summary.json file uses the usage-activity-summary/v1 schema. The optional activity sections are additive; the working_set section is always written when the calculation step executes:

{
  "working_set": {
    "measurement_state": "measured",
    "rebuild_factor": 3.9017857142857144,
    "cumulative_input_tokens": 874000,
    "peak_input_tokens": 224000,
    "rebuild_excess_tokens": 650000,
    "invocations": 5
  }
}

rebuild_factor is cumulative_input_tokens / peak_input_tokens, where each invocation contributes the canonical input_tokens value from the agent token_usage.jsonl record. Cache-read and cache-write fields are not added because provider normalization has already produced that logical input count. The factor is omitted when measurement_state is unavailable; partial means usable records were measured but malformed or unsupported records were ignored.

Working-Set Rebuild Factor measures cumulative context reconstruction relative to peak invocation context. It is an efficiency/trajectory metric, not a measurement of semantic coherence debt and not a predictor of task success. It cannot identify missing task facts or classify outcome quality. The metric is conceptually inspired by “The Working Set of a Coding Agent: Coherence Debt in Repository-Scale Tasks”, while deliberately limiting the implementation to observable token traffic.

# Download only the usage artifact
gh aw logs <run-id> --artifacts usage

# Or with gh run download
gh run download <run-id> -n usage

The evals artifact is uploaded by the evals job only when the workflow frontmatter declares one or more evals entries. It is not present on runs without evals and contains:

• evals.jsonl — Per-question BinEval evaluation results (YES/NO records) produced by running the declared evaluation questions against the agent output

# Download only the evals artifact
gh aw logs <run-id> --artifacts evals

# Or with gh run download
gh run download <run-id> -n evals

The gh aw audit command exposes an --evals flag that skips runs without evals results and automatically downloads the evals artifact when --artifacts is narrowed:

# Audit only runs that contain evals results
gh aw audit <run-id> --evals

When the workflow frontmatter declares one or more graders, the grader files are stored inside existing artifacts rather than uploaded as a standalone graders artifact. They live under agent/graders/ in the unified agent artifact, under graders/ in the agent-output-fallback artifact when the fallback transport is used, and under usage/graders/ after the conclusion job mirrors them for lightweight downloads. The files are:

• grader_manifest.json — The configured graders with their unit, direction, and threshold
• grader_results.json — The normalized grader results (status, value, pass/fail) computed from the run trace

# Download the artifacts that carry grader results
gh aw logs <run-id> --artifacts graders

# Or with gh run download against the actual artifacts
gh run download <run-id> -n usage
gh run download <run-id> -n agent
gh run download <run-id> -n agent-output-fallback

gh aw audit reports grader outcomes in its console output and includes them in the JSON report under the graders key (results, plus total, passed, failed, error_count, and unavailable_count). Use gh aw graders operational-value <run-id> to replay the archived operational-value evaluator at an explicit evidence cutoff.

Artifact names changed between upload-artifact v4 and v5. The gh aw logs and gh aw audit commands handle both naming schemes transparently:

Single-file artifacts are automatically flattened to root level regardless of their artifact directory name. Multi-file artifacts (firewall-audit-logs, agent, activation, experiment, and detection when the external gh-aw-detection engine is enabled) retain their directory structure.

When workflows are invoked via workflow_call, GitHub Actions prepends a short hash to artifact names (e.g., abc123-firewall-audit-logs). The CLI handles this automatically by matching artifact names that end with -{base-name}.

# Both of these are recognized as the firewall artifact:
# - firewall-audit-logs           (direct invocation)
# - abc123-firewall-audit-logs    (workflow_call invocation)

See Audit Commands for downloading and analyzing workflow run artifacts, Cost Management for token-usage and spend reporting, Network for firewall configuration, and Compilation Process for how workflows upload artifacts.