A normal log says: Cache restored from key: Linux-node-abc123
A debug-action-cache log says:
[debug] Checking cache for key: Linux-node-abc123
[debug] restoreKeys: [ 'Linux-node-' ]
[debug] Cache service URL: https://artifactcache.actions.githubusercontent.com/...
[debug] Request headers: Authorization: 'Bearer ***', Accept: 'application/json'
[debug] GET response: 404 (Not Found)
[debug] Trying restore key: Linux-node-
[debug] GET response: 200 OK
[debug] Cache found: cacheKey: 'Linux-node-def456', archiveLocation: 'https://...'
[debug] Downloading 234MB archive...
[debug] Extracting to /home/runner/work/repo/node_modules
Suddenly, you see why the wrong cache was restored (because the exact key failed, so it fell back to a prefix).
The actions/cache action outputs a boolean variable named cache-hit. You can print this to verify if the restoration actually succeeded.
- name: Cache Node Modules
uses: actions/cache@v3
id: cache-npm
with:
path: node_modules
key: $ runner.os -node-$ hashFiles('**/package-lock.json')
restore-keys: |
$ runner.os -node-
While the Debug Action Cache offers several benefits, there are potential issues to consider: debug-action-cache
GitHub Actions has a built-in mechanism to increase log verbosity.
When you re-run the workflow, actions/cache will output detailed information about tar creation, size calculations, and upload/download processes.
In the context of Continuous Integration (CI) with GitHub Actions, the term debug-action-cache usually refers to the process of troubleshooting the GitHub Actions Cache mechanism. Developers often encounter issues where caches are not saving, not restoring, or growing too large.
This write-up covers the mechanics of the cache, common failure modes, and actionable strategies to debug caching issues. A normal log says: Cache restored from key:
Self-hosted runners can persist caches on disk. debug-action-cache here means inspecting the runner's local drive.
# On the self-hosted machine
sudo find / -name "node_modules" -path "*/actions-runner/_work/*" -type d
You might find that previous jobs did not clean up, and the restore step is simply finding a local folder, bypassing the remote cache entirely.
debug-action-cache is not a standalone command but rather a diagnostic technique used to inspect, validate, and troubleshoot how GitHub Actions (or similar CI systems) save and restore cached dependencies, build artifacts, or intermediate files. It helps answer:
"Why is my cache miss happening?" or "What exactly is stored in this cache?"
It typically involves:
In the world of modern DevOps, speed is currency. Every minute your Continuous Integration (CI) pipeline runs costs money and slows down developer feedback loops. GitHub Actions introduced caching to solve this—storing dependencies like node_modules, pip, or apt packages to avoid re-downloading them on every run.
But what happens when caching breaks? What happens when your cache restore takes 10 minutes, or worse, corrupts your build?
Enter the niche but powerful workflow debugging tool: debug-action-cache. This isn't just a command; it is a mindset and a technical methodology for introspecting one of the most opaque parts of GitHub’s ecosystem.
In this 2,500+ word guide, we will dissect the anatomy of action caching, explore why debugging is necessary, and provide a step-by-step playbook to master debug-action-cache. Suddenly, you see why the wrong cache was