When you run one of the world’s largest code hosting platforms on its own infrastructure, you face a unique challenge: if the site goes down, you lose access to the very code you need to fix it. This self-referential dependency—known as a circular dependency—can turn a routine outage into a crisis. In this article, we explore seven critical insights from GitHub’s engineering team on how they leverage eBPF (extended Berkeley Packet Filter) to break these cycles and ensure deployment safety. From identifying hidden dependencies to writing custom eBPF programs, you’ll learn how GitHub protects its production environment from accidental circular traps.
1. The Self-Hosting Dilemma | 2. Three Types of Circular Dependencies | 3. Why Manual Reviews Fall Short | 4. Enter eBPF: A Lightweight Supervisor | 5. Building Your First eBPF Deployment Guard | 6. Scaling eBPF Across Thousands of Hosts | 7. The Future: Beyond Deployment Safety
1. The Self-Hosting Dilemma
GitHub runs its own source code on github.com. This dogfooding approach allows the company to test changes before they reach millions of users. But it creates a classic circular dependency: to deploy a fix for GitHub, engineers need access to GitHub itself. If an outage knocks the platform offline, all deployment activities grind to a halt. GitHub mitigates this by maintaining an external mirror of critical code and pre-built assets for rollbacks. Yet even with these precautions, deployment scripts can still introduce unexpected circular dependencies—for example, attempting to download a binary from GitHub during an outage. This is the fundamental problem that eBPF helps solve.
2. Three Types of Circular Dependencies
Consider a MySQL outage that causes GitHub to serve release data incorrectly. A deploy script on the affected nodes might try to pull an open source tool from GitHub—that's a direct dependency. A hidden dependency occurs when a tool already on disk checks for an update online, hanging the script. A transient dependency arises when the script calls an internal service that itself tries to fetch a binary from GitHub. These three categories show that deployment dependencies aren't always obvious. They can hide in tooling, network calls, or third-party APIs. Traditional monitoring often misses them until a real outage strikes. GitHub needed a way to detect and block these calls automatically, without modifying every script.
3. Why Manual Reviews Fall Short
Historically, each team review their deployment scripts to identify circular dependencies. This process is error-prone and unscalable: teams may not recognize indirect dependencies, and scripts change frequently. Moreover, a script that passes review in a normal environment may behave differently during an incident when network services behave unpredictably. GitHub realized they needed a runtime enforcement mechanism—a way to intercept and block specific system calls during deployment. This is where eBPF shines. It allows for fine-grained, kernel-level introspection without changing application code. By observing every system call, eBPF can spot risky patterns (like a DNS lookup to github.com during a deploy) and either log or block them.
4. Enter eBPF: A Lightweight Supervisor
eBPF is a technology that enables running sandboxed programs inside the Linux kernel. It’s used for performance tracing, security, and now deployment safety. GitHub engineers wrote eBPF programs that hook into network and filesystem syscalls. For example, they can intercept connect() calls to specific IP ranges or DNS queries for internal services. If a deployment script tries to access GitHub’s release servers during an incident, eBPF can block that call immediately. Because eBPF runs in the kernel, it adds minimal overhead (<5% CPU) and works across all processes on a host. This makes it an ideal supervisor for deployment scripts that must run in isolation from external dependencies.
5. Building Your First eBPF Deployment Guard
GitHub shared a simplified example: an eBPF program that monitors IPv4 outgoing connections. The program checks each connect syscall against a list of forbidden destinations (like GitHub’s IP ranges) during a deployment window. Using tools like bpftrace or the libbpf library, you can write a program that attaches to a kprobe or tracepoint. Here’s a skeletal approach in C: attach to connect, read the sockaddr structure, compare the IP to a blacklist, and return appropriate actions (e.g., deny or log). The same logic can extend to DNS lookups using uretprobe on the resolver. GitHub’s implementation also accounts for transient dependencies by recursively tracking process ancestry—if a child process spawned by the deploy script attempts a forbidden call, it gets blocked too.
6. Scaling eBPF Across Thousands of Hosts
Deploying eBPF at GitHub’s scale required careful management. Each host runs a lightweight agent that loads eBPF programs at boot or when a deployment starts. The agent receives policy updates from a central service, ensuring forbidden destinations are consistent across all nodes. Logs from blocked calls are sent to a centralized monitoring system, giving teams real-time visibility into attempted circular dependencies. GitHub also handles edge cases: if the deployment itself depends on a service that temporarily becomes unavailable (e.g., a config server), the eBPF program must distinguish between expected network calls and true dependencies. They use allowlist overrides for known good endpoints, but revoke them during incident scenarios. This dynamic policy approach keeps deployments safe without breaking legitimate functionality.
7. The Future: Beyond Deployment Safety
With eBPF now a core part of deployment safety, GitHub is exploring wider uses. For instance, eBPF can monitor disk I/O during upgrades to detect unexpected writes to stateful databases, or enforce file access patterns to prevent data corruption. The same technology could validate that rolling back a release doesn’t reintroduce old dependencies. More broadly, eBPF offers a new paradigm: enforce policy at the kernel level, independent of application frameworks. GitHub hopes to open-source some of the eBPF tooling for deployment safety, enabling the community to adapt it for their own infrastructure. By sharing their journey, they demonstrate how a clever use of existing kernel features can solve one of the oldest problems in self-hosted operations.
Conclusion
GitHub’s use of eBPF to break circular dependencies shows that sometimes the most elegant solutions come from deep kernel integration. By moving enforcement from human review to runtime kernel checks, they achieved a level of deployment safety that was previously impossible at scale. The three types of dependencies—direct, hidden, and transient—are now automatically neutralized, allowing GitHub to recover from outages faster and more reliably. If your organization faces similar self-hosting challenges, consider adopting eBPF as a lightweight deployment supervisor. It’s open, programmable, and remarkably efficient. As GitHub continues to refine this approach, we can expect even smarter incident response and more resilient infrastructure across the industry.