Skip to content

Commit 7b2fb63

Browse files
feat: add Copilot enterprise usage reporting scripts (#169)
* feat: add Copilot usage reporting scripts * fix: address Copilot reporting review
1 parent c2d6532 commit 7b2fb63

5 files changed

Lines changed: 416 additions & 0 deletions

File tree

‎gh-cli/README.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -833,6 +833,24 @@ joshjohanning-org/.github, no code scanning results
833833

834834
Gets the commits of since a certain date - date should be in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format, ie: `since=2022-03-28T16:00:49Z`
835835

836+
### get-copilot-ai-credit-usage-by-user-and-model.sh
837+
838+
Exports monthly Copilot AI-credit usage by user and model for an enterprise.
839+
The script first uses daily per-user metrics to identify users with AI-credit
840+
usage, then makes one billing API call per identified user.
841+
842+
```shell
843+
./get-copilot-ai-credit-usage-by-user-and-model.sh <enterprise> [year] [month] [output.csv] [max-users]
844+
```
845+
846+
The script uses the current `gh auth` credential. Classic PAT authentication
847+
may require `read:enterprise` and `manage_billing:copilot`.
848+
849+
> [!WARNING]
850+
> The model breakdown endpoint only accepts one user filter at a time. Large
851+
> enterprises can require thousands of API calls and may approach the API rate
852+
> limit. Use the optional `max-users` argument for testing.
853+
836854
### get-dependencies-in-repository.sh
837855

838856
Gets dependencies used in the repository, including the ecosystem and version number.
Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
#!/usr/bin/env bash
2+
# Export monthly enterprise AI credit usage grouped by user and model.
3+
# Usage: get-copilot-ai-credit-usage-by-user-and-model.sh <enterprise> [year] [month] [output.csv] [max-users]
4+
# Requires authenticated gh access to Copilot metrics and billing plus jq and curl.
5+
set -euo pipefail
6+
7+
usage() {
8+
echo "Usage: $0 <enterprise> [year] [month] [output.csv] [max-users]" >&2
9+
}
10+
11+
fail() {
12+
echo "Error: $*" >&2
13+
exit 1
14+
}
15+
16+
api() {
17+
local error_file output
18+
error_file=$(mktemp)
19+
TEMP_FILES+=("$error_file")
20+
21+
if ! output=$(gh api "$@" 2>"$error_file"); then
22+
cat "$error_file" >&2
23+
if grep -q "HTTP 404" "$error_file"; then
24+
cat >&2 <<'EOF'
25+
26+
The API returned 404. Confirm the enterprise slug and credential access.
27+
For classic PAT authentication, try:
28+
gh auth refresh -s read:enterprise -s manage_billing:copilot
29+
30+
The metrics API also requires the enterprise Copilot usage metrics policy.
31+
The enterprise AI credit endpoint may require an enterprise owner or billing
32+
manager using a classic PAT.
33+
EOF
34+
fi
35+
return 1
36+
fi
37+
38+
printf '%s' "$output"
39+
}
40+
41+
days_in_month() {
42+
case "$1" in
43+
1|3|5|7|8|10|12) echo 31 ;;
44+
4|6|9|11) echo 30 ;;
45+
2)
46+
if (( YEAR % 400 == 0 || (YEAR % 4 == 0 && YEAR % 100 != 0) )); then
47+
echo 29
48+
else
49+
echo 28
50+
fi
51+
;;
52+
*) fail "Month must be between 1 and 12." ;;
53+
esac
54+
}
55+
56+
[[ $# -ge 1 && $# -le 5 ]] || { usage; exit 1; }
57+
for command_name in gh jq curl; do
58+
command -v "$command_name" >/dev/null 2>&1 ||
59+
fail "Required command not found: $command_name"
60+
done
61+
gh auth status >/dev/null 2>&1 ||
62+
fail "GitHub CLI is not authenticated. Run: gh auth login"
63+
64+
ENTERPRISE="$1"
65+
YEAR="${2:-$(date +%Y)}"
66+
MONTH=$((10#${3:-$(date +%m)}))
67+
[[ "$YEAR" =~ ^[0-9]{4}$ ]] || fail "Year must use YYYY format."
68+
69+
MONTH_PADDED=$(printf '%02d' "$MONTH")
70+
OUTPUT="${4:-${ENTERPRISE}-copilot-ai-credit-usage-${YEAR}-${MONTH_PADDED}.csv}"
71+
MAX_USERS="${5:-0}"
72+
[[ "$MAX_USERS" =~ ^[0-9]+$ ]] || fail "Max users must be a non-negative integer."
73+
74+
ACTIVE_USERS=$(mktemp)
75+
TEMP_FILES=("$ACTIVE_USERS")
76+
trap 'rm -f "${TEMP_FILES[@]}"' EXIT
77+
78+
LAST_DAY=$(days_in_month "$MONTH")
79+
echo "Finding users with AI-credit usage in $YEAR-$MONTH_PADDED..." >&2
80+
81+
for ((day = 1; day <= LAST_DAY; day++)); do
82+
report_date=$(printf '%04d-%02d-%02d' "$YEAR" "$MONTH" "$day")
83+
echo "Reading $report_date..." >&2
84+
api -H "X-GitHub-Api-Version: 2026-03-10" \
85+
"/enterprises/$ENTERPRISE/copilot/metrics/reports/users-1-day?day=$report_date" |
86+
jq -r 'if type == "object" then (.download_links // [])[] else empty end' |
87+
while IFS= read -r url; do
88+
[[ -n "$url" ]] || continue
89+
curl -fsSL "$url" |
90+
jq -r 'select(type == "object" and (.ai_credits_used // 0) > 0) | .user_login'
91+
done
92+
done | sort -u >"$ACTIVE_USERS"
93+
94+
user_count=$(wc -l <"$ACTIVE_USERS" | tr -d ' ')
95+
if (( MAX_USERS > 0 && user_count > MAX_USERS )); then
96+
head -n "$MAX_USERS" "$ACTIVE_USERS" >"${ACTIVE_USERS}.limited"
97+
mv "${ACTIVE_USERS}.limited" "$ACTIVE_USERS"
98+
user_count="$MAX_USERS"
99+
fi
100+
101+
echo "Found $user_count users. This next phase makes one billing API call per user." >&2
102+
if (( user_count > 1000 )); then
103+
echo "Warning: this may approach the 5,000 requests/hour classic PAT limit." >&2
104+
fi
105+
106+
{
107+
echo '"user","model","gross_ai_credits","included_ai_credits","net_ai_credits","gross_amount","net_spend"'
108+
while IFS= read -r login; do
109+
[[ -n "$login" ]] || continue
110+
echo "Processing $login..." >&2
111+
api --method GET -H "X-GitHub-Api-Version: 2026-03-10" \
112+
"/enterprises/$ENTERPRISE/settings/billing/ai_credit/usage" \
113+
-f year="$YEAR" -f month="$MONTH" -f user="$login" |
114+
jq -r --arg user "$login" '
115+
.usageItems
116+
| select(type == "array" and length > 0)
117+
| group_by(.model)[]
118+
| [
119+
$user,
120+
.[0].model,
121+
(map(.grossQuantity) | add),
122+
(map(.discountQuantity) | add),
123+
(map(.netQuantity) | add),
124+
(map(.grossAmount) | add),
125+
(map(.netAmount) | add)
126+
]
127+
| @csv
128+
'
129+
done <"$ACTIVE_USERS"
130+
} >"$OUTPUT"
131+
132+
echo "Created $OUTPUT" >&2

‎scripts/README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,10 @@ Migrate work items from Azure DevOps to GitHub issues - this just links out to a
4444

4545
See: [code-scanning-coverage-report](./code-scanning-coverage-report/README.md)
4646

47+
## copilot-enterprise-usage-report
48+
49+
See: [copilot-enterprise-usage-report](./copilot-enterprise-usage-report/README.md)
50+
4751
## create-app-jwt.py
4852

4953
This script will generate a JWT for a GitHub App. It will use the private key and app ID from the GitHub App's settings page.
Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# copilot-enterprise-usage-report
2+
3+
Generate monthly GitHub Copilot enterprise usage reports from the current
4+
`enterprise-1-day` Usage Metrics API.
5+
6+
## Outputs
7+
8+
- Weekly surface activity CSV
9+
- Standalone HTML report with embedded data
10+
11+
The report distinguishes unlike metrics instead of treating them as equivalent:
12+
13+
- IDEs expose user-initiated interactions and generation activity
14+
- Copilot CLI and Copilot App expose prompt and request counts
15+
- Copilot Coding Agent exposes Copilot-created pull requests
16+
- Copilot Code Review exposes Copilot-reviewed pull requests
17+
18+
## Prerequisites
19+
20+
- An authenticated GitHub CLI session: `gh auth status`
21+
- `jq`, `curl`, and `base64`
22+
- Enterprise access to Copilot usage metrics
23+
24+
Classic PATs need `read:enterprise` or `manage_billing:copilot`. Fine-grained
25+
credentials need the **View Enterprise Copilot Metrics** permission. The
26+
enterprise **Copilot usage metrics** policy must also be enabled.
27+
28+
## Usage
29+
30+
```shell
31+
./copilot-enterprise-usage-report.sh <enterprise> [year] [month] [output-prefix]
32+
```
33+
34+
Example:
35+
36+
```shell
37+
./copilot-enterprise-usage-report.sh avocado-corp 2026 7
38+
```
39+
40+
This creates:
41+
42+
```text
43+
avocado-corp-copilot-usage-2026-07-weekly.csv
44+
avocado-corp-copilot-usage-2026-07.html
45+
```
46+
47+
The API provides up to one year of daily history beginning October 10, 2025.
48+
Recent data can take several UTC days to finalize.

0 commit comments

Comments
 (0)