GitHub Actions Ubuntu 26.04 Migration: Test Before October 19

Quick answer: GitHub will move the ubuntu-latest label from Ubuntu 24.04 to Ubuntu 26.04 gradually between October 19 and November 19, 2026. If your Actions workflows use runs-on: ubuntu-latest, test them now with ubuntu-26.04. If they are not ready, temporarily pin them to ubuntu-24.04.[1]

Copy-paste migration options

Choose one of these runner labels in each affected workflow:

# Test or deliberately adopt Ubuntu 26.04 on x64
jobs:
  test:
    runs-on: ubuntu-26.04

# Stay on Ubuntu 24.04 temporarily while you fix compatibility issues
jobs:
  test:
    runs-on: ubuntu-24.04

# Adopt Ubuntu 26.04 on Arm
jobs:
  test:
    runs-on: ubuntu-26.04-arm

GitHub says the Ubuntu 26.04 image is fully supported for production workflows on both x64 and arm64. It also warns that changed or removed tools and versions can break workflows that depend on the old image’s preinstalled environment.[1]

What is changing?

The floating ubuntu-latest label currently points to Ubuntu 24.04, but GitHub will progressively redirect it to Ubuntu 26.04 during the October 19–November 19 rollout window. That means two runs of an unchanged workflow can eventually execute on different operating-system images as the migration reaches your repository.[1]

This is relevant to jobs that use:

runs-on: ubuntu-latest

A job already pinned to ubuntu-24.04 will not move merely because the ubuntu-latest alias changes. A job pinned to ubuntu-26.04 opts into the new image immediately.

Five-minute repository audit

Run these commands from the repository root to find workflow files that use the floating label:

grep -RIn --include='*.yml' --include='*.yaml' \
  'runs-on:.*ubuntu-latest' .github/workflows

Also search reusable workflows and generated CI configuration:

grep -RIn --include='*.yml' --include='*.yaml' \
  'ubuntu-latest' .github

Then classify every result:

1. Safe to test now: change a branch or pull request to ubuntu-26.04 and run the full workflow.
2. Needs investigation: the job depends on system packages, compiler versions, browsers, databases, container tooling, or binaries already present on the runner.
3. Must remain stable temporarily: pin to ubuntu-24.04, create a migration issue, and set an owner and deadline.
4. Not a hosted Ubuntu job: leave references that are documentation, examples, or unrelated strings unchanged.

Safer test matrix before changing production CI

Add a temporary matrix so the same job runs on both images:

name: Ubuntu runner 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@v4
      - name: Show runner details
        run: |
          cat /etc/os-release
          uname -a
      - name: Install dependencies
        run: ./scripts/install-ci-dependencies.sh
      - name: Run tests
        run: ./scripts/test.sh

Replace the two example scripts with your real install and test commands. Keep fail-fast: false during comparison so a failure on one image does not hide the result from the other.

Migration checklist

1. Inventory every floating runner label

Search all active branches and reusable workflow repositories, not just the default branch. Include workflows called with workflow_call, because a central workflow can affect many repositories.

2. Compare the exact runner environments

GitHub maintains the standard hosted-runner images and their included-tool lists in the actions/runner-images repository. For a completed workflow, expand Set up job, then Runner Image; the Included Software link identifies the software on that exact runner.[2]

Record the image and tool versions from a known-good Ubuntu 24.04 run, then compare them with the Ubuntu 26.04 test run. This is more reliable than assuming that a tool is unchanged because its command still exists.

3. Make implicit dependencies explicit

If a workflow silently relies on a preinstalled package, add an explicit installation or setup step. Common areas to inspect include:

• language runtimes and package managers;
• compiler and linker versions;
• database clients and services;
• browser and browser-driver versions;
• native libraries needed to build dependencies;
• Docker, Buildx, and container tooling;
• shell behavior and command-line utilities;
• architecture-specific binaries in arm64 jobs.

Do not blindly pin every package. Pin only where reproducibility or compatibility requires it, and document why.

4. Test more than the happy path

Run unit tests, integration tests, artifact builds, container builds, release packaging, code signing, and deployment dry runs. A green lint job does not prove that production artifacts will be equivalent.

Compare:

• exit codes and test totals;
• generated artifact names and sizes;
• checksums where deterministic output is expected;
• container architecture and base layers;
• deployment manifests;
• cache hit and miss behavior;
• execution time and unexpected warnings.

5. Check caches carefully

If a cache key does not include the operating system or a dependency-lock hash, Ubuntu 24.04 and 26.04 jobs may restore incompatible cached files. Prefer cache keys that separate runner OS and architecture, for example:

key: ${{ runner.os }}-${{ runner.arch }}-deps-${{ hashFiles('**/package-lock.json') }}

After changing a cache key, verify both a cold run and a warm-cache run.

6. Decide: adopt or temporarily pin

Adopt ubuntu-26.04 when the complete workflow passes and its artifacts or deployments are verified. Temporarily use ubuntu-24.04 when a confirmed incompatibility cannot be fixed safely before rollout.

A temporary pin is a rollback control, not a completed migration. Add an issue or code comment with an owner and review date so the repository does not remain on an older image by accident.

7. Merge before the rollout reaches you

GitHub’s migration is gradual, so there is no reliable assumption that every repository changes on the first day or the last day. Finish testing before October 19 rather than waiting for a failing run during the rollout.[1]

How to diagnose an Ubuntu 26.04-only failure

Start by confirming which image actually ran:

- name: Runner diagnostics
  run: |
    cat /etc/os-release
    uname -a
    printf 'Architecture: '
    dpkg --print-architecture
    printf 'PATH: %s\n' "$PATH"

Next, open the workflow log and inspect Set up job → Runner Image → Included Software. GitHub documents that this link points to the preinstalled-tool list for the exact runner used in that run.[2]

Then work through the failure in this order:

1. Compare the failed command and error with the last successful Ubuntu 24.04 run.
2. Check whether the required executable or library is missing.
3. Print the relevant tool version on both images.
4. Replace reliance on a preinstalled version with an explicit setup step where practical.
5. Clear or separate caches if the error involves compiled dependencies.
6. Re-run only after committing a specific fix; avoid making several unrelated CI changes at once.

Example pull-request plan

Use a controlled change instead of editing every workflow at once:

1. Create a branch named ci/test-ubuntu-26.
2. Change one representative workflow from ubuntu-latest to ubuntu-26.04.
3. Add runner diagnostics temporarily.
4. Run tests and produce the normal build artifact.
5. Compare the result with a recent Ubuntu 24.04 artifact.
6. Fix confirmed incompatibilities one at a time.
7. Expand the test to deployment or release workflows using a dry-run environment.
8. Merge the explicit ubuntu-26.04 label, or pin to ubuntu-24.04 with a tracked follow-up.

FAQ

When will ubuntu-latest change to Ubuntu 26.04?

GitHub says the gradual migration will run from October 19 through November 19, 2026.[1]

Can I test Ubuntu 26.04 now?

Yes. Use runs-on: ubuntu-26.04 for x64 or runs-on: ubuntu-26.04-arm for arm64. GitHub says both images are fully supported for production workflows.[1]

How do I stay on Ubuntu 24.04?

Replace ubuntu-latest with ubuntu-24.04 in the affected job. Treat that as a temporary compatibility measure and track the remaining work.[1]

Why can the migration break a workflow?

Ubuntu 26.04 has updated and, in some cases, removed tools and tool versions compared with earlier images. Workflows that rely on those implicit dependencies may fail after the image changes.[1]

How can I see exactly what software was on a runner?

Open the workflow log, expand Set up job, then Runner Image, and follow the Included Software link. GitHub says that page describes the preinstalled tools on the exact runner used for the job.[2]

Should I keep using ubuntu-latest?

Use it when you intentionally want GitHub’s current supported Ubuntu default and are prepared for periodic image changes. Use an explicit label when your build needs a controlled operating-system version. Either way, make required tools explicit and test image migrations before they reach critical workflows.

Sources

[1] https://github.blog/changelog/2026-09-17-ubuntu-26-generally-available-and-latest-migration — Ubuntu 26 generally available and latest migration
[2] https://docs.github.com/en/actions/how-tos/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners — About GitHub-hosted runners