Skip to content

[WIP] Improve cost management reference documentation #20128

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 2 commits into from
Mar 8, 2026
Merged

[WIP] Improve cost management reference documentation #20128

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d9361b3
Initial plan
Copilot Mar 8, 2026
4e83d25
docs: improve cost-management reference with logs section and snippet…
Copilot Mar 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 58 additions & 3 deletions docs/src/content/docs/reference/cost-management.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,61 @@ The agent job invokes an AI engine (Copilot, Claude, Codex, or a custom engine)
> [!NOTE]
> For Copilot, inference is charged to the individual account owning `COPILOT_GITHUB_TOKEN`, not to the repository or organization running the workflow. Use a dedicated service account and monitor its premium request usage to track spend per workflow.

## Monitoring Costs with `gh aw logs`

The `gh aw logs` command downloads workflow run data and surfaces per-run metrics including elapsed duration, token usage, and estimated inference cost. Use it to see exactly what your workflows are consuming before deciding what to optimize.
Comment on lines +34 to +36
Copy link

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The PR description checklist mentions adding a concrete meta-agent workflow snippet to the “Agentic Cost Optimization” section, but this file still contains only narrative text in that section (no snippet/example workflow). Either add the promised snippet or update the PR description to match the actual changes.

Copilot uses AI. Check for mistakes.

### View recent run durations

```bash
# Overview table for all agentic workflows (last 10 runs)
gh aw logs

# Narrow to a single workflow
gh aw logs issue-triage-agent

# Last 30 days for Copilot workflows
gh aw logs --engine copilot --start-date -30d
```

The overview table includes a **Duration** column showing elapsed wall-clock time per run. Because GitHub Actions bills compute time by the minute (rounded up per job), duration is the primary indicator of Actions spend.

### Export metrics as JSON

Use `--json` to get structured output suitable for scripting or trend analysis:

```bash
# Write JSON to a file for further processing
gh aw logs --start-date -1w --json > /tmp/logs.json

# List per-run duration, tokens, and cost across all workflows
gh aw logs --start-date -30d --json | \
jq '.runs[] | {workflow: .workflow_name, duration: .duration, cost: .estimated_cost}'
Copy link

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the JSON export example, the comment says it will list per-run duration, tokens, and cost, but the jq filter only outputs workflow, duration, and cost. Either include token_usage in the jq output or update the surrounding text so it matches the actual fields being shown.

Suggested change
jq '.runs[] | {workflow: .workflow_name, duration: .duration, cost: .estimated_cost}'
jq '.runs[] | {workflow: .workflow_name, duration: .duration, tokens: .token_usage, cost: .estimated_cost}'

Copilot uses AI. Check for mistakes.

# Total cost grouped by workflow over the past 30 days
gh aw logs --start-date -30d --json | \
jq '[.runs[]] | group_by(.workflow_name) |
Copy link

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The jq example that uses group_by(.workflow_name) will produce incorrect totals unless the input array is sorted by workflow_name first (jq groups only adjacent equal keys). Consider adding sort_by(.workflow_name) before group_by, or use a reduce-based aggregation.

Suggested change
jq '[.runs[]] | group_by(.workflow_name) |
jq '[.runs[]] | sort_by(.workflow_name) | group_by(.workflow_name) |

Copilot uses AI. Check for mistakes.
map({workflow: .[0].workflow_name, runs: length, total_cost: (map(.estimated_cost) | add // 0)})'
```

The JSON output includes `duration`, `token_usage`, `estimated_cost`, `workflow_name`, and `agent` (the engine ID) for each run under `.runs[]`.

### Use inside a workflow agent

The `agentic-workflows` MCP tool exposes the same `logs` operation so that a workflow agent can collect cost data programmatically. Add `tools: agentic-workflows:` to any workflow that needs to read run metrics:

```aw wrap
description: Weekly Actions minutes cost report
on: weekly
permissions:
actions: read
engine: copilot
tools:
agentic-workflows:
```

The agent then calls the `logs` tool with `start_date: "-7d"` to retrieve duration and cost data for all recent runs, enabling automated reporting or optimization.

## Trigger Frequency and Cost Risk

The primary cost lever for most workflows is how often they run. Some events are inherently high-frequency:
Expand Down Expand Up @@ -58,14 +113,14 @@ The most effective cost reduction is skipping the agent job entirely when it is
on:
issues:
types: [opened]
skip-if-match: 'label:duplicate OR label:wont-fix'
skip-if-match: 'label:duplicate OR label:wont-fix'
```

```aw wrap
on:
issues:
types: [labeled]
skip-if-no-match: 'label:needs-triage'
skip-if-no-match: 'label:needs-triage'
```

Use these to filter out noise before incurring inference costs. See [Triggers](/gh-aw/reference/triggers/) for the full syntax.
Expand Down Expand Up @@ -155,7 +210,7 @@ These are rough estimates to help with budgeting. Actual costs vary by prompt si
| On-demand via slash command | User-controlled | Varies | Varies |

> [!TIP]
> Use `gh aw audit <run-id>` to inspect token usage and cost for individual runs, and `gh aw logs` for aggregate metrics across recent runs. Create separate `COPILOT_GITHUB_TOKEN` service accounts per repository or team to track spend by workflow.
> Use `gh aw audit <run-id>` to deep-dive into token usage and cost for a single run. Create separate `COPILOT_GITHUB_TOKEN` service accounts per repository or team to attribute spend by workflow.

## Related Documentation

Expand Down