GitHub Actions workflows usually define a runner with a line such as:
runs-on: ubuntu-latest
At first glance, this looks simple. GitHub manages the runner image, the workflow selects it, and the job starts.
The problem appears when an organization has many repositories and many workflows.
Some workflows may use the current runner label, while others may still reference an older image. A few may use self-hosted runners or hardcoded operating system versions. Over time, these differences become difficult to track.
An old runner image can cause more than a failed build. It can leave a workflow using an outdated compiler, SDK, system library, command-line tool, or preinstalled dependency.
The practical approach is to inventory the runner configuration across repositories, identify workflows using old images, test them on the current supported environment, and update them in a controlled way.
What Is a GitHub Actions Runner Image?
A GitHub Actions runner is the machine or virtual environment where a workflow job executes.
A workflow might contain:
jobs:
build:
runs-on: ubuntu-latest
The runner provides the operating system and a collection of commonly used development tools.
For example, a job may depend on tools already available on the runner:
Runner
|
+-- Operating system
+-- Git
+-- Node.js
+-- Python
+-- Docker
+-- Compilers
+-- System libraries
+-- CLI tools
The workflow itself may not explicitly install all of these tools.
That creates an important dependency.
Your build can depend on the runner image even when the runner version is not mentioned anywhere else in the project.
Why Old Runner Images Become a Problem
An older runner image can contain older versions of system software and preinstalled tools.
For example, a workflow might rely on:
- run: gcc --version
without installing GCC first.
The workflow therefore depends on whatever version is provided by the runner.
The same applies to commands such as:
node --version
python --version
docker --version
java --version
dotnet --version
If the runner image changes, these tools can change too.
If the workflow remains on an old image, it can eventually become incompatible with newer dependencies or GitHub's supported runner infrastructure.
Start by Finding Every Workflow
The first step is inventory.
GitHub Actions workflow files normally live under:
.github/workflows/
A repository may contain files such as:
.github/workflows/build.yml
.github/workflows/test.yml
.github/workflows/deploy.yml
.github/workflows/release.yml
Search these files for:
runs-on:
For example:
runs-on: ubuntu-20.04
or:
runs-on: ubuntu-latest
or:
runs-on: windows-latest
You are looking for both old runner references and inconsistent runner choices.
Common Runner Labels
Workflows may use labels such as:
runs-on: ubuntu-latest
runs-on: windows-latest
runs-on: macos-latest
They may also specify an operating system version:
runs-on: ubuntu-22.04
The exact supported labels change over time, so the important point is to compare the labels used by your workflows against the currently supported GitHub-hosted runner images.
Do not assume that every numeric version found in a workflow is automatically obsolete.
Search Across a Repository
For a single repository, searching the workflow directory is usually enough.
With Git, you can use:
git grep "runs-on:" .github/workflows
You can also search for specific operating system references:
git grep "ubuntu-" .github/workflows
This is useful when reviewing a repository manually.
For a large organization, manual repository-by-repository searches do not scale well.
Search Across Multiple Repositories
Organizations with many repositories should build an inventory.
The inventory can contain:
Repository | Workflow | Runner | Job | Status |
|---|
api-service | build.yml | ubuntu-latest | build | Current |
web-app | test.yml | ubuntu-20.04 | test | Review |
worker | deploy.yml | ubuntu-22.04 | deploy | Review |
desktop-app | build.yml | windows-latest | build | Current |
This immediately makes old references easier to find.
The important part is not only identifying old labels.
You also need to know why each workflow uses them.
Check Reusable Workflows
Runner configuration may not always be present in the repository's main workflow file.
A repository might call a reusable workflow:
jobs:
build:
uses: company/workflows/.github/workflows/build.yml@main
The runner configuration may exist inside the reusable workflow.
That means searching only for:
runs-on:
in the calling repository can produce an incomplete inventory.
Review reusable workflows as part of the dependency chain.
Application Workflow
|
v
Reusable Workflow
|
v
runs-on
|
v
Runner Image
Check Matrix Builds
Runner versions can also appear inside a build matrix.
For example:
strategy:
matrix:
os:
- ubuntu-22.04
- windows-latest
The workflow may therefore use multiple runner images.
A simple search for one runs-on value is not enough.
Look for expressions such as:
runs-on: ${{ matrix.os }}
Then inspect the matrix values.
Check Variables and Expressions
Some workflows do not hardcode the runner directly.
For example:
env:
RUNNER_IMAGE: ubuntu-22.04
and later:
runs-on: ${{ env.RUNNER_IMAGE }}
Another workflow may use repository or organization variables.
This is why a complete review should look for:
runs-on:
matrix
vars.
env.
workflow_call
reusable workflows
The goal is to determine the actual runner selected at execution time.
Do Not Forget Self-Hosted Runners
Not every workflow uses GitHub-hosted runners.
A workflow might contain:
runs-on: self-hosted
or:
runs-on:
- self-hosted
- linux
These workflows have a different maintenance model.
GitHub does not manage the operating system image in the same way as a GitHub-hosted runner.
Your organization is responsible for:
Operating system updates
Security patches
Installed software
Runner agent updates
Disk space
Network access
Authentication
Configuration management
Self-hosted runners should therefore be inventoried separately.
Why Self-Hosted Runners Need Extra Attention
A self-hosted runner can remain unchanged for a long time.
For example:
2023
|
+-- Runner installed
2024
|
+-- Same OS
2025
|
+-- Same configuration
Current
|
+-- Build still depends on old environment
The workflow may continue working until a dependency suddenly requires a newer system library or toolchain.
Treat self-hosted runners as infrastructure rather than as permanent machines that never need maintenance.
Check Docker-Based Jobs
A workflow may use a current runner but execute the actual build inside a container.
For example:
jobs:
build:
runs-on: ubuntu-latest
container:
image: node:22
steps:
- uses: actions/checkout@<commit-sha>
- run: npm ci
- run: npm test
In this case, the runner still matters because GitHub Actions itself runs on the host runner, but the application build environment is primarily controlled by the container.
This is an important distinction.
GitHub Runner
|
+-- GitHub Actions execution
|
+-- Container
|
+-- Application build
When investigating compatibility, review both layers.
Runner Image and Tool Versions Are Different
A workflow might specify:
uses: actions/setup-node@<commit-sha>
with:
node-version: 22
This is more explicit than relying on the Node.js version installed on the runner.
Similarly:
uses: actions/setup-python@<commit-sha>
with:
python-version: "3.12"
makes the application runtime more predictable.
This leads to a useful rule:
The more important a tool is to your build, the less you should rely on an incidental version provided by the runner.
Make Tool Versions Explicit
Suppose a workflow contains:
- run: node --version
- run: npm test
The workflow depends on the Node.js version provided by the runner.
A more controlled workflow can explicitly install the required version:
- uses: actions/setup-node@<commit-sha>
with:
node-version: 22
- run: npm ci
- run: npm test
This does not eliminate runner dependencies, but it reduces them.
The same principle applies to:
Python
Java
.NET
Go
Ruby
Terraform
Cloud CLI tools
Look for Hidden Runner Dependencies
A workflow may appear to use explicit versions but still depend on system tools.
For example:
- uses: actions/setup-node@<commit-sha>
with:
node-version: 22
- run: npm ci
- run: git --version
- run: openssl version
- run: make
Node.js is controlled, but Git, OpenSSL, and make may come from the runner.
If those versions matter to your build, install or control them explicitly.
This is particularly important for security-sensitive workflows.
Build a Runner Dependency Inventory
For each workflow, document the tools it expects from the runner.
For example:
Tool | Source | Version Controlled? |
|---|
Node.js | setup-node | Yes |
npm | Node.js | Yes |
Git | Runner | No |
OpenSSL | Runner | No |
Docker | Runner | Partially |
jq | Runner | No |
This helps identify hidden dependencies.
A workflow that relies heavily on preinstalled tools is more sensitive to runner image changes.
Check Workflow Logs
The workflow logs can reveal what environment the job actually received.
Useful commands include:
node --version
npm --version
python --version
git --version
docker --version
You can temporarily add diagnostic commands:
- name: Check environment
run: |
uname -a
node --version
npm --version
git --version
Do this during testing rather than permanently exposing unnecessary environment details in production logs.
Test Old and Current Runner Images
If you discover an older runner reference, do not immediately change it and hope the workflow works.
Create a test change.
For example:
runs-on: ubuntu-22.04
can be tested against:
runs-on: ubuntu-latest
Run the complete workflow.
Pay attention to:
Build failures
Compiler errors
Native npm modules
Python dependencies
Docker builds
Shell behavior
File paths
System packages
Deployment tools
A runner migration is an environment change.
Treat it like one.
Native Dependencies Are a Common Problem
Node.js applications can depend on native modules.
For example:
npm ci
may compile native code if a compatible prebuilt binary is unavailable.
The build may therefore depend on:
Compiler versions
libc versions
Python
make
System headers
A runner image change can expose these dependencies.
If a package suddenly fails to build, check whether it depends on the underlying operating system rather than assuming the npm package itself is broken.
Check Shell Differences
Linux and Windows runners do not provide identical shell environments.
For example:
- run: ./scripts/build.sh
may work on Linux but not Windows.
Similarly:
- run: dir
is different from:
- run: ls
A runner migration can expose assumptions about the shell.
Keep operating-system-specific steps explicit.
For example:
defaults:
run:
shell: bash
when the workflow actually requires Bash and the selected runner supports it.
Review File System Assumptions
Build scripts sometimes depend on specific paths or permissions.
For example:
chmod +x ./scripts/build.sh
may behave differently across operating systems.
Check:
Path separators
File permissions
Case sensitivity
Temporary directories
Home directories
Available disk space
Do not assume that every runner image provides an identical filesystem layout.
Check Docker and Container Builds
Runner image changes can affect Docker workflows.
For example:
- name: Build image
run: docker build -t my-app .
The Docker version, BuildKit configuration, or available system resources can affect the result.
After moving to a different runner image, verify:
docker version
docker info
and run the complete image build.
If the project depends on a specific Docker feature, consider controlling the Docker version explicitly where practical.
Check Deployment Workflows Separately
Build and deployment workflows should not always be treated as one category.
A build workflow may only need:
Source
Compiler
Tests
Artifacts
A deployment workflow may also need:
Cloud CLI
Credentials
Network access
Production permissions
A runner migration that breaks deployment can have a much larger impact.
Prioritize deployment workflows during testing.
Check Scheduled Workflows
Do not review only workflows triggered by pull requests and pushes.
Scheduled workflows can run infrequently:
on:
schedule:
- cron: "0 2 * * *"
A scheduled workflow may remain unnoticed until the next execution.
Include scheduled jobs in your inventory.
Check Manual Workflows
Workflows triggered with:
workflow_dispatch:
can also remain unused for long periods.
That makes them easy to overlook during normal CI testing.
Run them manually after a runner migration if they are still operationally important.
Common Signs of an Old Runner Dependency
Watch for these patterns:
runs-on: ubuntu-20.04
runs-on: self-hosted
runs-on: ${{ matrix.os }}
runs-on: ${{ vars.RUNNER }}
and reusable workflows:
uses: company/workflows/.github/workflows/build.yml@...
These are not automatically problems.
They are signals that the runner configuration needs to be reviewed.
Common Mistakes
Searching Only the Main Workflow File
Runner settings may exist inside reusable workflows or matrices.
Updating the Runner Without Testing
A newer image can change system tools and libraries.
Assuming latest Means Everything Is Fixed
ubuntu-latest controls the GitHub-hosted image selection, but your workflow may still depend on versions of tools that should be explicitly installed.
Ignoring Self-Hosted Runners
Self-hosted runners have their own patching and lifecycle requirements.
Testing Only Pull Request Workflows
Scheduled, manual, and deployment workflows can use different runners.
Ignoring Native Dependencies
Packages that compile native code can expose operating system differences.
A Practical Runner Audit
A simple audit process can look like this.
Step 1: Find All Workflow Files
Search:
.github/workflows/
Step 2: Find Runner References
Search for:
runs-on:
Step 3: Inspect Matrices
Look for:
matrix.os
and similar expressions.
Step 4: Inspect Reusable Workflows
Check referenced workflows for their actual runner configuration.
Step 5: Separate GitHub-Hosted and Self-Hosted Runners
They have different maintenance responsibilities.
Step 6: Identify Hidden Dependencies
Check which tools come directly from the runner.
Step 7: Test Current Supported Images
Move one workflow at a time and run the complete test suite.
Step 8: Fix Tool Version Assumptions
Use setup actions or containers where deterministic versions matter.
Step 9: Update Production Workflows
Prioritize deployment and security-sensitive workflows.
Step 10: Document the Result
Keep an inventory so the same audit does not have to start from zero later.
Example of a More Controlled Workflow
A workflow can explicitly control its important tools:
name: Build
on:
push:
branches:
- main
permissions:
contents: read
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@<commit-sha>
- name: Setup Node.js
uses: actions/setup-node@<commit-sha>
with:
node-version: 22
cache: npm
- name: Install dependencies
run: npm ci
- name: Check versions
run: |
node --version
npm --version
- name: Run tests
run: npm test
The important part is not the exact runner label.
The workflow explicitly controls the application runtime instead of depending entirely on what happens to be installed on the runner.
Runner Migration Checklist
Area | What to Check |
|---|
Workflow files | Find every workflow |
Runner label | Identify current image |
Matrix | Check every OS value |
Reusable workflows | Inspect referenced workflows |
Self-hosted runners | Review separately |
Runtime versions | Pin important runtimes |
Native modules | Test compilation |
Shell | Check OS-specific commands |
Docker | Test image builds |
Scheduled jobs | Run after migration |
Manual jobs | Test important workflows |
Deployment | Test production workflows |
Monitoring | Watch failures after migration |
Advantages of Regular Runner Audits
Regular audits provide several benefits:
Fewer unexpected CI failures
Better security maintenance
More predictable builds
Easier runtime upgrades
Less dependence on undocumented runner behavior
Faster response to runner image changes
They also expose workflows that nobody remembers maintaining.
That alone can be valuable in a large organization.
Summary
GitHub Actions runner images are part of your CI environment, even when the workflow does not explicitly install every tool it uses.
The first step is to find out which runner each workflow actually uses. Then look beyond simple runs-on values and inspect matrices, reusable workflows, self-hosted runners, containers, and variables.
Once the inventory is complete, test older workflows against supported runner images and identify tools that should be explicitly versioned.
The goal is not to move every workflow to the newest runner immediately.
The goal is to know which workflows depend on older environments, understand what they depend on, and update them before the old environment becomes a build or deployment problem.
A well-maintained CI pipeline should make its environment dependencies visible instead of leaving them hidden inside the runner image.
Join the conversation! Your thoughts help the community grow.