Runners: Hosted and Self-hosted

Runners: Hosted and Self-hosted

A runner is the compute environment that accepts a job and executes its steps. GitHub-hosted runners offer fresh managed virtual machines and broad toolsets. Self-hosted runners provide custom hardware, network access, or software, but the organization owns patching, isolation, scaling, and incident response.

Core ideas

• runs-on selects a runner using a hosted image label, custom labels, a group, or a combination.
• Hosted runners are generally ephemeral; persistent self-hosted machines can retain files and compromised state between jobs.
• Runner groups restrict which organizations or repositories may schedule work on a pool.
• Ephemeral autoscaled runners reduce persistence and make clean builds easier to guarantee.

How it works

Match the runner trust level to the code being executed. Pull requests from forks can contain hostile build instructions, so do not route untrusted code to a privileged runner with internal network access. Prefer isolated, short-lived workers with minimal credentials and egress controls.

Configuration example

jobs:
  linux-build:
    runs-on: ubuntu-latest
    steps:
      - run: uname -a

  internal-package:
    runs-on:
      group: production-builders
      labels: [self-hosted, linux, x64]
    steps:
      - run: ./gradlew publish

Read the example from top to bottom: the trigger creates a run, the job requests a runner, and each step receives only the context configured for it. Adapt names, versions, permissions, and commands to the repository rather than copying production credentials or policies blindly.

Production guidance

• Patch the runner OS, runner application, compilers, and preinstalled tools on a defined schedule.
• Avoid registering a self-hosted runner at broader scope than necessary.
• Monitor queue time, disk pressure, job failures, and unexpected outbound connections.

The chapter quiz follows this lesson and checks both the vocabulary and the operational decisions behind the configuration.