Warn before the Actions minute budget runs out

[ExtraToast]

What to build

The organization ran out of Actions minutes on 2026-08-27 with no warning at all. Every private repo went dark mid-working-session — runs allocated nothing and failed in three seconds — and the first anyone knew of it was workflows failing for reasons that looked like broken code.

Nothing watches the spend. Add a watchdog that warns while there is still room to act.

It reads the org's Actions consumption, compares it against the included allowance, and raises a visible alert as the month's usage crosses thresholds — early enough that a busy week can be noticed before it becomes an outage. Run it on a schedule from a public repo, where standard runners are free, so the watchdog itself never contributes to the problem it watches.

The billing API moved and the old endpoint is gone. /orgs/{org}/settings/billing/actions now returns 410 This endpoint has been moved. The enhanced billing endpoint at /organizations/{org}/settings/billing/usage works and — usefully — needs no admin:org scope, only an ordinary token. It accepts year and month, and returns per-repo line items carrying product, sku, unitType, quantity and netAmount. Confirmed working against this org while writing this ticket.

Two traps that will otherwise produce a watchdog that reads plausibly and reports nonsense:

• The response covers public and private repos together, and public usage is fully discounted rather than absent. Filter on what actually consumes the allowance, or the number will read roughly five times too high.
• The allowance is consumed in billable minutes, not wall-clock minutes. GitHub rounds every job up to a full minute, so 561 minutes of real compute billed 2,845. A watchdog reasoning about run durations will consistently under-report.

Alert somewhere a human sees without looking — the estate already has a Discord webhook path for this.

Acceptance criteria

• Current month private-repo Actions consumption is reported against the allowance
• Crossing a threshold produces an alert a human receives without going looking for it
• The watchdog runs from a public repo and its own runs are billed as free
• Public-repo usage is excluded from the figure compared against the allowance
• The threshold alert is verified by forcing it to fire — a watchdog whose alarm has never been observed to trigger is not known to work
• The figure it reports is reconciled once against the billing UI, so a wrong-by-a-factor reading is caught immediately rather than at the next outage

Blocked by

• None — can start immediately.

[ExtraToast]

Built, merged, and running — but not yet watching. One owner action needed.

Reusable workflow in #128, scheduled caller in JorisJonkers-dev/.github#43, plus two follow-up fixes (#130, #131) and a caller fix (JorisJonkers-dev/.github#44).

The arithmetic is verified against live billing data, including that the alarm fires rather than only that it stays quiet:

allowance	usage	branch	exit
10000	32%	notice only	0
4200	75%	::warning::	0
3000 (real)	105%	::error::	1

That 105% is real: 3,159 of 3,000 included minutes for August 2026, private repos only. The org is past its allowance, which is why a monetary budget was needed. (Higher than the ~2,975 I reported on the 27th — that came from a top-N list and missed three private repos.)

What is blocked

The App installation token cannot read org billing:

##[notice]10 private repo(s) of 33 in JorisJonkers-dev        <- token fine here
##[warning]gh api .../settings/billing/usage failed: 403 Resource not accessible by integration

Billing sits behind its own App permission, "Organization plan" (read). Pick one:

1. Grant the App that permission, accept the updated installation permissions, then set app-has-billing-permission: true on the caller. Best end state — nothing to rotate.
2. Add a BUDGET_TOKEN secret with org billing read access. Works immediately, no App changes. It deliberately outranks the plain App token.

Until then the watchdog runs, fails loud, and prints exactly that remedy.

Two things learned the hard way, worth keeping

• My local PAT could read the endpoint; the App token could not. That is why this passed local verification and failed in CI. Local verification of a token-scoped call proves the arithmetic, not the access.
• create-github-app-token fails the job when asked for a permission the installation lacks — it does not degrade. Requesting it optimistically (fix(budget): request the billing permission and say so when it is missing #130) took the whole watchdog down at token minting, producing a zero-job run that fails in seconds. That signature is indistinguishable from an exhausted Actions quota, i.e. the exact condition this watchdog exists to detect. fix(budget): make the billing permission opt-in so it degrades instead of dying #131 made the permission opt-in for that reason.

Cadence caveat, unchanged

The caller is scheduled, and GitHub throttles schedules hard in this org — 4–7 runs per repo per day regardless of declared cron (JorisJonkers-dev/.github#42). Fine for a budget check; it cannot promise to warn within minutes, and the workflow comment says so.