Intelligent disk space optimization for GitHub Actions runners with automatic Docker relocation. Supports both Ubuntu and macOS runners.
TL;DR: Run this BEFORE resource-intensive operations (builds, K8s clusters, large downloads) to maximize available space with minimal overhead.
GitHub Actions free-tier Ubuntu runners have limited disk space (~14GB free on root partition). Building containers, running Kubernetes, or large test suites can quickly exhaust this space, causing mysterious failures.
quick-cleanup intelligently frees disk space and relocates Docker storage to the larger /mnt partition in a single, fast step.
jlumbroso/free-disk-space:
- ✅ Comprehensive cleanup (can free ~34GB)
- ❌ Slow (4-5 minutes even for minimal cleanup)
- ❌ All-or-nothing approach (can't skip cleanup if space sufficient)
- ❌ Doesn't relocate Docker storage
- ✅ Best for: Maximum space recovery when time isn't critical
quick-cleanup:
- ✅ Fast (<1 minute for light mode, <3 minutes aggressive)
- ✅ Adaptive (auto-detects available space, skips work if unnecessary)
- ✅ Relocates Docker to /mnt automatically (unique feature)
- ✅ Pre-operation focused (runs BEFORE builds, not after)
- ✅ Best for: CI pipelines needing quick, intelligent cleanup
- name: Optimize disk space
uses: palmsoftware/quick-cleanup@v0This will:
- Auto-detect disk space and clean accordingly
- Relocate Docker storage if /mnt is on a separate partition (older runners)
- Complete in 1-3 minutes
- name: Aggressive cleanup
uses: palmsoftware/quick-cleanup@v0
with:
cleanup-mode: aggressive
minimum-free-space: 20-
Check available space
-
20GB available: Light cleanup (cache, snap, Android, Docker)
- ≤20GB available: Aggressive cleanup (+ removes dotnet, powershell, chromium, node_modules, ghc)
-
-
Relocate Docker storage (if beneficial)
- On older runners with separate /mnt partition: Moves Docker to /mnt for additional space
- On newer runners: Skips relocation (same partition, no benefit)
- Validates services after restart when relocation occurs
-
Validate and report
- Shows space freed
- Validates minimum space requirement (if set)
- Fails fast if insufficient space after cleanup
Light mode:
- Package cache (apt-get clean, autoremove)
- Snap packages (disabled revisions)
- Android SDK (~8GB)
- Docker images/containers/volumes
- Log files and temporary files
Aggressive mode (everything above plus):
- /usr/share/dotnet (~3GB)
- /usr/local/share/powershell (~1GB)
- /usr/local/share/chromium (~1GB)
- /usr/local/lib/node_modules (~1GB)
- /opt/ghc, /usr/local/.ghcup (~2GB)
- Large packages: MySQL, PostgreSQL, Firefox, Azure CLI, Google Cloud SDK
Light mode:
- Homebrew cache cleanup
- Android SDK (if present)
- Docker image prune (if Docker is available)
- Temporary files and log files
Aggressive mode (everything above plus):
- Xcode simulator runtimes (~5-15GB)
- /usr/local/share/dotnet (.NET SDK)
- /usr/local/share/powershell
- /usr/local/share/chromium
- /usr/local/lib/node_modules
- /opt/ghc, /usr/local/.ghcup (Haskell)
- System/library caches (~/Library/Caches, /Library/Caches)
- name: Prepare runner
uses: palmsoftware/quick-cleanup@v0
- name: Build large image
run: docker build -t myapp:latest .- name: Optimize disk
uses: palmsoftware/quick-cleanup@v0
with:
minimum-free-space: 15
- name: Create K8s cluster
uses: palmsoftware/quick-k8s@v0- name: Free space for test artifacts
uses: palmsoftware/quick-cleanup@v0
with:
cleanup-mode: light # Fast cleanup for quick tests- name: Prepare for OCP
uses: palmsoftware/quick-cleanup@v0
with:
cleanup-mode: aggressive
minimum-free-space: 25
- name: Deploy OpenShift
uses: palmsoftware/quick-ocp@v0- name: Free space on macOS runner
uses: palmsoftware/quick-cleanup@v0
with:
cleanup-mode: aggressive
remove-xcode-simulators: 'true'
remove-homebrew-cache: 'true'| Input | Description | Default | Options |
|---|---|---|---|
cleanup-mode |
Cleanup intensity | auto |
auto, light, aggressive, skip |
relocate-docker |
Docker relocation strategy | auto |
always, auto, never |
docker-storage-path |
Custom Docker data-root | /mnt/docker-storage |
Any absolute path |
minimum-free-space |
Required free space (GB) | 0 |
Number (0 = no validation) |
cleanup-threshold |
Threshold for auto mode (GB) | 20 |
Number |
remove-android |
Remove Android SDK | true |
true, false |
remove-large-packages |
Remove databases, browsers, CLIs (Linux only) | true |
true, false |
remove-docker-images |
Prune Docker images | true |
true, false |
remove-xcode-simulators |
Remove Xcode simulator runtimes (macOS only) | true |
true, false |
remove-homebrew-cache |
Clean Homebrew cache (macOS only) | true |
true, false |
Minimal cleanup (Docker relocation only):
- uses: palmsoftware/quick-cleanup@v0
with:
cleanup-mode: skipCustom threshold:
- uses: palmsoftware/quick-cleanup@v0
with:
cleanup-threshold: 15 # Aggressive if <15GBEnforce minimum space:
- uses: palmsoftware/quick-cleanup@v0
with:
minimum-free-space: 25 # Fail if <25GB after cleanupConservative cleanup:
- uses: palmsoftware/quick-cleanup@v0
with:
cleanup-mode: light
remove-android: false
remove-large-packages: falseTested on ubuntu-22.04 runners:
| Mode | Time | Space Freed | Final Free Space |
|---|---|---|---|
| skip (Docker only) | ~30s | +11GB (relocation) | ~25GB |
| light | ~1m | ~15GB | ~29GB |
| aggressive | ~2.5m | ~22GB | ~36GB |
Note: Results may vary based on runner image version and pre-installed packages
- ✅ Ubuntu 22.04 (fully tested)
- ✅ Ubuntu 24.04 (fully tested)
⚠️ Other Linux: May work, not tested⚠️ macOS 15 (experimental — cleanup only, no Docker relocation)- ❌ Windows: Not supported
- Linux cleanup: Relies on apt, systemd, standard GitHub Actions runner layout
- macOS cleanup: Experimental; no Docker relocation (macOS runners don't use /mnt partitions)
- Root partition focus: Optimized for standard runner disk layout (/, /mnt on Linux)
- No undo: Cleanup is permanent, cannot restore removed packages
- Sudo required: All operations require sudo access
- Run early: Execute as one of the first steps in your workflow
- Use auto mode: Let the action decide cleanup intensity
- Set minimum-free-space: For critical workflows, validate space requirements
- Combine with quick-k8s/quick-ocp: Designed to work seamlessly together
- Monitor timing: If cleanup is slow, consider if you need aggressive mode
Cause: /mnt is on the same partition as / (newer GitHub Actions runners)
Expected behavior: This is normal. Modern GitHub Actions runners don't have a separate /mnt partition, so Docker relocation is automatically skipped when using relocate-docker: auto (default).
Note: If you explicitly set relocate-docker: always, the action will fail with an error. Use auto or never instead.
Cause: Cleanup didn't free enough space to meet minimum requirement
Solutions:
- Try aggressive mode:
cleanup-mode: aggressive - Reduce minimum requirement:
minimum-free-space: 10 - Use external cleanup action first:
jlumbroso/free-disk-space
Cause: Another process is using apt (e.g., unattended-upgrades)
Resolution: quick-cleanup uses best-effort approach and will continue despite apt locks. Check logs for warnings but action should still succeed.
Cause: Docker relocation encountered an error
Resolution: quick-cleanup automatically rolls back configuration on failure. Check action logs for specific error. Set relocate-docker: never to skip relocation.
Contributions welcome! Please:
- Run
make lintbefore submitting - Test on ubuntu-22.04 and ubuntu-24.04
- Update README if adding inputs
- Add integration test for new features
- quick-k8s - Kubernetes cluster deployment for GitHub Actions
- quick-ocp - OpenShift Local deployment for GitHub Actions
- jlumbroso/free-disk-space - Comprehensive cleanup (slower, more thorough)
This action extracts and generalizes proven cleanup strategies from quick-k8s and quick-ocp, making them available for any GitHub Actions workflow.