Documentation / Core Concepts / How WorkerRun Works

How WorkerRun Works

From webhook to execution in milliseconds — choose V8 isolates for speed or containers for full OS access.

Request Flow

GitHub Webhook

Job queued event

↓

WorkerRun

Quota check + JIT registration

↓

Queue

Cloudflare Queue

V8 Mode↓

V8 Isolate

Worker Loader execution

Container Mode↓

Sandbox DO

Ubuntu container

↓

GitHub API

Report results

Step by Step

1

Webhook received

GitHub sends a webhook when a workflow job is queued with runs-on: worker-run (V8 mode) or runs-on: worker-run/instance-type=lite (Container mode).

2

Quota check & JIT registration

WorkerRun validates the organization's quota, then registers a just-in-time (JIT) runner with the GitHub API to claim the job.

3

Job queued

The job is dispatched to a Cloudflare Queue for reliable processing.

4

Execution session

A RunnerSession is created. In V8 mode, each step runs in a fresh V8 isolate via Worker Loader sub-workers. In Container mode, steps execute inside a real Ubuntu container powered by Cloudflare Sandbox SDK.

5

Results reported

Step outcomes, annotations, and outputs are reported back to GitHub via the Checks API in real time as each step completes.

Execution Modes

V8 Isolation Mode

runs-on: worker-run

The default mode. Jobs run inside V8 isolates on Cloudflare Workers with millisecond startup times. Shell steps are executed via @cloudflare/shell with 80+ built-in commands. Supports Node.js actions, composite actions, pre/post lifecycle hooks, if: conditions, and continue-on-error. Best for lightweight automation tasks.

  • -Millisecond cold start
  • -Node.js actions (node12/16/20/24) and composite actions
  • -80+ built-in shell commands (curl, jq, grep, sed, awk, etc.)
  • -Full expression evaluation (contains, startsWith, endsWith, format, fromJSON, toJSON, hashFiles)
  • -Pre/post lifecycle hooks, if: conditions, continue-on-error
  • -In-memory ephemeral filesystem

Container Mode

runs-on: worker-run/instance-type=lite

Jobs run in real Ubuntu containers via Cloudflare Sandbox SDK. Supports full bash, real filesystem, git, npm, and more. Choose from multiple instance types: lite, basic, standard-1 through standard-4. Docker-based actions are available on standard-2 and higher.

  • -Full bash shell environment
  • -Real persistent filesystem with git, npm, etc.
  • -actions/checkout@v4 works out of the box
  • -Composite actions and pre/post lifecycle hooks
  • -Docker-based actions (standard-2+ instance types)
  • -No per-step timeout limitation
  • -Everything V8 mode supports, plus external binaries

When to Use V8 vs Container

V8 Isolation Mode

runs-on: worker-run
  • -PR labeling, merge checks, posting comments
  • -API calls and webhook automation
  • -Shell scripts using built-in commands (curl, jq, grep, sed, etc.)
  • -Any Node.js or composite action that does not need external binaries
  • -Tasks where millisecond startup time matters

Container Mode (lite / basic)

runs-on: worker-run/instance-type=lite
  • -Building and testing with npm, node, python, etc.
  • -Checking out code with actions/checkout@v4
  • -Running arbitrary scripts that need a full OS
  • -CI/CD pipelines with multiple build steps

Container Mode (standard-2+)

runs-on: worker-run/instance-type=standard-2
  • -Workflows that use Docker-based actions
  • -Building Docker images
  • -Resource-intensive builds and tests

Why Cloudflare Workers?

  • Global network — Workers run in 300+ data centers worldwide, close to where webhooks originate.
  • Millisecond startup — V8 isolates start in under 5 ms. No cold boot of a VM or container for lightweight jobs.
  • V8 isolates built-in — Each job gets its own isolate with hardware-level memory isolation, the same technology that powers Chrome tabs.
  • Sandbox SDK — For jobs that need a full OS, Cloudflare Sandbox SDK provides real Ubuntu containers with near-instant provisioning on the same global network.