How to set a CI budget for coding agents

A developer outlined a three-layer CI budget strategy for coding agents: per-job timeouts, concurrency groups that cancel superseded runs, and hard dollar stops. Using published GitHub numbers, the writeup shows a hung job without timeout-minutes can run 360 minutes and cost $2.16 on a 2-core Linux runner at $0.006/minute, versus $0.09 with a 15-minute timeout, and notes that GitHub's account or repository budgets cannot cap spend per agent task, a gap the Latchkey tool fills with per-task and per-batch dollar limits.

A CI budget for coding agents needs three layers: a time limit on every job, a rule that cancels runs the agent already superseded, and a hard dollar stop that refuses new work once it is reached. GitHub gives you the first two in YAML and the third as an account or repository budget; Latchkey adds a budget on each piece of work, a batch, under a workspace spend limit. Each layer catches what the one above lets through. The GitHub dollar stop covers an account or repository; Latchkey adds one per piece of work. The expensive failure is rarely one big job. It is a cheap job repeated: a test the agent cannot fix, a hang it does not notice, a push per attempt that starts the full pipeline each time. Nobody is watching at 3 a.m., and an agent does not get bored. A worked example from published numbers shows the scale. A job with no timeout-minutes runs for up to 360 minutes; on a GitHub-hosted Linux 2-core runner at $0.006 per minute, one hung attempt costs $2.16. With timeout-minutes: 15 the same hang costs $0.09. Multiply either by the number of attempts in a night and the first layer has paid for itself. jobs.<job id .timeout-minutes defaults to 360, and a step's own timeout-minutes has the same 360 maximum. Set both lower on anything an agent can trigger. The job limit is the backstop; the step limit on the test step is the one that names the hang in the log. Pick the number from the slowest green run you have seen, with headroom, not from a guess at what is safe. A timeout that is too tight teaches the agent that the suite is flaky. jobs: test: runs-on: ubuntu-latest timeout-minutes: 15 steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 v7.0.1 - run: npm ci - run: npm test timeout-minutes: 10 Defaults and maximums from the workflow syntax reference; the $0.006 Linux 2-core rate from the Actions runner pricing reference on docs.github.com. Both read 2026-11-12. An agent that pushes every attempt starts a run per push. Only the newest one matters, so let GitHub cancel the rest: a concurrency group per workflow and ref, with cancel-in-progress: true , cancels the running and pending runs of the same branch when a newer one arrives. Build the group from github.workflow as well as the ref. GitHub's own reference warns that group names must be unique across workflows, or a run of one workflow cancels another's. concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true GitHub's hard stop lives in billing, under Budgets and alerts. For metered products such as GitHub Actions a budget can prevent usage once it is reached, but only if you select Stop usage when budget limit is reached . Without it you get an email at the threshold and usage carries on. Alerts can fire at 75%, 90% and 100%. Three details matter for agents. The narrowest scope for an organization budget is a single repository, so the stop is shared with every person working there: in GitHub's own example, once the organization's Actions budget is spent, members are blocked from using all GitHub-hosted runners until the next billing cycle or until the budget is raised. A budget counts metered usage only from the date it was created, so the first cycle can overshoot. And overlapping budgets each apply, so a product budget and a repository budget can block sooner than you expect. Budgets and alerts, and Setting up budgets, docs.github.com, read 2026-11-12. The loop itself. All three GitHub layers work per job, per branch or per account; none of them knows that forty runs over a night were one agent working one task. The retry cap belongs in the agent's instructions, and the dollar cap belongs on the task, which is the gap the next two sections fill. | Layer | GitHub Actions | Latchkey | |---|---|---| | One job | timeout-minutes default 360 | --timeout 30 s to 3 h, default 30 min and --budget in dollars | | Superseded work | concurrency with cancel-in-progress | concurrency in a Latchkey CI workflow file; latchkey cancel for jobs | | One piece of work | None | Batch budget: latchkey budget set <batch <dollars | | Everything | Budget with Stop usage, per account or repository | Workspace spend limit, per calendar month | A batch is a name you pass on every job of one task, with --batch or LATCHKEY BATCH . Its spend is every job in it at list rates, in whole minutes, with no monthly reset. Once that spend reaches the budget, latchkey run in the batch is refused before anything is created, with exit code 193, and the batch's queued jobs are held. Jobs already running finish within their own timeout and budget, so a batch can end a little past its number. The permission model is the useful part. An API key can set a batch's first budget, up to the workspace spend limit, or lower it, and never raise it; a raise is refused and the budget stays. Only a workspace owner or admin can raise one, on the Billing page. So the agent can be told to budget its own work without being able to talk itself into more. For a single command, --budget stops that job once it has cost the amount at its size's rate. A job stopped there ends with exit code 3, billed at most that budget. batch="agent-claude-fix-login" latchkey budget set "$batch" 5 --max-concurrent 4 latchkey run --batch "$batch" --timeout 900 --budget 0.25 'npm ci && npm test' case $? in 193 echo "batch budget reached: report it, do not retry" ;; 3 echo "this job hit its own budget" ;; esac latchkey batch show "$batch" Exit codes and budget rules from latchkey help run and latchkey help budget in @latchkeydev/cli 0.16.0, run 2026-11-12. An owner or admin sets the spend limit in US dollars on the Billing page. It counts the calendar month, and at the limit Latchkey refuses new jobs, holds queued ones and stops running ones, GitHub Actions jobs on Latchkey runners included. A job or batch budget can never be set above it. There is none by default, so set one before you hand a key to an agent. Budgets attach to work and to the workspace, not to keys: there is no per-key monthly budget. To see what one agent spent, name its batches after it, which is what Latchkey's own MCP setup page recommends, and read latchkey budget show <batch or the batch budgets list on the Billing page. Tell it in plain words, because the natural move for an agent that hits a wall is to try again. A refusal at the workspace spend limit carries the code JOB CREATION BLOCKED SPEND CAP REACHED and is a limit to report to a human, never one to retry. A batch at its budget, JOB BATCH BUDGET REACHED , takes a report or a new batch name for genuinely new work, and the CLI's reference rules out the obvious dodge: a new name is not a way around a budget your human set. The credential side of the same problem, one key per agent, is on one scoped API key per coding agent https://latchkey.dev/learn/agent-ci/scoped-api-key-per-coding-agent . The $2.16 and $0.09 in the introduction are arithmetic on published numbers, not a bill anyone received. No recorded run backs this page, and it has no entry in content/repro-evidence.mjs or content/heal-evidence.mjs . GitHub's side comes from the workflow syntax, pricing and budgets pages on docs.github.com; Latchkey's from latchkey help run and latchkey help budget in CLI 0.16.0 and its billing documentation, all read 2026-11-12. Create a budget for the Actions product under Billing, Budgets and alerts, scoped to your account, organization or a single repository, and select "Stop usage when budget limit is reached". Without that option the budget only sends alerts. With Stop usage selected, further metered usage is blocked: GitHub's example shows members blocked from all GitHub-hosted runners until the next billing cycle or until the budget is increased. Without it you are emailed and usage continues. 360 minutes. jobs.<job id .timeout-minutes defaults to 360, and if you set a value above the runner's execution time limit the job is canceled at that limit instead. Yes. Organization budgets can be scoped to the whole organization or to a single repository, and enterprise budgets can also target a cost center. A repository is the narrowest scope for Actions spend.