Design GitHub Actions: A CI/CD Platform for Untrusted Code

Workflows start from events: a push, a pull request, a cron schedule or a manual dispatch from the UI. Each workflow is defined in a YAML file stored in the repository, made of jobs that contain ordered steps. Jobs can declare needs on other jobs to form a dependency chain, and a matrix expands one job definition into many variants, such as testing on three operating systems and four language versions.

Jobs execute on runners, which are either machines we host or machines the customer registers and operates inside their own network. While a job runs, users watch its logs live; afterwards they can download artifacts like compiled binaries or test reports. The overall result is posted back as a pass or fail check on the pull request, which is what developers look at most.

Isolation is the first requirement because the platform's entire purpose is to run code from strangers. A job must have no way to observe another tenant's processes, files or secrets. Reliability comes next: each qualifying event should produce exactly one run, and if a runner crashes mid-job the system must detect it instead of leaving a check stuck in the pending state forever.

Start latency shapes the developer experience. Someone waiting on a pull request expects work to begin within about 30 seconds of queueing. Fairness protects the shared fleet: an enterprise that pushes a thousand jobs at once should be capped by per-organisation limits so that a small team's single build is not stuck behind it.

Assume around 100 million pushes and pull requests per day, which is about 1.2K events per second. A share of them match workflows and produce roughly 20 million jobs daily, or about 230 per second on average and near 1K at peak. If an average job runs for about five minutes, then 230 per second times 300 seconds means roughly 70K jobs are executing at any instant, each needing a dedicated machine.

Logs add up quickly as well. At about 1 MB per job, the platform writes around 20 TB of log data every day, before counting artifacts. These figures make the cost centre obvious: tens of thousands of concurrently running machines. The design must schedule them efficiently, scale the pool up and down quickly, and recycle capacity without ever letting one tenant's leftovers reach the next.

Four entities structure the system. A Workflow is the YAML definition, a Run is one execution of it triggered by an event, a Job is a unit of work inside a run, and a Runner is the machine that executes jobs. Runs and jobs carry state such as queued, in progress, succeeded or failed.

The Git service posts every repository event to POST /events with the repo, event type, ref and commit SHA. Users can trigger a run manually through POST /workflows/{id}/dispatches with a branch and inputs. Runners fetch work through GET /runner/jobs?wait=50s, a long poll that holds the request open until a job is available and returns the job definition plus a short-lived job_token. Browsers call GET /jobs/{id}/logs to follow output as it is produced.

Each push or pull request in the Git service is published to Kafka, which acts as a durable event bus so nothing is dropped if a downstream component restarts. The orchestrator consumes these events, locates the workflow files whose triggers match, and expands them into a run containing jobs. All run and job state is persisted in the run database.

Jobs whose dependencies are satisfied are placed in a job queue partitioned by runner label, for example ubuntu, windows or a customer's self-hosted pool. Runners long-poll the queue for their label, take a job, execute its steps in order and report the outcome. An autoscaler monitors queue depth, booting more runner VMs when jobs start to wait and shrinking the pool when demand falls.

During execution, the runner sends log lines to the log service, which streams them to anyone watching and eventually persists them, together with uploaded artifacts, in blob storage. Keeping this traffic on its own path means a burst of noisy builds cannot slow down scheduling.

Kafka may deliver an event more than once, so the orchestrator first deduplicates on the event's delivery ID; a single push must yield a single run. It then reads the workflow files exactly as they exist at the triggering commit, not at the branch head, and evaluates their trigger filters such as branch patterns and changed file paths.

Matching workflows are expanded into a job graph. A matrix of three operating systems by four versions becomes twelve independent jobs, while a job declaring needs stays blocked until its prerequisites succeed. Only jobs with no unfinished dependencies are enqueued, and each organisation's concurrency limit is applied at this point. When a newer push lands on the same branch, the older run can be cancelled to avoid wasting runners on stale code.

As jobs complete, the orchestrator unblocks and enqueues their dependents. Every running job holds a lease that the runner renews with heartbeats; if the heartbeats stop, the lease expires and the job is retried or marked failed, so a crashed machine never leaves a run hanging.

A small fleet of long-lived machines that run job after job gives instant starts, but files, caches and stray processes from one customer can be found by the next, which is unacceptable for untrusted code. Containers on a shared host are fast and pack densely, yet every container shares the host kernel, so a single kernel exploit could cross tenant boundaries.

A fresh virtual machine for every job, destroyed when the job ends, provides hardware-level isolation and a guaranteed clean environment, so it is the chosen option. Its weakness is boot time. The autoscaler counters that with a warm pool of pre-booted VMs per runner label, sized from recent demand, so a queued job is assigned to an already running machine in seconds.

Each secret is delivered solely to the job that references it, and any occurrence of its value in log output is replaced with asterisks. For deployments to cloud providers, jobs exchange a signed identity for short-lived OIDC credentials, which removes the need to store long-lived cloud keys in the platform at all.

Runners batch log output into small chunks and send one roughly every second. The log service fans each chunk out to anyone currently viewing that job, giving the browser a near-live stream. When the job finishes, the chunks are assembled into one file per step and written to blob storage, after which the in-memory live buffer can be released.

Artifacts can reach hundreds of megabytes, so runners request a signed URL and upload directly to blob storage rather than streaming bytes through the API tier. A dependency cache whose key is derived from hashing the lock file lets later builds restore packages instead of downloading them again, which shortens jobs and reduces runner minutes. Retention rules delete logs and artifacts after a period such as 90 days; without them, 20 TB per day would grow without limit.

Fresh VMs are far safer than containers, at the price of higher cost per job and slower cold starts. The size of the warm pool trades start latency against paying for idle machines. Long polling lets self-hosted runners behind corporate firewalls work with only outbound connections, though it adds a little delay compared with pushing work to them.

Retention length balances debugging value against steadily rising storage bills. The overall philosophy: keep events durable, apply fairness in the queues, treat machines as disposable, and move log handling off the critical path of job execution.