Moving GitHub Actions to Ubuntu 26

If your workflow uses Docker Compose, Buildx, container actions, or custom scripts, run the complete pipeline on Ubuntu 26.04.

Do not stop after confirming that:

docker --version

works.

The important test is whether the actual build, test, packaging, and deployment process succeeds.

Step 7: Check Package Installation Scripts

A common source of migration problems is a script that assumes an older Ubuntu environment.

For example:

sudo apt-get update
sudo apt-get install -y some-package

This may work today but fail later if:

• the package name changes

• a repository changes

• a package is removed

• an installation script expects older libraries

• a third-party repository does not yet support the new Ubuntu release

Review scripts that add external package repositories carefully.

Avoid silently trusting installation commands copied from older setup documentation.

Step 8: Check apt-key and Repository Configuration

Ubuntu migrations can also expose older package-management practices.

If your repository contains commands such as:

apt-key add

review them.

Newer Ubuntu environments have moved away from the older apt-key approach. Projects that maintain their own package repository setup should use a current, supported repository configuration.

The important point is not to copy an old installation script unchanged just because it worked on Ubuntu 24.04.

Step 9: Check Cgroup Assumptions

Container-heavy workflows should check whether their tooling makes assumptions about Linux cgroups.

Ubuntu 26.04 uses cgroup v2, and older tooling that expects cgroup v1 can require changes. This is particularly relevant to custom container tooling, older CI scripts, and software that directly interacts with Linux resource-control interfaces.

If your workflow does not interact with cgroups directly, this may not require any changes.

But if you have scripts that inspect paths such as:

/sys/fs/cgroup/

or depend on older container behavior, include them in your migration tests.

Step 10: Test Self-Hosted Runner Assumptions Separately

A workflow that works on GitHub-hosted Ubuntu 26.04 does not automatically prove that it works on every self-hosted Linux runner.

Self-hosted runners are controlled by the organization and can have different:

• operating systems

• kernels

• installed packages

• architectures

• Docker configurations

• security policies

Keep GitHub-hosted runner migration testing separate from self-hosted infrastructure migration.

Use a Matrix to Compare Runner Versions

For important repositories, a temporary matrix can make migration testing easier.

jobs:
  test:
    strategy:
      matrix:
        os:
          - ubuntu-24.04
          - ubuntu-26.04

    runs-on: ${{ matrix.os }}

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '10.x'

      - name: Build
        run: dotnet build --configuration Release

      - name: Test
        run: dotnet test --configuration Release --no-build

This is useful because the same workflow executes against both environments.

You can then compare:

Ubuntu 24.04
     |
     +-- Build
     +-- Test
     +-- Package
     |
     v
Ubuntu 26.04
     |
     +-- Build
     +-- Test
     +-- Package

If one environment fails, you have a much clearer starting point for investigation.

Do Not Use ubuntu-latest as Your Migration Test

There is an important difference between:

runs-on: ubuntu-latest

and:

runs-on: ubuntu-26.04

When testing the migration, use the explicit version.

If you continue testing only with ubuntu-latest, the underlying runner can change independently of your migration work.

An explicit label gives you a known target.

Once your application works correctly on Ubuntu 26.04, you can decide whether to continue using:

runs-on: ubuntu-26.04

or return to:

runs-on: ubuntu-latest

The right choice depends on how much control you want over runner-version changes.

Pinning the Ubuntu Version vs Using latest

For production-critical workflows, explicit runner labels can make migration timing easier to control.

For less sensitive workflows, ubuntu-latest can reduce manual maintenance.

Common Migration Problems

Missing Packages

A workflow may fail with:

E: Unable to locate package ...

Check whether the package is still available under the expected name and repository.

Native Binary Failures

You may see errors such as:

error while loading shared libraries

or:

GLIBC_... not found

These usually point toward compatibility between the binary and the system libraries.

Tool Version Differences

A script may expect a specific version:

node --version

while the runner contains another version.

Install the required version explicitly rather than relying on the image default.

Third-Party Repository Problems

A setup script may reference a repository that does not yet support Ubuntu 26.04.

Verify third-party dependencies independently before migrating the entire pipeline.

Container Compatibility

Older container tooling can behave differently under newer kernel and cgroup environments.

Test the actual container workflow rather than only checking that Docker starts.

Best Practices for the Migration

Test Explicitly

Use:

runs-on: ubuntu-26.04

during migration testing.

Pin Important Tool Versions

Explicitly configure language runtimes and SDKs where reproducibility matters.

Avoid Hidden Dependencies

If a build depends on a package, install or otherwise provision it deliberately rather than assuming it is present.

Keep Migration Changes Small

Do not combine an Ubuntu migration with a major application refactoring if you can avoid it.

If the build fails, you want to know which change caused the problem.

Test the Complete Pipeline

A successful compilation is not enough.

Test:

1. Restore

2. Build

3. Unit tests

4. Integration tests

5. Packaging

6. Container builds

7. Security scanning

8. Deployment steps where appropriate

Monitor After Migration

A workflow can pass during a test branch and still expose an edge case later.

Watch production CI runs after migration and investigate new failure patterns.

A Practical Migration Checklist

[ ] Find all ubuntu-latest workflows
[ ] Find all ubuntu-24.04 workflows
[ ] Check reusable workflows
[ ] Test with ubuntu-26.04
[ ] Pin important SDK/runtime versions
[ ] Review apt package installation
[ ] Check native libraries
[ ] Check OpenSSL dependencies
[ ] Test Docker workflows
[ ] Review third-party repositories
[ ] Check cgroup-related tooling
[ ] Run the complete test suite
[ ] Compare Ubuntu 24.04 and 26.04 where useful
[ ] Review deployment workflows separately
[ ] Decide whether to use an explicit runner or ubuntu-latest
[ ] Monitor CI after migration

Advantages and Disadvantages

Summary

Moving GitHub Actions workflows to Ubuntu 26.04 should be treated as a CI environment migration rather than a simple one-line YAML change.

GitHub already provides the explicit ubuntu-26.04 runner, and the ubuntu-latest label is scheduled to transition to Ubuntu 26.04 through a rollout beginning October 19, 2026 and expected to complete by November 19, 2026.

The safest approach is to identify workflows that use Ubuntu runners, test them explicitly against ubuntu-26.04, verify system dependencies, pin important development tools, and test the complete CI/CD pipeline.

Pay particular attention to native libraries, package installation scripts, Docker workflows, third-party repositories, and tooling that depends on Linux kernel or cgroup behavior.

Most importantly, do not wait for ubuntu-latest to change before discovering compatibility problems. Testing with ubuntu-26.04 now gives teams a controlled environment in which to find and fix those problems before the automatic migration reaches their workflows.