GitHub Actions Ubuntu 26 Migration: Test ubuntu-latest Before It Moves

GitHub Actions now supports Ubuntu 26.04 for production workflows on x64 and Arm64. The larger change arrives next: ubuntu-latest will gradually move from Ubuntu 24.04 to Ubuntu 26.04 between October 19 and November 19, 2026.

If your workflow depends on the contents of the hosted runner image, doing nothing is still a migration decision.

What Is Changing

You can target the new images explicitly:

jobs:
  test-x64:
    runs-on: ubuntu-26.04
 
  test-arm64:
    runs-on: ubuntu-26.04-arm

During the announced migration window, jobs using ubuntu-latest will begin landing on Ubuntu 26.04. The rollout is gradual, so two runs close together may not prove that every job is using the same base image.

The new image includes updated toolchains and removes some previously installed software. Workflows are most exposed when they assume a command exists without installing or pinning it.

Find Hidden Runner Dependencies

Search workflow files for direct command usage and ubuntu-latest:

rg "runs-on:.*ubuntu-latest|apt-get|python|node|java|docker|helm|terraform|pulumi" .github/workflows

Review shell scripts and composite actions too. A reusable workflow may hide the actual runner label or invoke software not declared in the caller.

For each tool, decide who owns its version:

• A setup action such as actions/setup-node or actions/setup-python
• Your workflow's package installation step
• A container image pinned by digest or version
• The GitHub-hosted runner image

The last option has the least predictability. Prefer explicit setup when a version affects build output or deployment behavior.

Test Both Images in a Matrix

Add a temporary compatibility workflow:

name: Ubuntu image compatibility
 
on:
  workflow_dispatch:
  pull_request:
 
jobs:
  test:
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-24.04, ubuntu-26.04]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version-file: .nvmrc
          cache: npm
      - run: npm ci
      - run: npm test
      - run: npm run build

Run unit, integration, packaging, container, infrastructure, and deployment-dry-run jobs. A successful dependency install does not prove that native extensions, browsers, Docker builds, or deployment CLIs behave identically.

Record the Actual Image

The Set up job section of a workflow run shows the image version and included software link. Add lightweight diagnostics during migration:

- name: Runner diagnostics
  run: |
    cat /etc/os-release
    uname -a
    node --version || true
    python3 --version || true
    docker version || true

Remove noisy diagnostics after the rollout, but preserve the image details in failed-run evidence. “It failed on ubuntu-latest” is incomplete without the actual OS and image release.

Decide Whether to Pin

If testing passes, you can switch directly to ubuntu-26.04 before the rolling migration. That makes the cutover date yours rather than GitHub's.

If testing reveals blockers, temporarily pin:

runs-on: ubuntu-24.04

Pinning buys investigation time; it is not a permanent avoidance strategy. Hosted images have support lifecycles, and old images are eventually deprecated. Create an owner and deadline for every temporary pin.

Common Failure Categories

Expect issues from removed preinstalled packages, changed language defaults, native library versions, stricter compiler behavior, browser and driver mismatches, and assumptions about filesystem or service configuration.

Do not repair an image migration by blindly installing “latest” versions. Reproduce the old and new environments, identify the dependency, then pin or update it intentionally.

Containerized jobs may reduce host-tool differences, but the runner still provides Docker, networking, mounts, and orchestration. Test those paths on the new image.

Migration Checklist

Before October 19:

1. Inventory ubuntu-latest across workflows and reusable workflows.
2. Run the Ubuntu 24.04/26.04 matrix.
3. Compare artifacts, test results, deployment plans, and execution time.
4. Fix undeclared dependencies.
5. Move passing workflows to ubuntu-26.04 or document a temporary pin.
6. Monitor GitHub's runner-image announcements through November 19.

For runner strategy beyond hosted images, compare GitHub-hosted, larger, and self-hosted runners.

Sources

• GitHub: Ubuntu 26 generally available and latest migration
• GitHub: Runner images
• GitHub Docs: GitHub-hosted runners