Skip to main content

Configuring GitHub-Hosted Runners

1. Using GitHub-Hosted Runners

Runner Specification Notes
ubuntu-latest ubuntu-22.04 Latest Ubuntu image with pre-installed tools
ubuntu-22.04 ubuntu-22.04 Ubuntu 22.04 LTS with pre-installed tools
ubuntu-20.04 ubuntu-20.04 Ubuntu 20.04 LTS with pre-installed tools
macos-latest macOS-13 Latest macOS with pre-installed tools
macos-13 macOS-13 macOS 13 with pre-installed tools
windows-latest windows-2022 Latest Windows image with pre-installed tools
windows-2022 Windows-2022 Windows Server 2022 with pre">%20pre-installed%20tools

Example: Using ubuntu-latest runner

name: Build
on:
  push:
    branches: [ main ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
Note: GitHub-hosted runners provide a clean, isolated environment for each job. They are automatically provisioned and cleaned up after each run.

2. Specifying Runner OS

Option Values Notes
runner.os ubuntu-latest, ubuntu-22.04, ubuntu-20.04 Default Linux runner
runner.os macos-latest, macos-13, macos-12 Default macOS runner
runner.os windows-latest, windows-2022, windows-2019 Default Windows runner

Example: Setting OS for workflow

name: Build
on Ubuntu
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

3. Using Latest Runner Images

Runner Type OS Latest Image Tag Notes
ubuntu-latest Ubuntu 22.04 ubuntu-22.04 Default Ubuntu runner; updated regularly
ubuntu-24.04 Ubuntu 24.04 ubuntu-24.04 NEW Ubuntu 24.04 runner
ubuntu-22.04 Ubuntu 22.04 ubuntu-22.04 Stable Ubuntu runner
ubuntu-20.04 Ubuntu 20.04 ubuntu-20.04 DEPRECATED Ubuntu 20.04 runner (end-of-life)
macos-latest macOS 13 (Sonoma) macos-13 Default macOS runner; updated regularly
macos-14 macOS 14 (Sonoma) macos-14 NEW macOS 14 runner
macos-13 macOS 13 (Sonoma) macos-13 Stable macOS runner
windows-latest Windows Server 2022 windows-2022 Default Windows runner; updated regularly
windows-2022 Windows Server 2022 windows-2022 Stable Windows runner
windows-2019 Windows Server 2019 windows-2019 DEPRECATED Windows 2019 runner (end-of-life)

Example: Using Latest Ubuntu Runner

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Run tests
        run: npm test

Example: Using Ubuntu 24.04 Runner

jobs:
  build:
    runs-on: ubuntu-24.04
    steps:
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"
      - name: Install dependencies
        run: npm ci
Note: The latest tag is updated periodically to point to the most recent stable image. It's recommended to pin to a specific version for production workflows.

4. Using Specific Runner Versions

Runner Version Available Tags Notes
ubuntu-latest ubuntu-22.04, ubuntu-latest Currently runs on Ubuntu 22.04
ubuntu-22.04 ubuntu-22.04 Stable version with long-term support
ubuntu-20.04 ubuntu-20.04 Legacy version, deprecated in favor of 22.04
macOS-latest macos-13, macOS-latest Currently runs on macOS 13 (Ventura)
macOS-13 macos-13 Stable version with latest features
windows-latest windows-2022, windows-latest Currently runs on Windows Server 2022
windows-2022 windows-2022 Stable version with long-term support

Example: Specifying runner version in workflow

name: Example Workflow
on:
  push:
    branches: [ main ]
jobs:
  build:
    runs-on: ubuntu-22.04
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
Note: Using latest tags ensures you get the most up-to-date runner environment, but may introduce breaking changes. It's recommended to pin to a specific version for stability.

5. Running on Multiple OS

GitHub Actions allows you to run workflows across multiple operating systems using the runs-on field with different runner labels.

Runner Label Operating System Description
ubuntu-latest Ubuntu 22.04 Latest Ubuntu runner, ideal for Linux-based workflows.
ubuntu-22.04 Ubuntu 22.04 Stable Ubuntu 22.04 runner.
ubuntu-20.04 Ubuntu 20.04 Ubuntu 20.04 runner (legacy support).
macos-latest macOS Sonoma Latest macOS runner, optimized for Apple Silicon and Intel.
macos-13 macOS 13 (Ventura) macOS 13 runner for legacy compatibility.
windows-latest Windows Server 2022 Latest Windows runner for Windows-based workflows.
windows-2022 Windows Server 2022 Stable Windows Server 2022 runner.

Example: Matrix Strategy for Multiple OS

jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Run tests
        run: echo "Running on ${{ matrix.os }}"
Note: The ubuntu-latest, macos-latest, and windows-latest runners are updated regularly to the latest stable versions.

6. Using Larger Runners

Runner Type Specification Usage Notes
ubuntu-latest Ubuntu 22.04 Standard runner for Linux workflows Default runner; good for most use cases
ubuntu-22.04 Ubuntu 22.04 Stable runner with long-term support Recommended for production workflows
ubuntu-20.04 Ubuntu 20.04 Legacy runner with older packages Use only for compatibility
windows-latest Windows Server 2022 Standard runner for Windows workflows Default Windows runner; includes latest tools
windows-2022 Windows Server 2022 Stable Windows runner with long-term support Recommended for production workflows
windows-2019 Windows Server 2019 Legacy Windows runner with older packages Use only for compatibility
macOS-latest macOS 13 (Ventura) Standard runner for macOS workflows Default macOS runner; includes latest Xcode
macOS-13 macOS 13 (Ventura) Stable macOS runner with long-term support Recommended for production workflows
macOS-12 macOS 12 (Monterey) Legacy macOS runner with older packages Use only for compatibility

Example: Using larger runner in workflow

name: Build with larger runner
on: [push]
jobs:
  build:
    runs-on: ubuntu-22.04
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Install dependencies
        run: npm ci
      - name: Run tests
        run: npm test
Note: Larger runners provide more CPU and memory resources than the default runners. They are ideal for complex builds or large projects that require more computational power.

7. Using Runner Context

Property Description Example Value
runner.name Name of the runner executing the job GitHub Actions
runner.os Operating system of the runner Linux
runner.arch Architecture of the runner AMD64
runner.temp Temporary directory on the runner /tmp

Example: Using runner context in a job

jobs:
  example-job:
    runs-on: ubuntu-latest
    steps:
      - name: Print runner info
        run: |
          echo "Runner OS: ${{ runner.os }}"
          echo "Runner Arch: ${{ runner.arch }}"
          echo "Temp Directory: ${{ runner.temp }}"

8. Checking Runner Capabilities

Capability Description Availability
OS ubuntu-latest, ubuntu-22.04, ubuntu-20.04, macOS-latest, macOS-13, macOS-12, windows-latest, windows-2022, windows-2019 GitHub-hosted runners
Architecture x64, arm64 GitHub-hosted runners
CPU 2-core (x64), 4-core (arm64) for ubuntu-latest; 2-core for macOS-latest; 2-core for windows-latest GitHub-hosted runners
Memory 7GB (x64), 14GB (arm64) for ubuntu-latest; 16GB for macOS-latest; 8GB for windows-latest GitHub-hosted runners
Storage 14GB (x64), 14GB (arm64) for ubuntu-latest; 10GB for macOS-latest; 10GB for windows-latest GitHub-hosted runners

Example: Using runner capabilities in a workflow

name: Check Runner Capabilities
on:
  push:
    branches: [ main ]

jobs:
  check-capabilities:
    runs-on: ubuntu-latest
    steps:
      - name: Print runner info
        run: |
          echo "OS: ${{ runner.os }}"
          echo "Architecture: ${{ runner.architecture }}"
          echo "CPU cores: ${{ runner.cpu }}"
          echo "Memory (GB): ${{ runner.memory }}"
Note: Runner capabilities are available as environment variables in the workflow context.

9. Using Pre-installed Tools

Tool Version Installation Path Notes
Node.js 20.11.0 /opt/hostedtoolcache/node/20.11.0/x64 Available via nvm and node command
Python 3.12.0 /opt/hostedtoolcache/Python/3.12.0/x64 Also includes pip and venv
Java 21.0.1 /opt/hostedtoolcache/Java/21.0.1/x64 OpenJDK 21, available via java and javac
Go 1.22.0 /opt/hostedtoolcache/Go/1.22.0/x64 Available via go command
Ruby 3.2.0 /opt/hostedtoolcache/Ruby/3.2.0/x64 Available via ruby and gem
PHP 8.2.0 /opt/hostedtoolcache/PHP/8.2.0/x64 Available via php command
Rust 1.75.0 /opt/hostedtoolcache/Rust/1.75.0/x64 Available via rustc and cargo
Swift 5.9.0 /opt/hostedtoolcache/Swift/5.9.0/x64 Available via swift command

Example: Using pre-installed Node.js in a workflow

name: Use Node.js
on:
  push:
    branches: [ main ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20.11.0"
      - run: node --version
Note: The actions/setup-node action can be used to select a specific Node.js version, even if it's not the default pre-installed one.

10. Accessing Runner Workspace

Aspect Description Notes
Workspace Path /home/runner/work/<repo_name>/<repo_name> Default location where the repository is checked out
Environment Variable GITHUB_WORKSPACE Points to the workspace directory
File Access Read/Write Workflow can read and write files in the workspace

Example: Using Workspace in a Job

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: List files in workspace
        run: |
          echo "Workspace contents:"
          ls -la $GITHUB_WORKSPACE

      - name: Create a file in workspace
        run: |
          echo "Hello from GitHub Actions" > $GITHUB_WORKSPACE/hello.txt
Note: The workspace is automatically cleaned up after each job completes, unless specified otherwise using continue-on-error.

Was this article helpful?