Debugging Github Actions - The right way

Debug your GitHub Actions using real data, not guesswork

Hello Everyone

Welcome to your AKVAverse, I’m Abhishek Veeramalla, aka the AKVAman, your guide for Cloud, DevOps, and AI.

GitHub Actions is at the heart of modern CI/CD, but when jobs fail without explanation, teams lose time and trust in their pipelines. Rerunning flaky jobs or digging endlessly through logs is frustrating and slows down delivery.

The tricky part is knowing if the failure is really in your code or if the runner simply ran out of memory or CPU. Basic logging commands can help, and external tools like DataDog provide deeper visibility, but both add extra work.

The Challenges of Debugging GitHub Actions

Debugging failed workflows in GitHub Actions is not straightforward. Pipelines run in ephemeral environments, which means system state is lost as soon as the job completes. Logs provide some information, but they often fail to answer the most important questions:

• Did the runner run out of memory or CPU?

• Was the failure caused by application code or infrastructure limits?

• At what stage in the workflow did the problem occur?

• Are failures consistent across runs, or do they appear sporadically?

Without clear answers, engineers fall into a cycle of re-running jobs, adding ad hoc debug commands, or relying on trial-and-error changes to the pipeline. This wastes time and undermines trust in the CI/CD system.

Traditional Debugging Approaches

Most teams start with one of two methods:

1. Inline diagnostic commands
Adding simple commands such as

free -h
df -h
uptime

These provide visibility into memory, disk, and uptime during a job. While useful, this approach becomes unmanageable as workflows scale. Logs grow noisy, scattered across multiple jobs, and patterns are difficult to track.

2. External observability tools
Platforms like DataDog or Prometheus can integrate with GitHub Actions. They provide dashboards, metrics, and long-term trends. However, they introduce overhead: managing agents, handling API keys, and in many cases, migrating to self-hosted runners. The complexity often outweighs the benefit for teams that simply need to identify the root causes of job failures.

It comes down to a trade-off: minimal inline logs on one side, and complex observability setups on the other, neither being the perfect solution.

Observability Built into the Runner: Depot

A more effective approach is to capture observability data directly within the runner. This removes the need for constant YAML changes and avoids the overhead of managing separate monitoring systems.

Depot takes this approach a step further. While it is known for speeding up builds, it also delivers detailed visibility straight inside GitHub Actions jobs. Instead of stitching together multiple tools, you get insights right where they’re needed.

I tried Depot on my own GitHub Actions runner, and the improvement in visibility for each job is insane

CPU and memory usage across the job lifecycle
Depot showed me how resources were consumed from start to finish, making it easy to spot whether issues came from spikes or sustained load. Over time, I could also see if jobs were gradually getting heavier with each release.

Step-level resource breakdown
Instead of simply reporting that a job failed, Depot highlighted the exact step dependency installation, testing, or building that pushed the runner too far. This made optimization intentional rather than guesswork for me.

Pinpoint out-of-memory timing
When a job failed due to memory limits, Depot showed me the precise moment it happened. No log hunting and gave clarity on whether it was an application issue or a runner limitation.

Process-level insights
Depot drilled down to the process level, showing me which specific commands were consuming the most CPU or memory. This allowed me to isolate the real culprit without reworking the entire pipeline.

View of metrics panel

Streamlining the Debugging Process

With Depot, debugging becomes a structured process based on data rather than guesswork. For example:

• Memory issues: Quickly see if crashes are caused by code problems or runner exhaustion, then fix with caching or smaller jobs.

• Slow builds: Step-level CPU metrics reveal exactly where time is lost install, compile, or package so you optimize the right place.

• Flaky jobs: Spot repeating resource patterns across runs and uncover the real cause instead of writing failures off as random.

• Scaling: Base scaling decisions on real CPU and memory usage, avoiding the cost of oversized runners.

Out of memory indicator for GitHub Actions job

A Thought to Leave You With

CI/CD failures are unavoidable in software development. The key is to quickly and confidently identify the cause. Logs alone are often insufficient, and external monitoring can be overly complex.

Depot bridges this gap by integrating observability into the runner itself, providing clear visibility without the need for scripts or complex setups. This results in less time spent guessing, more time building, and a more reliable pipeline.

With Depot, debugging GitHub Actions becomes a source of clarity and confidence, enabling teams to ship software faster and more efficiently.

Check out a detailed blog for the Depot here:

Start small, stay curious, and get hands-on.

Until next time, keep building, keep experimenting, and keep exploring your AKVAverse. 💙

Thanks Depot, for collaborating on this deep dive.

Abhishek Veeramalla, aka the AKVAman