Skip to content

Commit 8935fe5

Browse files
docs: document the usage artifact in reference/artifacts.md (#37679)
The `usage` artifact constant (`constants.UsageArtifactName = "usage"`) is produced by the conclusion job and is a valid value for the `--artifacts` flag on `gh aw logs` / `gh aw audit`, but it was missing from the Quick Reference table, the Artifact Sets table, and had no dedicated section. Add it in all three places to match the surrounding style. Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
1 parent 99c7b94 commit 8935fe5

1 file changed

Lines changed: 16 additions & 0 deletions

File tree

docs/src/content/docs/reference/artifacts.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ GitHub Agentic Workflows upload several artifacts during workflow execution. Thi
2020
| `aw-info` || Single-file | Engine configuration (`aw_info.json`) |
2121
| `prompt` || Single-file | Generated prompt (`prompt.txt`) |
2222
| `experiment` | `constants.ExperimentArtifactName` | Multi-file | A/B experiment state (`state.json`) uploaded by the activation job when experiments are declared in the frontmatter |
23+
| `usage` | `constants.UsageArtifactName` | Multi-file | Compact conclusion-job artifact with workflow-run metadata and token-usage files used by lightweight reporting and forecasting paths |
2324
| `safe-outputs-items` | `constants.SafeOutputItemsArtifactName` | Single-file | Safe output items manifest |
2425
| `code-scanning-sarif` | `constants.SarifArtifactName` | Single-file | SARIF file for code scanning results |
2526

@@ -36,6 +37,7 @@ The `gh aw logs` and `gh aw audit` commands support `--artifacts` to download on
3637
| `mcp` | `firewall-audit-logs` | MCP gateway traffic logs |
3738
| `detection` | `detection` | Threat detection output |
3839
| `experiment` | `experiment` | A/B experiment state (only present when experiments are declared) |
40+
| `usage` | `usage` | Compact conclusion-job artifact for lightweight reporting and forecasting |
3941
| `github-api` | `activation`, `agent` | GitHub API rate limit logs |
4042

4143
```bash
@@ -190,6 +192,20 @@ The `🧪 A/B Experiments` section of the audit report shows the variant chosen
190192

191193
See [A/B Experiments](/gh-aw/experimental/experiments/) for how to declare experiments in workflow frontmatter.
192194

195+
## `usage`
196+
197+
The `usage` artifact is a compact artifact produced by the conclusion job. It carries workflow-run metadata and token-usage files used by lightweight reporting and forecasting paths, so downstream tools can read aggregated usage data without downloading the full `agent` artifact.
198+
199+
### Accessing usage data
200+
201+
```bash
202+
# Download only the usage artifact
203+
gh aw logs <run-id> --artifacts usage
204+
205+
# Or with gh run download
206+
gh run download <run-id> -n usage
207+
```
208+
193209
## Naming Compatibility
194210

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

0 commit comments

Comments
 (0)