Runners & Environments

Where your workflows actually execute — GitHub-hosted runners, self-hosted runners, and deployment environments.

🧒 Simple Explanation (ELI5)

Back to our kitchen analogy from the previous lessons. You've written your recipe (the workflow YAML) and listed all the dishes (jobs) and cooking steps. But where do you actually cook?

Runners are the kitchens where your recipes run. There are two types:

GitHub-hosted runners = renting a professional kitchen. Every time you need to cook, GitHub gives you a brand-new, spotless kitchen with all the standard tools already installed — pots, pans, knives, an oven. You cook your meal, serve it, and walk out. The kitchen is cleaned and demolished. Next time, you get a completely new one. It costs per hour of use, but you never worry about maintenance, cleaning, or broken equipment.

Self-hosted runners = your own kitchen at home. It's always there. You can customize it however you want — install a pizza oven, stock your favorite spices, add a deep fryer. There's no rental cost. But you maintain it. If the stove breaks, you fix it. If it gets dirty, you clean it. And if someone sneaky walks in through the back door and messes with your food — that's your security problem.

Then there are deployment environments — these aren't kitchens, they're dining rooms. You have a casual dining room (staging) where you taste-test the food before the big dinner. And you have the formal dining room (production) where actual guests eat. Before serving food in the formal room, a head chef (reviewer) has to approve it. Environments add gates and rules to where your code goes after it's built.

🔧 Technical — GitHub-Hosted Runners

GitHub-hosted runners are virtual machines managed entirely by GitHub. They're created fresh for each job, execute your steps, and are destroyed afterward. Zero state carries over between runs.

Available Runner Images

Hardware Specifications

Larger runners (4+ cores) are available on GitHub Team and Enterprise plans only. They're essential for heavy workloads like large Gradle builds, ML model training, or running dozens of parallel test containers.

Pre-Installed Software

GitHub-hosted runners come loaded with commonly used tools so you don't have to install them every run:

Ephemeral Nature

This is the most important characteristic of GitHub-hosted runners: every job gets a brand-new VM. When the job finishes, the VM is destroyed. This means:

• No files, caches, or environment variables persist between runs
• No risk of contamination from previous jobs (clean slate guarantee)
• You must re-clone your repo, re-install dependencies, and re-build from scratch every time
• To persist data between jobs, use artifacts (covered in Lesson 8) or caches

Syntax

jobs:
  build:
    # Use a GitHub-hosted Ubuntu runner
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Running on $(uname -a)"

  test-windows:
    # Use a GitHub-hosted Windows runner
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Running on Windows"
        shell: pwsh  # PowerShell Core on Windows

🔧 Technical — Self-Hosted Runners

Self-hosted runners are machines you own and manage that connect to GitHub Actions to execute workflow jobs. They can be physical servers, VMs, cloud instances, or containers — anything that can run the GitHub Actions runner application.

Why Use Self-Hosted Runners?

• Custom hardware: GPU for ML training, high-memory machines for large compilations, ARM architecture
• Specific OS: RHEL 8, Windows Server 2019, custom Linux distributions not available as GitHub-hosted images
• Network access: Connect to internal databases, private APIs, on-premises services behind firewalls
• Cost optimization: If you're running hundreds of CI minutes daily, dedicated machines can be cheaper than per-minute billing
• Compliance: Data residency requirements — code and artifacts never leave your infrastructure
• Pre-loaded tools: Large dependencies (SDKs, datasets, Docker images) already on disk — no download time each run

Setting Up a Self-Hosted Runner

Navigate to your repository (or organization) → Settings → Actions → Runners → New self-hosted runner. GitHub provides a script to download and configure the runner agent:

# Download the runner package (Linux x64 example)
mkdir actions-runner && cd actions-runner
curl -o actions-runner-linux-x64-2.311.0.tar.gz -L \
  https://github.com/actions/runner/releases/download/v2.311.0/actions-runner-linux-x64-2.311.0.tar.gz
tar xzf ./actions-runner-linux-x64-2.311.0.tar.gz

# Configure the runner — connects it to your repository
./config.sh --url https://github.com/YOUR-ORG/YOUR-REPO \
            --token YOUR-REGISTRATION-TOKEN

# Start the runner as a service (persists across reboots)
sudo ./svc.sh install
sudo ./svc.sh start

Labels

Every self-hosted runner has labels that workflows use to select it. Default labels are assigned automatically based on the machine: self-hosted, linux (or windows, macOS), and x64 (or ARM64). You can add custom labels like gpu, high-memory, production, or team-backend.

jobs:
  train-model:
    # Runs on a self-hosted Linux machine with a GPU
    # ALL labels must match — this is an AND condition
    runs-on: [self-hosted, linux, gpu]
    steps:
      - uses: actions/checkout@v4
      - run: nvidia-smi  # Verify GPU is available
      - run: python train.py

  standard-ci:
    # Falls back to a regular self-hosted Linux runner
    runs-on: [self-hosted, linux]
    steps:
      - uses: actions/checkout@v4
      - run: npm test

Runner Groups

At the organization level, you can create runner groups to control which repositories can use which runners. For example:

• production-runners group — only accessible by infrastructure repos
• ml-runners group — GPU machines restricted to the data-science team's repos
• general-ci group — available to all repositories in the org

Security Considerations

• Code injection: Workflow files from untrusted PRs can run arbitrary shell commands on the runner machine
• Persistence: Unlike GitHub-hosted runners, self-hosted runners are NOT ephemeral by default — previous job artifacts, environment variables, or malicious files may linger
• Mitigation: Use ephemeral runners (auto-delete after each job), run inside containers, limit network access, and never store secrets on the runner itself
• Configuration flag: --ephemeral during setup makes the runner deregister after a single job execution

Autoscaling with Actions Runner Controller (ARC)

For teams running many workflows, manually managing self-hosted runners doesn't scale. Actions Runner Controller (ARC) runs on Kubernetes and automatically provisions runner pods based on workflow demand:

# Simplified ARC RunnerDeployment (Kubernetes CRD)
apiVersion: actions.summerwind.dev/v1alpha1
kind: RunnerDeployment
metadata:
  name: ci-runners
spec:
  replicas: 1  # Minimum runners
  template:
    spec:
      repository: my-org/my-repo
      labels:
        - self-hosted
        - linux
        - ci
---
apiVersion: actions.summerwind.dev/v1alpha1
kind: HorizontalRunnerAutoscaler
metadata:
  name: ci-runners-autoscaler
spec:
  scaleTargetRef:
    name: ci-runners
  minReplicas: 1
  maxReplicas: 10
  metrics:
    - type: TotalNumberOfQueuedAndInProgressWorkflowRuns
      repositoryNames:
        - my-org/my-repo

When workflows queue up, ARC spins up new runner pods (up to the max). When the queue empties, it scales back down. Each runner pod is ephemeral — destroyed after one job, matching GitHub-hosted behavior.

📊 GitHub-Hosted vs. Self-Hosted — Comparison

🔧 Technical — Deployment Environments

Deployment environments are named targets that represent where your code gets deployed — development, staging, production. They're configured in your repository settings and referenced in workflow jobs to add protection rules, scoped secrets, and deployment tracking.

Creating Environments

Navigate to Settings → Environments → New environment. Give it a name (e.g., production). Then configure:

Protection Rules

Protection rules are gates that must be satisfied before a job targeting the environment can run:

Environment Secrets and Variables

Secrets and variables can be scoped to a specific environment. An environment secret named DB_PASSWORD in the production environment is only accessible to jobs that specify environment: production. This prevents staging jobs from accidentally using production credentials.

# Environment secrets override repository secrets with the same name.
# If both repo-level and environment-level DB_PASSWORD exist,
# the environment-level value wins for jobs targeting that environment.
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production  # This job can access production secrets
    steps:
      - run: echo "Connecting to ${{ secrets.DB_PASSWORD }}"
        # Uses the PRODUCTION DB_PASSWORD, not the repo-level one

Using environment: in a Workflow

The environment: key in a job definition links the job to a configured environment. You can also specify a url: that appears in the GitHub UI as a link to the deployed application:

name: Deploy Pipeline

on:
  push:
    branches: [main]

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    environment:
      name: staging
      url: https://staging.myapp.com
    steps:
      - uses: actions/checkout@v4
      - run: ./deploy.sh staging

  deploy-production:
    runs-on: ubuntu-latest
    needs: deploy-staging
    environment:
      name: production
      url: https://myapp.com
    steps:
      - uses: actions/checkout@v4
      - run: ./deploy.sh production

When deploy-production runs, it pauses and waits for a reviewer to approve (if required reviewers are configured). The reviewer sees a notification, can inspect the staging deployment, and then clicks Approve and deploy.

Deployment Activity

Every deployment to an environment is tracked in the Deployments section of your repository. You can see:

• Which commit was deployed, when, and by whom
• Active vs. inactive deployments (rollback visibility)
• Direct link to the workflow run that performed the deployment
• Environment URL — click through to see the live application

📊 Runner & Environment Flow

⌨️ Hands-on Exercises

Exercise 1: Compare Ubuntu vs. Windows Runners

Create a workflow that runs the same job on both ubuntu-latest and windows-latest to observe the environment differences:

name: Runner Comparison

on:
  workflow_dispatch:  # Manual trigger

jobs:
  compare:
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - name: OS Information
        run: |
          echo "Runner OS: ${{ runner.os }}"
          echo "Runner Arch: ${{ runner.arch }}"
          echo "Runner Name: ${{ runner.name }}"
          echo "Runner Temp: ${{ runner.temp }}"
          echo "Runner Tool Cache: ${{ runner.tool_cache }}"

      - name: List pre-installed tools
        run: |
          echo "--- Node.js ---"
          node --version
          echo "--- Python ---"
          python3 --version || python --version
          echo "--- Docker ---"
          docker --version || echo "Docker not available"
          echo "--- kubectl ---"
          kubectl version --client || echo "kubectl not available"
          echo "--- Helm ---"
          helm version || echo "Helm not available"
        shell: bash

What to verify: Trigger manually from Actions tab. You'll see two jobs — one on Ubuntu, one on Windows. Compare the installed tool versions, the working directory paths (/home/runner vs. C:\), and which tools are available on each OS.

Exercise 2: Add an Environment with Protection Rules

Set up a deployment environment with a manual approval gate:

1. Go to repository Settings → Environments → New environment
2. Name it production
3. Under Environment protection rules, enable Required reviewers and add yourself
4. Optionally add a Wait timer of 5 minutes
5. Under Deployment branches, select Selected branches and add main

Then create this workflow:

name: Deploy with Approval

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Building application..."
      - run: echo "Running tests..."

  deploy:
    runs-on: ubuntu-latest
    needs: build
    environment:
      name: production
      url: https://myapp.example.com
    steps:
      - uses: actions/checkout@v4
      - name: Deploy
        run: |
          echo "🚀 Deploying to production!"
          echo "Environment: ${{ github.event.deployment.environment }}"
          echo "Approved by a reviewer before reaching this point."

What to verify: Push to main. The build job completes immediately. The deploy job shows "Waiting for review" — click into it, approve it, and watch it run.

Exercise 3: Explore the runner Context

The runner context provides information about the machine executing the current job:

name: Runner Context Explorer

on: workflow_dispatch

jobs:
  explore:
    runs-on: ubuntu-latest
    steps:
      - name: Dump runner context
        run: |
          echo "runner.os = ${{ runner.os }}"          # Linux, Windows, or macOS
          echo "runner.arch = ${{ runner.arch }}"       # X64, ARM64
          echo "runner.name = ${{ runner.name }}"       # Runner machine name
          echo "runner.temp = ${{ runner.temp }}"       # Path to temp directory
          echo "runner.tool_cache = ${{ runner.tool_cache }}"  # Path to tool cache

      - name: Check disk space
        run: df -h

      - name: Check memory
        run: free -m

      - name: Check CPU
        run: lscpu | head -20

What to verify: Confirm the 2-core CPU, ~7 GB RAM, and ~14 GB disk. These match the documented specs for standard GitHub-hosted Linux runners.

🐛 Debugging Common Issues

Scenario: "No runner matching the specified labels was found"

The job sits in "Queued" and eventually fails with this error. GitHub cannot find a runner that matches your runs-on labels.

• Wrong labels: Your workflow says runs-on: [self-hosted, linux, gpu] but no registered runner has all three labels. Labels are AND-matched — the runner must have every label. Check your runner labels in Settings → Actions → Runners.
• Runner offline: The self-hosted runner is registered but not running. SSH into the machine and check the service: sudo ./svc.sh status. Restart if needed: sudo ./svc.sh start.
• Runner group restrictions: The runner is in a runner group that doesn't include your repository. Ask your org admin to update the group's repository access.
• Typo in label: runs-on: ubunut-latest (typo) won't match any GitHub-hosted runner. Double-check spelling.

Scenario: "Job queued but never starts"

The job shows "Queued" for an unusually long time without starting — minutes or even hours.

• GitHub-hosted: Check githubstatus.com for ongoing incidents. During peak times, macOS runners especially can have delays.
• Self-hosted: All available runners are busy executing other jobs. Queue builds up. Solutions: add more runners, use ARC for autoscaling, or limit concurrent jobs with concurrency:.
• Spending limit: On paid plans, if your account exceeds its spending limit for Actions, jobs will queue indefinitely until the limit is raised.
• Pending environment approval: If the job targets an environment with required reviewers, it will wait until someone approves. This looks like "queued" but is actually "waiting for review" — check the job details.

Scenario: "Environment protection rule — waiting for review"

The deployment job is paused, showing a yellow "Waiting" badge and a "Review deployments" button.

• Expected behavior: This means the environment has required reviewers configured and is working correctly. A designated reviewer must click "Review deployments", select the environment, and click "Approve and deploy".
• No notification received: Reviewers are notified via email and GitHub notifications. Check notification settings if you're not receiving them.
• Wrong reviewers: Only the people listed as required reviewers can approve. Check Settings → Environments → [environment name] → Required reviewers.
• Timeout: Pending reviews expire after 30 days. The workflow run will be cancelled if no one approves within that window.

🎯 Interview Questions

🌍 Real-World Use Case

A fintech company with 50+ engineers needed a CI/CD strategy that balanced speed, cost, compliance, and security across multiple project types.

The Challenge

The company had three categories of projects: (1) open-source client libraries published on npm/PyPI, (2) internal microservices handling payment processing, and (3) a data science team training fraud detection models. Each had different requirements:

• Open-source projects needed CI on every PR from external contributors — untrusted code
• Internal services required access to private VPC databases and APIs for integration tests
• ML pipelines needed GPU access for model training and couldn't use standard runners
• SOC 2 compliance required audit trails for all production deployments

The Solution

The Results

• Security: Zero incidents — untrusted PR code never ran on internal infrastructure
• Cost: $180/month total: $80 in GitHub Actions minutes (open-source) + $100 in GPU instance costs (ML, autoscaled). Down from $400+/month when everything ran on GitHub-hosted larger runners.
• Compliance: Every production deployment tracked with reviewer name, approval timestamp, and commit SHA. Audit-ready for SOC 2.
• Speed: Internal integration tests dropped from 8 minutes (GitHub-hosted, no VPC access workarounds) to 2 minutes (self-hosted, direct VPC access).
• Developer experience: Teams choose runners by setting runs-on: labels — no infrastructure tickets needed.

📝 Summary

• GitHub-hosted runners are ephemeral VMs managed by GitHub — zero maintenance, fresh every run, pre-loaded with tools, billed per minute
• Available images: ubuntu-latest, ubuntu-24.04, windows-latest, macos-latest, macos-14 (M1). Standard: 2-core, 7 GB RAM, 14 GB SSD
• Self-hosted runners are machines you manage — custom hardware, private network access, cost savings at scale, but full maintenance responsibility
• Self-hosted runners use labels (runs-on: [self-hosted, linux, gpu]) for job routing. Never use on public repos
• Actions Runner Controller (ARC) autoscales self-hosted runners on Kubernetes based on workflow demand
• Deployment environments are named targets (staging, production) with protection rules, scoped secrets, and deployment tracking
• Protection rules include required reviewers, wait timers, and branch restrictions — creating approval gates for sensitive deployments
• Environment secrets override repository secrets and are only accessible to jobs targeting that environment
• The runner context (runner.os, runner.arch, runner.name) provides runtime information about the executing machine
• Hybrid strategies work best: GitHub-hosted for standard CI and public repos, self-hosted for specialized hardware and private network access