GitHub-Hosted Runners, Images, Labels, Hardware, and Runtime Behavior: Guided Hands-On Workflow

1. Preflight and cost boundary

Use a learner-owned disposable repository. A public repository is the simplest free-compatible path for standard hosted runners; private repositories consume included/billable Actions minutes according to the account plan. The mandatory learning works with Ubuntu and Windows. macOS is optional if you want a third OS comparison.

2. Versioned OS matrix

name: chapter08-hosted-runner-probe
on: workflow_dispatch
permissions: {}

jobs:
  probe:
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-24.04, windows-2025, macos-26]
    runs-on: ${{ matrix.os }}
    steps:
      - name: Common context evidence
        shell: bash
        if: runner.os != 'Windows'
        run: |
          set -euo pipefail
          printf 'label=%s
' '${{ matrix.os }}'
          printf 'runner_os=%s
' '${{ runner.os }}'
          printf 'runner_arch=%s
' '${{ runner.arch }}'
          printf 'image_os=%s
' "${ImageOS:-unknown}"
          printf 'image_version=%s
' "${ImageVersion:-unknown}"
          printf 'run_id=%s
' "$GITHUB_RUN_ID"
          printf 'attempt=%s
' "$GITHUB_RUN_ATTEMPT"
          printf 'sha=%s
' "$GITHUB_SHA"

      - name: Windows context evidence
        if: runner.os == 'Windows'
        shell: pwsh
        run: |
          "label=${{ matrix.os }}"
          "runner_os=${{ runner.os }}"
          "runner_arch=${{ runner.arch }}"
          "image_os=$env:ImageOS"
          "image_version=$env:ImageVersion"
          "run_id=$env:GITHUB_RUN_ID"
          "attempt=$env:GITHUB_RUN_ATTEMPT"
          "sha=$env:GITHUB_SHA"

The platform split is intentional. Cross-platform automation often fails because authors assume Bash, GNU utilities, path separators, and quoting rules are universal.

3. Inspect preinstalled tools without depending on them

Add a step that records a few common versions:

      - name: Preinstalled tool snapshot
        shell: pwsh
        run: |
          git --version
          python --version
          node --version
          "workspace=$env:GITHUB_WORKSPACE"
          "temp=$env:RUNNER_TEMP"

PowerShell Core is available across the chosen hosted images, so this compact snapshot is convenient. The values are observations, not a promise that your project can rely on those versions next week.

4. Make Python an explicit dependency

The official setup action is executable code. Pin the exact reviewed commit and record the human-readable release in a comment:

      - name: Set up Python 3.13
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: '3.13'
          check-latest: false

      - name: Verify selected toolchain
        shell: pwsh
        run: |
          python --version
          python -c "import platform; print(platform.python_implementation(), platform.machine())"

The OS image may still change, but the workflow now expresses which Python line it requires. For even stricter reproducibility, pin a patch version that your support policy has tested.

5. Compare latest to a versioned label safely

Create a separate two-cell diagnostic matrix, not a production gate:

  label_compare:
    strategy:
      matrix:
        os: [ubuntu-latest, ubuntu-24.04]
    runs-on: ${{ matrix.os }}
    steps:
      - shell: bash
        run: |
          set -euo pipefail
          printf 'requested=%s
image_os=%s
image_version=%s
' \
            '${{ matrix.os }}' "${ImageOS:-unknown}" "${ImageVersion:-unknown}"

Today both labels map to Ubuntu 24.04, but they communicate different intent. ubuntu-latest opts into a future migration; ubuntu-24.04 opts out of the OS-generation migration while that image remains supported.

6. Create a non-sensitive reproducibility manifest

Do not upload the whole environment. Produce a small text or JSON file containing only the inputs needed for diagnosis:

$manifest = [ordered]@{
  run_id        = $env:GITHUB_RUN_ID
  run_attempt   = $env:GITHUB_RUN_ATTEMPT
  source_sha    = $env:GITHUB_SHA
  runner_os     = '${{ runner.os }}'
  runner_arch   = '${{ runner.arch }}'
  requested_os  = '${{ matrix.os }}'
  image_os      = $env:ImageOS
  image_version = $env:ImageVersion
  python        = (python --version 2>&1 | Out-String).Trim()
  git           = (git --version | Out-String).Trim()
}
$manifest | ConvertTo-Json | Set-Content "$env:RUNNER_TEMP/runner-manifest.json"
Get-Content "$env:RUNNER_TEMP/runner-manifest.json"

Chapter 13 will teach retained artifact transport. In this chapter, the manifest is inspected in the job log/local temp area so the runner concept remains isolated.

7. Challenge: choose the correct control

A project passed yesterday on ubuntu-latest but fails today because the preinstalled Python minor changed. Which correction controls the actual dependency?

Answer after investigation: changing to ubuntu-24.04 may avoid a future OS-generation migration, but an explicit setup step is the direct control for Python. Record both the image release and the selected Python version.

Knowledge check

Official references and version notes

• GitHub-hosted runners reference — current standard/larger runner behavior, filesystem, networking, IP and privilege details.
• Choosing the runner for a job — current runs-on labels, public/private standard runner specifications and architecture availability.
• Using GitHub-hosted runners — current fresh-instance execution model and runner selection.
• GitHub Actions runner images — authoritative current image-label mappings, image releases, weekly update cadence and included-software manifests.
• Ubuntu 24.04 software manifest — current Ubuntu 24.04 image software inventory; verify the run-specific image release rather than assuming this file is frozen.
• Windows Server 2025 software manifest — current Windows Server 2025 image software inventory.
• macOS 26 software manifest — current macOS 26 Arm64 hosted-image inventory.
• Runner context — current runner.os, runner.arch, runner.temp, runner.tool_cache and related context fields.
• Default environment variables — current workspace, temp, repository, run and runner-related default environment state.
• Larger runners concept — current larger-runner plan boundaries and features such as additional resources, groups, autoscaling, GPU and networking options.
• Larger runners reference — current larger-runner hardware/network restrictions, static-IP and macOS caveats.
• setup-python releases — current official action release history; Chapter 08 uses an immutable SHA corresponding to v7.0.0.