spending-limit-detector

name	spending-limit-detector
description	Detect GitHub Pro spending limit (the "spending limit needs to be increased" annotation) before debugging code. The pattern: look for the specific annotation text in `gh run view` output. Use this skill to triage red CI Build runs quickly — saves hours of "fixing" code that was never broken.

Spending Limit Detector

GitHub Pro (and other paid plans) have soft caps on monthly Actions minutes. When exceeded, new workflow runs don't start — they fail at the queue level, not the code level. This is the most common "false failure" in fleet operations.

The Detection

gh run view <run_id> --repo camster91/<repo> | grep -i "spending"

If the output contains:

The job was not started because recent account payments have failed
or your spending limit needs to be increased. Please check the
'Billing & plans' section in your settings.

Then the failure is the spending cap, not the code.

Why It Happens

• GitHub Pro gives 2,000 min/month for Actions
• A 59-repo fleet with weekly CI on each = ~10 min/repo/run = 590 min/week from CI alone
• Add Dependabot PRs (35 PRs × 3-5 min each = 105-175 min/week)
• Plus occasional push-triggered runs for source fixes

That's ~715-765 min/week or ~2,800-3,000 min/month — over the cap.

The Fix (User Action Required)

The agent cannot fix this. The user must:

1. Go to GitHub.com → Settings → Billing and plans → Spending limit
2. Increase the limit (default is $0; Pro users can go up to their plan amount)
3. Optionally set a monthly cap to prevent runaway costs

After the user increases the limit, existing workflow runs don't auto-retry. They need to be re-triggered (push a no-op commit or use gh workflow run).

Detecting the Pattern Fleet-Wide

# For each repo, check the latest run for billing cap
for repo in $(gh repo list --limit 200 --no-archived --json name -q . | jq -r '.[]'); do
    run_id=$(gh run list --repo camster91/$repo --workflow ci.yml --limit 1 --json databaseId -q . 2>/dev/null)
    if [ -n "$run_id" ]; then
        if gh run view $run_id --repo camster91/$repo 2>/dev/null | grep -q "spending limit"; then
            echo "$repo: BILLING CAP"
        fi
    fi
done

What the Agent Should Do

When the cap is hit:

1. Stop trying to fix code — nothing is broken
2. Report the situation — "16 repos are blocked by GitHub Pro spending cap. To fix, go to Settings → Billing and increase the limit. Once increased, I can re-trigger the runs."
3. Optionally queue a "follow-up re-trigger" — save a script that, once the cap is reset, re-triggers all workflows

# Save this for the user to run after the cap resets
for repo in $(cat blocked_repos.txt); do
    gh workflow run lint.yml --repo camster91/$repo
    gh workflow run ci.yml --repo camster91/$repo
done

Common Pitfalls

1. Don't waste hours debugging code when the issue is billing cap. Check the annotation first.
2. The "spending limit" annotation is on the run, not the job — you need gh run view (run level) not gh run view <job-id> (job level).
3. Cancelled runs might say "failure" but the conclusion is cancelled. Don't confuse with billing cap.
4. Dependabot PRs often fail with billing cap — when the fleet is busy, Dependabot's auto-PRs are the first to get queued out.

Related Skills & Chains

• fleet-ci-audit — Use this first to identify which repos are blocked by billing cap
• dependabot-ops — Temporarily disable Dependabot on repos that are heavy users to save minutes
• repo-archival-policy — Archiving unused repos saves Actions minutes