Runners

What are self-hosted runners?

Understanding self-hosted CI/CD runners and when to use them

Self-hosted runners are compute instances that you manage and maintain, used to execute CI/CD workflows and pipelines. Unlike cloud-hosted runners provided by CI/CD platforms, self-hosted runners run on your own infrastructure.

How self-hosted runners work#

When you configure a self-hosted runner, it connects to your CI/CD platform and waits for jobs to execute. When a workflow or pipeline triggers a job that's configured to run on your self-hosted runner, the platform sends the job to your runner, which executes it and reports the results back to the platform.

1
┌─────────────────┐
2
│  Your Platform  │  GitHub Actions, GitLab, Jenkins, etc.
3
│  (GitHub, etc.) │
4
└────────┬────────┘
5
         │ Sends jobs
6
         │
7
┌────────▼────────────────┐
8
│  Self-Hosted Runner     │
9
│  (Your Infrastructure)  │
10
│                         │
11
│  ┌───────────────────┐  │
12
│  │ Execute Job       │  │
13
│  │ - Run tests       │  │
14
│  │ - Build artifacts │  │
15
│  │ - Deploy app      │  │
16
│  └───────────────────┘  │
17
└────────┬────────────────┘
18
         │ Reports results
19
         │
20
┌────────▼────────────┐
21
│ Platform Dashboard  │
22
│ (View results)      │
23
└─────────────────────┘

Cloud-hosted vs self-hosted runners#

AspectCloud-hosted runnersSelf-hosted runners
SetupInstant, no configurationRequires server setup and configuration
CostPer-minute billingFixed infrastructure cost
CustomizationLimited optionsComplete control
MaintenanceManaged by platformYour responsibility
PerformanceVaries by locationDepends on your hardware
SecurityPlatform managedYour responsibility
NetworkPublic internetPrivate network possible
TimeoutUsually 6 hoursConfigurable or unlimited

When to use self-hosted runners#

Good for self-hosted runners:

  • Long-running jobs (>6 hours) that exceed cloud-hosted timeouts
  • Resource-intensive workloads (compilation, video processing, ML training)
  • Private networks with strict security requirements
  • Cost optimization for frequent CI/CD runs
  • Custom tooling requiring specific software or configurations
  • High-performance needs requiring dedicated hardware
  • Compliance requirements mandating on-premises execution
  • Air-gapped environments without internet connectivity

Better with cloud-hosted runners:

  • Quick tests with simple requirements
  • Open-source projects with unpredictable workload
  • Minimal maintenance desired
  • Scaling up and down based on demand
  • Multi-platform builds needing various OS support

Key concepts#

Runner (or Agent)#

The software running on your infrastructure that connects to your CI/CD platform and executes jobs.

Compute Instance#

The server or computer that runs the self-hosted runner software. Can be physical hardware, VM, or container.

Job#

A set of steps that run on a single runner instance as part of a workflow or pipeline.

Executor (GitLab) / Executors (Jenkins)#

The method used to execute jobs (e.g., shell, Docker, Kubernetes).

Registration#

The process of connecting a runner to your CI/CD platform, establishing trust and credentials.

Labels / Tags#

Identifiers used to route specific jobs to specific runners based on capabilities.

Getting started with self-hosted runners#

  1. Choose your platform - GitHub Actions, GitLab, Jenkins, or another CI/CD system
  2. Prepare infrastructure - Physical server, VM, cloud instance, or container
  3. Install runner software - Download and install the runner agent
  4. Register runner - Connect it to your CI/CD platform
  5. Configure settings - Labels, tags, and job policies
  6. Run first job - Test with a simple workflow or pipeline
  7. Iterate and optimize - Add more runners, optimize for performance

Next steps#