Setting a Per-Repository Monthly GitHub Actions Budget — Budgets and Defense-in-Depth for the AI Agent Era
With Claude Code, the GitHub Copilot coding agent, Codex, and similar AI coding agents in widespread use, GitHub Actions workflows now get triggered not only by pushes and PRs but also by agents making their own decisions. If the budget is still sized around the old assumption that CI runs only when a developer commits, an agent loop or a parallel-jobs fan-out can run up charges well beyond the expected amount within the first few days of a billing cycle. Before letting an AI agent touch CI, set a spending cap on the billing side first.
GitHub Actions billing exposes a monthly budget through Budgets and alerts, and that budget can be scoped to the whole Enterprise, a single Organization, a single repository, or a cost center. This post walks through the UI and REST API setup as of November 2026, how Organization and Repository budgets stack, the current rates, the pitfalls a hard budget cannot cover, and a defense-in-depth design.
Where budgets can be set
GitHub Actions monthly caps are configured under Settings → Billing & Licensing → Budgets and alerts. The official Setting up budgets guide covers the setup steps.
Budget scopes are:
| Scope | Where it is set | Who can set it |
|---|---|---|
| Whole Enterprise, cost center | Enterprise Billing & Licensing | Enterprise owner, billing manager |
| Whole Organization, a repository in the Organization | Organization Billing & Licensing | Organization owner, billing manager |
| Whole personal account, a repository under it | Personal Settings → Billing | The account owner |
Up to 10,000 budgets per account are allowed, so wiring individual budgets to hundreds of repositories is viable. Budget scope and target SKU are immutable after creation; to point a budget at a different repository, delete and recreate it.
Creating a Repository budget from the UI
The steps to create a hard budget scoped to a single repository under an Organization are:
- Open the Organization’s
Settingsand clickBilling & Licensingunder Access on the sidebar. For Enterprise accounts, use the Billing & Licensing tab at the top. For a personal account, open https://github.com/settings/billing. - Click
Budgets and alerts, thenNew budget. - Pick a
Budget Type.Product-level budgetwith Product set toActionscovers all Actions SKUs. For a single expensive runner or the Actions cache overage, useSKU-level budgetand pick a SKU such asactions_linux_96_coreoractions_cache_storage. - Set
Budget scopetoRepositoryand choose one repository. - Enter the monthly cap in whole USD under
Budget. - Check
Stop usage when budget limit is reached. Without this box, the same dollar amount only sends an alert and does not stop further charges. - Enable
Receive budget threshold alertsand add recipients (SRE, platform team) underAlert Recipients. - Click
Create budget.
In the same Budgets and alerts page, the Included usage alerts option sends a notification when the plan’s included (free) allowance reaches 90% and 100%. Included compute usage is shared across an Organization, which is one of the sharp edges discussed below, so enabling this early warning is worthwhile.
Managing budgets through the REST API
The Budget Management API covers the full budget lifecycle: create, read, update, and delete. Organization endpoints are:
POST /organizations/{org}/settings/billing/budgets
GET /organizations/{org}/settings/billing/budgets
GET /organizations/{org}/settings/billing/budgets/{budget_id}
PATCH /organizations/{org}/settings/billing/budgets/{budget_id}
DELETE /organizations/{org}/settings/billing/budgets/{budget_id}A fine-grained PAT or GitHub App token with Organization Administration: write is required, and the authenticated user must be an Organization owner or billing manager. The call below sets ORG/REPO to a 100 USD hard budget on Actions:
gh api --method POST \
-H "Accept: application/vnd.github+json" \
-H "X-GitHub-Api-Version: 2026-03-10" \
/organizations/ORG/settings/billing/budgets \
--input - <<'EOF'
{
"budget_amount": 100,
"prevent_further_usage": true,
"budget_scope": "repository",
"budget_entity_name": "ORG/REPO",
"budget_type": "ProductPricing",
"budget_product_sku": "actions",
"budget_alerting": {
"will_alert": true,
"alert_recipients": ["alice", "bob"]
}
}
EOFbudget_amountis a whole-dollar integer (no sub-dollar granularity).prevent_further_usage: trueis the hard cap.falsefalls back to notifications only.- When creating through the Organization endpoint,
budget_scopeacceptsorganization,repository,multi_user_customer, oruser. - Product-wide budgets use
budget_type: "ProductPricing"withbudget_product_sku: "actions". SKU-level budgets useSkuPricingwith a SKU such asactions_linux.
PATCH allows editing budget_amount, prevent_further_usage, and budget_alerting only. Scope and SKU are immutable. The Product and SKU names reference lists the valid SKUs.
Enterprise budgets live under /enterprises/{enterprise}/settings/billing/budgets. The Enterprise endpoints accept GitHub App user access tokens or installation access tokens with the Enterprise billing enterprise permission; fine-grained PATs are not listed as supported. To keep using the same fine-grained PAT as the Organization endpoints, standardize on the Organization endpoints and create one Repository budget per repo.
The official integrations/terraform-provider-github provider does not yet carry Budget resources; Issue #3561 proposes adding resources for Enterprise Budgets. For now, calling the REST API idempotently from a provisioning pipeline or a daily gh api script is the practical path to Infrastructure-as-Code management.
How Organization and Repository budgets stack
Hard caps stack as a logical AND: any applicable budget with Stop usage enabled that hits zero blocks further usage. The Setting up budgets page states:
Usage of metered products can count toward multiple applicable budgets at the same time, and if any budget with Stop usage … enabled is exhausted, additional usage is blocked.
flowchart TD
A[Workflow requests a GitHub-hosted runner] --> B{Enterprise hard budget has room?}
B -- No --> X[Enterprise-wide block]
B -- Yes --> C{Organization hard budget has room?}
C -- No --> Y[Organization-wide block]
C -- Yes --> D{Repository hard budget has room?}
D -- No --> Z[Only this repo is blocked]
D -- Yes --> E[Runner runs; usage counted against all budgets]
- With a 500 USD Organization hard budget and a 100 USD hard budget on Repository A, A stops at 100 USD and the rest of the Organization keeps running.
- If the Organization hard budget hits 500 USD first, every repository under it stops regardless of whether individual Repository budgets still have room.
- A Repository budget cannot “escape” a higher-level cap. Lower-scope budgets only act as a stricter constraint on top of higher-scope ones.
Budgets do not sum across scopes. An Organization budget of 200 USD with two Repository budgets of 50 USD each does not raise the Organization total to 300 USD. GitHub itself recommends avoiding overlapping budgets, but when the intent is deliberate defense-in-depth, these roles work well:
- Top layer (Enterprise or Organization): the absolute ceiling the company cannot cross.
- Middle layer (Repository): a circuit breaker for high-cost, high-parallelism, or fork-PR repositories.
- Bottom layer (workflow-side timeout and concurrency): per-job and per-push consumption controls.
Keeping the sum of Repository budgets below the Organization budget usually causes a runaway repo to trip its own breaker before the Organization-wide one, so other teams’ CI keeps running. The same rule applies to Product-level versus SKU-level budgets: a product-level actions budget exhausting at zero blocks all GitHub-hosted runners even if a SKU-level budget still has room.
Sizing against the 2026 rates
Sizing a budget sanely requires the current rates and included allowance. The included allowance is expressed in USD as Included compute usage.
| Plan | Monthly included compute | Artifacts + Packages shared | Per-repository cache |
|---|---|---|---|
| GitHub Free (Personal) | 12 USD | 500 MiB | 10 GiB |
| GitHub Pro | 18 USD | 1 GiB | 10 GiB |
| GitHub Free for organizations | 12 USD | 500 MiB | 10 GiB |
| GitHub Team | 18 USD | 2 GiB | 10 GiB |
| GitHub Enterprise Cloud | 300 USD | 50 GiB | 10 GiB |
Standard GitHub-hosted runner rates follow (Actions runner pricing). Standard runners on public repositories and self-hosted runners (public or private) do not incur GitHub Actions compute charges.
| Runner | USD / minute | 1 job hangs 6 h | 20 parallel jobs hang 6 h |
|---|---|---|---|
| Linux 1-core (slim) | 0.002 | 0.72 | 14.40 |
| Linux 2-core x64 | 0.006 | 2.16 | 43.20 |
| Linux 2-core arm64 | 0.005 | 1.80 | 36.00 |
| Windows 2-core | 0.010 | 3.60 | 72.00 |
| macOS 3–4 core | 0.062 | 22.32 | 446.40 |
Larger runners cost more per minute and are billed even on public repositories.
| Larger runner | USD / minute | 1 job hangs 6 h | 20 parallel jobs hang 6 h |
|---|---|---|---|
| Linux 32-core | 0.082 | 29.52 | 590.40 |
| Linux 64-core | 0.162 | 58.32 | 1,166.40 |
| Linux 96-core | 0.252 | 90.72 | 1,814.40 |
| Windows 96-core | 0.552 | 198.72 | 3,974.40 |
| macOS M2 Pro 5-core | 0.102 | 36.72 | 734.40 |
| Linux GPU 4-core | 0.052 | 18.72 | 374.40 |
Storage charges run on accrued GB-hours and settle monthly. Artifacts share their allowance with GitHub Packages.
| Storage | USD / GiB-month |
|---|---|
| Artifacts + Packages shared | 0.25 |
| Actions cache (over 10 GiB per repository) | 0.07 |
| Larger-runner custom images | 0.07 |
Storage is accrued hourly, and deleting an artifact mid-month stops future accrual but does not refund the hours already billed. Artifact storage usage can lag by 6–12 hours per the official billing doc.
A 0.002 USD/minute platform charge on self-hosted runners in private repositories has been postponed, and as of November 2026 no effective date has been announced (Update to GitHub Actions pricing).
Five pitfalls a hard budget cannot cover
Hard budgets are a strong safeguard, but relying only on them invites surprise overruns or unplanned CI stoppages.
- The first billing cycle can exceed the cap. A newly created budget only counts usage from its creation timestamp forward (Budgets and alerts calls out “you may exceed your budget in the first billing cycle”). Mid-month budget creation bills pre-creation usage on top of the cap. Create budgets at month boundaries or before go-live.
- The included allowance is shared across the Organization. Included compute usage is not partitioned per repository; a healthy Repository B starts incurring paid usage the moment Repository A drains the pool. Use Included usage alerts at 90% / 100% to spot the exhaustion before it hits paid territory.
- In-flight job behavior is unspecified. The docs say “additional usage is blocked” but do not state whether a job already running when the budget is exhausted is killed immediately or allowed to complete. If a fan-out of parallel jobs starts just before the budget runs out, the charges for those jobs running to completion may be unavoidable.
- Larger runners refuse to start with a 0 USD budget. The Larger runners reference lists a spending limit greater than zero and a valid credit card on file as prerequisites. Setting a 0 USD budget on a repository that uses Larger runners stops jobs entirely; use 1 USD or more.
- The ~1,000 USD support-only block. Multiple GitHub Community reports from 2026 (#199036, #206941, #207969, #209042) describe CI halting at about 1,000 USD of Actions usage while still within budget, or staying blocked even after the budget was raised. GitHub has not published an official explanation; each case required Support engagement. Do not assume the configured budget is the only reason CI could stop; keep a Support escalation path ready.
Defense-in-depth design
Treat the hard budget as the safety net, timeout and concurrency as the runaway brake, and the Usage API as the early-warning system.
| Area | Setting / practice | Risk it blunts |
|---|---|---|
| Job timeout | Set jobs.<job_id>.timeout-minutes to the expected runtime plus margin (for example 20 minutes). The default in the workflow syntax is 360 minutes | 6-hour hangs, especially on macOS and Larger runners |
| Concurrency | Add concurrency: { group: "${{ github.workflow }}-${{ github.ref }}", cancel-in-progress: true } to every CI workflow. Deployment workflows use cancel-in-progress: false | Duplicate runs from rapid pushes or PR updates |
| Larger runner access | Set the runner group’s Repository access to Selected repositories and allowlist only what needs it | Accidental use of high-rate runners via a YAML typo or a test |
| Artifact retention | Shorten Artifact and log retention in Settings → Actions → General to 7–30 days. Use retention-days on actions/upload-artifact for per-job overrides | GB-hour creep from forgotten artifacts |
| AI agent execution controls | Set max-ai-credits in the GitHub Agentic Workflows frontmatter to cap AI Credits per run (cost management), and Actions policies at the Organization level to restrict which actors and events can start workflows | Agent loops or unapproved high-cost job launches |
For early warning, call the Usage Summary API from a daily scheduled workflow to track consumption per repository and per SKU. The Organization endpoint is:
GET /organizations/{org}/settings/billing/usage/summaryAn example call:
curl -sL \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer $GITHUB_TOKEN" \
-H "X-GitHub-Api-Version: 2026-03-10" \
"https://api.github.com/organizations/$ORG/settings/billing/usage/summary?year=2026&month=11&repository=$ORG/$REPO&product=Actions"The response carries grossAmount, discountAmount, and netAmount per SKU, so dashboards can separate list-price burn from post-allowance spend. A Cybozu engineering blog post describes a Grafana setup that plots both and projects month-end spend as “month-to-date × (days_in_month ÷ current_day) × 1.5 safety factor”, leaving time to respond before the budget is reached. Making this projection a standing item in a daily standup or team meeting catches the days when an AI agent misconfiguration spikes consumption out of nowhere.
Recommended configuration
A Team or Enterprise Cloud Organization typically benefits from a layered setup like the one below. Dollar amounts should be tuned to the organization’s usage.
| # | Budget | Scope | Stop usage | Alerts | Purpose |
|---|---|---|---|---|---|
| 1 | 1.5–2× expected monthly Actions spend | Organization | On | Owner, billing manager, SRE | Company-wide final ceiling |
| 2 | 1.2–1.5× expected monthly Actions spend per repo | High-cost or high-risk repositories (macOS builds, E2E, fork-PR targets) | On | Repository owning team | Local breaker so one repo cannot halt the Organization |
| 3 | Larger-runner SKU such as actions_linux_96_core | Organization | On | SRE | Dedicated cap on high-rate runners |
| 4 | Expected monthly Actions spend per repo (optional) | Regular repositories | Off (soft) | Repository owning team | Early detection without blocking |
| 5 | actions_cache_storage | Organization | On | SRE | Only when the cache allowance has been raised |
Add timeout-minutes and concurrency to every workflow, keep Larger runners restricted to specific repositories through runner groups, and shorten artifact retention. Auto-provision a default Repository budget on new repository creation by calling the Budget API from the repository provisioning pipeline.
That’s all from laying out a per-repository hard-cap and defense-in-depth setup for GitHub Actions in the AI coding agent era, from the Gemba.