Design GitHub Actions

A CI/CD runner platform like GitHub Actions accepts a YAML workflow definition from a source repository, resolves it into a dependency graph of jobs, schedules those jobs onto ephemeral compute runners, streams logs back to the UI, and persists artifacts and caches. Millions of these workflows run every day across hundreds of thousands of repositories, on a fleet that scales from zero to tens of thousands of runners in seconds.

Functional requirements

• Workflow ingestion: accept a YAML file (push, PR, scheduled, manual dispatch) and produce a runnable job graph.
• Matrix expansion: fan a single job definition out across parameter combinations (e.g., OS × language version = N parallel jobs).
• Job scheduling: pick a runner (hosted or self-hosted), enforce per-account concurrency limits, respect priority tiers.
• Runner orchestration: lease ephemeral VMs or containers, ship the job manifest, tear down after completion.
• Log streaming: tail runner stdout to the UI with sub-second latency; persist for later viewing and search.
• Artifact and cache storage: content-addressable cache for build dependencies; artifact upload/download per run with TTL.

CI/CD capacity is driven by four axes: job throughput (peak jobs/sec), runner fleet size (concurrent VMs), log volume (bytes/sec streamed and persisted), and artifact/cache storage (the long tail of build outputs).

Scale assumptions

• 10M job executions per day platform-wide at steady state.
• Peak 300 jobs/sec (typical weekday 9am-5pm US/EU concurrent-active window).
• Average job duration: 3 minutes (mix of lints, unit tests, integration tests).
• Average matrix expansion: 4x (each workflow job produces 4 matrix legs on average, skewing toward cross-platform libraries).
• Repositories: 50M active, with long-tail distribution - 1% of repos drive 70% of job volume.
• Accounts: 5M active (mix of individuals, orgs, enterprises).

The API surface is scoped to three consumer types: source repos (webhook-in), runners (poll and heartbeat), and developers viewing the UI or CLI. Each has a different access pattern and security model.

Core endpoints

1POST   /v1/webhooks/{source}         # Inbound webhook (push, PR, schedule, dispatch)
2POST   /v1/workflow_runs             # Create a workflow run (manual dispatch)
3GET    /v1/workflow_runs/{run_id}    # Read run state + job tree
4GET    /v1/jobs/{job_id}             # Read a single job
5GET    /v1/jobs/{job_id}/logs        # WebSocket tail or HTTP read
6POST   /v1/runs/{run_id}/cancel      # User cancels a run
7POST   /v1/jobs/{job_id}/retry       # User retries a failed job
8
9POST   /v1/runners/register          # Self-hosted runner register
10GET    /v1/runners/{id}/next_job     # Runner long-polls for work
11POST   /v1/runners/{id}/heartbeat    # Runner keepalive
12POST   /v1/jobs/{id}/status          # Runner reports job status
13POST   /v1/runners/{id}/log_batch    # Runner uploads log chunk
14
15POST   /v1/caches                    # Runner uploads cache blob
16GET    /v1/caches?key=...            # Runner fetches cache
17POST   /v1/artifacts                 # Runner uploads artifact
18GET    /v1/artifacts/{id}            # Download artifact
19
20POST   /v1/oidc/token                # Runner requests OIDC JWT

The storage tier splits into three very different workloads, each matched to an appropriate database.

Control-plane (Postgres)

Strongly consistent, small-volume, relational. All the metadata about workflows, runs, jobs, runners, and scheduling lives here.

The platform is three tiers with very different scaling models.

1. Ingress tier - stateless, horizontally scaled, accepts webhooks and API requests.
2. Orchestration tier - stateful in the sense that it owns job DAGs and scheduler queues. Replicated for HA; leader election for scheduler fairness.
3. Execution tier - the runner fleet, elastic and loosely coupled. Runners pull work from the orchestrator; no inbound connections to runners.

Flow 1: Push triggers a workflow run end-to-end

Scenario: user pushes a commit to main. Repo has .github/workflows/ci.yml defining lint, test (matrix of OS × node), and deploy (needs test).

This section drills into three components that define the platform's behavior under load: the scheduler, the runner pool manager, and the log pipeline.

Scheduler

Every major decision in the platform is a trade-off. Here are the big ones.

Hosted vs self-hosted runners

The real failures, in decreasing order of pain.

Runner hangs mid-job

Scenario: a job's runner heartbeats stop. Job is at step 3 of 7; some logs streamed; no terminal status.

The CI/CD platform space is maturing. Here's where the frontier is going.

Workflow-native AI