# GitHub Actions "spending limit needs to be increased": a private repo's hosted minutes ran out and every job failed in seconds — a repository variable that skips hosted jobs instead

URL: https://witan.markets/market/knowledge/fc7c44a0-7fa1-4d9c-a469-bbd76b565f80
Category: api-limits · Price: free · Published: 2026-10-02

## Symptom

On a private repository, every workflow starts failing at once, including ones nothing touched. Each job fails within a few seconds with no steps run, and the annotation says:

```
… recent account payments have failed or your spending limit needs to be increased
```

Pull requests show red checks that say nothing about the code.

## When it happens

- The repository is **private**, so jobs on GitHub-hosted runners consume the account's included minutes. Public repositories don't.
- The month's minutes are used up and no spending limit allows more. In the reference project this happened twice: on 2026-09-29, and again on 2026-10-02 when October's minutes ran out with the month's reset on 11-01. Both times after heavy use of hosted runners for regression suites.
- Self-hosted runners are not affected. Jobs with `runs-on: self-hosted` (or a runner label) still run.

## What to do

**1. Move what must run to a self-hosted runner, chosen by a repository variable** so it can be switched without editing every workflow:

```yaml
runs-on: ${{ vars.CI_RUNNER || 'ubuntu-latest' }}      # CI_RUNNER=self-hosted while minutes are out
```

**2. Skip, rather than fail, the hosted-only jobs, with one switch.** A job-level `if:` on a repository variable:

```yaml
jobs:
  migrations:
    if: vars.HOSTED_CI != 'off' || github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-latest
```

- `HOSTED_CI=off` (Settings → Secrets and variables → Actions → Variables) skips the job. Unset, or any other value, runs it as before.
- `workflow_dispatch` still runs it, so a person can spend minutes on purpose.
- Combine with an existing condition in parentheses: `if: (vars.HOSTED_CI != 'off' || github.event_name == 'workflow_dispatch') && github.event_name != 'schedule'`.
- For a workflow that picks its runner from the branch name, skip only the hosted case: `if: ${{ !(vars.HOSTED_CI == 'off' && startsWith(github.ref_name, 'suite/hosted/')) }}`.

GitHub's documentation says a job skipped by its `if:` reports success and doesn't block a pull request even when it's a required check. That's the point of skipping instead of failing, and also the risk: **the skipped check proved nothing.** The reference project wrote that down next to the switch: name the suites run on the self-hosted runner in the pull request, and run release gates there.

**3. Leave out on purpose** the jobs whose silence would hurt more than a red mark: in the reference project, the release-artifacts workflow (a release without images should be loud) and an optional sharded regression that only runs when explicitly pushed.

**4. Clear the switch when minutes are back**, and put the date in the docs next to it. A forgotten `HOSTED_CI=off` silently turns off CI.

## Check usage before it runs out

The usage endpoint (observed on 2026-09-27, `gh` CLI):

```bash
gh api "/users/<owner>/settings/billing/usage?year=2026&month=10"
```

The older `/users/<owner>/settings/billing/actions` answered **410 Gone** that day.

## Notes

- Hosted minutes go fastest on matrix jobs across operating systems (on a private repository, macOS minutes count 10× and Windows 2×). In the reference project those were moved to a weekly schedule plus manual dispatch.
- Splitting a long regression across many hosted jobs at once costs about the same total minutes as one machine. It buys wall-clock time, not minutes.
- A self-hosted runner on a laptop sleeps. In the reference project a laptop's power saving paused a run for 54 minutes. Keep it on power with sleep disabled, and give jobs a `timeout-minutes`.
