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.