I Pushed Code for Years Without Understanding What Happened Next

I remember the exact moment I realized I had no idea how my CI pipeline actually worked. I was debugging a flaky test in our staging environment, and a senior developer asked me: "Where is this test running?" I said "GitHub Actions." He asked: "On what machine?" Silence. I honestly didn't know if it was GitHub's machine, my company's machine, or some mystery third party. I just knew that when I pushed code, tests ran somewhere and either passed or failed.

That gap in my understanding bothered me. I've been shipping production code for years. I've written dozens of workflows. But I was operating at a surface level—copy-pasting YAML from documentation, tweaking environment variables, running things on my machine locally before pushing. I was cargo-culting my own pipeline. So when I came across this explanation of how GitHub Actions actually connects a git push to actual execution, it forced me to slow down and build a mental model from first principles.

The Event Nobody Thinks About

Here's the thing that clicked for me: nothing happens when you push code. That sounds counterintuitive, but it's true.

Your commits land on GitHub. The branch pointer updates. And then... silence. GitHub doesn't magically know or care that your repository has CI set up. GitHub runs millions of repos. Most of them don't have CI at all.

What actually kicks off a pipeline is a webhook—a mechanism I understood in theory but never really connected to my daily workflow. When you push, GitHub fires an event. It then checks: has anyone registered to care about this event? If a service has registered a webhook URL, GitHub sends an HTTP POST to that address with the commit details. This is how external services like Slack bots and monitoring tools get notified. This is also, conceptually, how GitHub Actions gets triggered.

For years I thought of GitHub Actions as some magical integration built into GitHub. Technically it's more tightly coupled than a third-party webhook—GitHub doesn't POST to itself over the internet—but the mental model is the same. Event happens. Something is listening. That something decides what to do.

Your Workflow File Is the Real Contract

This is what actually bothered me about the YAML-first approach: I write these files, but I never questioned why it has to be YAML instead of JavaScript or Python.

The answer is trust and constraint. A JavaScript file in your repo can do anything—delete files, make network calls, open sockets. You're asking GitHub to run that on their infrastructure for millions of repositories. A lot of them are public. A lot are from strangers.

YAML is deliberately restrictive. It's declarative, not executable. You describe what you want to happen: "Run these steps, in this order, on this type of machine." You can't write a while loop. You can't open a socket. The format itself prevents certain classes of attacks.

Do I think YAML is perfect for this job? No. YAML is verbose and fragile—whitespace matters in ways that trip everyone up. But I get why GitHub chose it. The alternative is "let anyone run arbitrary code on our infrastructure," which doesn't scale.

My Take: The Gap Between "Works" and "Understand"

I've spent enough time debugging production issues to know that understanding the mechanism matters. It won't make you a better developer every day. But when something breaks, or when you need to optimize, or when you're debugging a flaky test that only fails in CI, that mental model is invaluable.

What I still want to understand better is how GitHub Actions actually allocates runners. That's where the magic gets real—someone's machine is actually executing my code. Is it ephemeral? Does my job queue if the queue is full? Can I see logs of what actually ran? The webhook and workflow discovery are elegant, but the execution layer is where things get complicated.

Here's a practical example of what I mean: if I have a workflow that runs every push, and I push 10 commits at once, do all 10 run in parallel or queue sequentially? I think I know the answer based on my experience, but I shouldn't have to guess.

Your Turn

Next time you push code and your tests run, take 30 seconds to trace the actual path: your commit arrives, a webhook fires, GitHub finds your workflow file, the workflow describes what to run, and something executes it. Most developers never think about this chain. Understanding it won't change your daily work, but it'll make you a more deliberate developer.

What's one thing about your CI setup you've never fully understood? I'm curious if others have that same gap between "it works" and "I know why it works."

Source: This post was inspired by "Episode 2 — Who Actually Runs My Pipeline?" by Dev.to. Read the original article