GitHub-Hosted Runners, Images, Labels, Hardware, and Runtime Behavior: Diagnostics, Failure Modes, and Production Practices

1. Preserve evidence before rerun

1. Record run ID, attempt, source SHA and workflow revision.
2. Open the failing job's Set up job section and record requested label, image OS/version and included-software link.
3. Record runner.os/runner.arch, selected tool versions and failing shell.
4. Locate the first failing command—not the final cascade.
5. Only then compare a previous successful run's image/tool evidence.

A rerun may land on a newer image release and destroy the clean comparison if you failed to preserve the original details.

2. Failure: treating ubuntu-latest as immutable

Yesterday: requested=ubuntu-latest image_os=ubuntu24 image_version=20260901.1 python=3.x.y
Today:     requested=ubuntu-latest image_os=ubuntu24 image_version=20260908.1 python=3.x.z
Failure: tool changed behavior

The first fix is not “rerun until green.” Reproduce with the old/new tool version if possible. If the application depends on a specific tool, declare that tool through a setup action or package pin. If the OS generation changed during a -latest migration, move to a versioned label temporarily and schedule the migration deliberately.

3. Failure: hard-coded Unix paths on Windows

# Broken cross-OS assumption — diagnostic example only
- run: cat /tmp/report.txt

On Windows this is the wrong shell/path model. Prefer runner-provided paths and platform-neutral tooling:

- shell: pwsh
  run: |
    $p = Join-Path $env:RUNNER_TEMP 'report.txt'
    'portable' | Set-Content $p
    Get-Content $p

Or intentionally branch by runner.os if the operation is OS-specific. Do not pretend one shell dialect is portable.

4. Failure: expecting job A's file in job B

If job B reports “file not found,” first verify whether the file was created in another job. Separate jobs are fresh instances. The correct fix is an explicit artifact/output/rebuild design—not moving files into a more “global-looking” directory on job A's VM.

5. Failure: relying on undocumented preinstalled software

If a command disappears or changes version, inspect the run-specific included-software manifest. Then decide whether the tool is an incidental image utility or an application dependency. Application dependencies belong in workflow/package configuration with explicit versions.

6. Failure: architecture mismatch

runner_arch=ARM64
error: package/native binary only published for x64

Do not “fix” this by emulation without understanding the support requirement. Either choose an x64 runner, add an Arm64-compatible dependency/build, or constrain the matrix until the product supports Arm64. Preserve the dependency-resolution evidence.

7. Failure: assuming identical hardware/network

Public/private standard specifications differ, macOS classes differ, larger runners differ, and network paths are external dependencies. If a job is killed for memory or disk pressure, record the runner class and actual resource observations. If an API call times out, correlate runner logs with provider status/network evidence before blaming CPU or adding retries.

8. Troubleshooting shortcuts to avoid

• Blind reruns that replace first-failure evidence.
• Switching to a huge runner without measuring memory/CPU/disk pressure.
• Installing “latest” packages ad hoc in the failing job without recording versions.
• Hard-coding public hosted IP ranges as a permanent firewall contract.
• Moving untrusted workloads to a privileged self-hosted runner because hosted networking is inconvenient.

9. Intentionally broken portability probe

strategy:
  matrix:
    os: [ubuntu-24.04, windows-2025]
runs-on: ${{ matrix.os }}
steps:
  - name: Broken — assumes Bash and /tmp
    run: |
      echo "$RUNNER_OS" > /tmp/os.txt
      cat /tmp/os.txt

Expected evidence: Ubuntu succeeds; Windows fails before proving application behavior. Repair it with explicit shell/runner temp semantics, preserve both run attempts, and explain that this was a workflow portability failure—not a Windows application failure.

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.