Concurrent workspace preflight

Self-hosted Runner Disk Capacity Checker

Combine every per-job workspace component and test the simultaneous peak against disk capacity after persistent use and reserve.

Decision guide

Size the highest simultaneous workspace, not one finished artifact

What this tool helps you decide

This checker determines whether a self-hosted continuous-integration runner has enough disk for the maximum simultaneous job workspace. It combines source checkout, Git LFS objects, installed dependencies, restored caches, build and test outputs, and temporary packaging space. The result reports per-job peak, concurrent peak, usable workspace after persistent usage and reserve, maximum modeled concurrency, and minimum disk capacity for the selected job count.

Before you start

Run a representative job on a disposable or well-observed runner and measure high-water disk use at each stage. Avoid adding the same directory twice: for example, if the checkout measurement already includes fetched LFS files, enter the non-LFS checkout and LFS portions separately or place the total in one field. Measure dependency and cache extraction peaks, not just downloaded archives. Record build output before cleanup and include temporary package copies. Separately measure operating system, toolchains, persistent daemon layers, logs, and abandoned workspaces.

How the calculation works

Per-job peak is the sum of the six entered workspace components. Concurrent peak multiplies this figure by maximum simultaneous jobs. Usable workspace applies the selected free-space reserve to total disk capacity and subtracts operating-system and persistent usage. Headroom is usable workspace minus concurrent peak. Maximum concurrency divides usable workspace by per-job peak and rounds downward. Minimum disk reverses the reserve formula so the requested concurrency, persistent use, and unused percentage can coexist.

How to interpret the results

A pass means the measured model fits the capacity boundary; it does not guarantee job isolation or I/O performance. Small positive headroom is fragile when jobs vary, logs accumulate, cleanup fails, or container daemons retain layers. A failure can be resolved by lowering concurrency, increasing disk, reducing per-job duplication, or cleaning persistent state. Do not simply delete workspaces while jobs are running. Confirm runner lifecycle and cache ownership before automating cleanup.

Worked example

An 8 GB checkout, 20 GB LFS payload, 12 GB dependency tree, 10 GB restored cache, 18 GB build peak, and 6 GB temporary area total 74 GB per job. Four concurrent jobs require 296 GB. A 500 GB disk with 20% reserved supplies 400 GB before persistent use; subtracting 80 GB leaves 320 GB. The plan passes with 24 GB headroom, supports four such jobs, and requires at least 470 GB of total disk for the entered reserve.

Assumptions and limitations

The calculation assumes simultaneous jobs reach the same peak at once, which is conservative when stages do not overlap and risky when unmeasured daemon layers grow independently. It does not inspect a runner, model filesystem metadata, snapshots, sparse files, inode limits, copy-on-write behavior, Docker build cache, log rotation, memory-backed temporary storage, IOPS, or cleanup race conditions. Decimal gigabytes are used. Measure actual free space and directory sizes with the runner's operating system and platform tools.

Next steps

Record a high-water mark over several job types, then set monitoring below the modeled reserve rather than at zero free space. Separate persistent cache volumes from disposable workspaces where the runner architecture supports it, and test cleanup after cancellation and failure. Use the Git LFS Storage & Bandwidth Planner for hosted source quotas and the Build Cache Capacity & Churn Planner for how long cache keys survive. For write wear on the runner SSD, continue to the VM & Container SSD Endurance Planner.