The landscape of continuous integration and continuous deployment (CI/CD) within the GitHub Actions ecosystem is undergoing a fundamental transformation with the migration of the ubuntu-latest label to Ubuntu 24.04. This transition represents more than a routine operating system version increment; it constitutes a strategic realignment of the default runner environment, affecting package availability, default tool versions, and security protocols. For organizations and individual developers relying on GitHub-hosted runners, this shift mandates a thorough audit of existing workflows to prevent pipeline failures and ensure long-term maintainability. The migration reflects a broader industry trend toward explicit dependency management and enhanced security boundaries, moving away from the implicit assumptions that previously characterized "black box" runner environments.
The Migration Timeline and Execution Strategy
GitHub has structured the transition of the ubuntu-latest label to a gradual rollout process designed to minimize disruption while allowing users time to adapt their pipelines. The initiative began with the general availability (GA) of the Ubuntu 24.04 image for GitHub-hosted runners in September 2024. Following this, the actual migration of the ubuntu-latest pointer commenced on December 5, 2024, and is scheduled to complete by January 17, 2025. This multi-week window ensures that workflows are not simultaneously affected, providing a buffer for teams to identify and resolve compatibility issues.
During the migration period, any workflow utilizing the ubuntu-latest label may experience intermittent changes in the underlying operating system version. To monitor this transition, developers can inspect the "Runner Image" information within the "Set up job" step of their Actions logs. This transparency allows teams to verify whether a specific job has been migrated to the new image. For those requiring immediate stability, the recommended approach is to pin workflows to a specific version, such as ubuntu-22.04, until migration preparations are complete. This pinning strategy prevents unexpected breaks during the rollout phase, ensuring that critical production pipelines remain unaffected by the shifting default.
The migration process applies not only to standard GitHub Actions runners but also to Azure DevOps pipelines, as both platforms share the same underlying runner image infrastructure. This cross-platform consistency simplifies the migration effort for organizations utilizing both services, although it requires careful coordination to ensure that workflows across both environments are updated simultaneously. The gradual nature of the rollout—spanning approximately six weeks—highlights GitHub's commitment to user experience, balancing the need for modernization with the practical realities of large-scale infrastructure changes.
Rationale for Package Reduction and Disk Space SLAs
A defining characteristic of the Ubuntu 24.04 runner image is the significant reduction in the number of pre-installed packages compared to its predecessor, Ubuntu 22.04. This decision is driven by GitHub's need to maintain its Service Level Agreement (SLA) for free disk space. As the base image size increases with additional software, the available disk space for user workflows decreases, potentially causing failures in pipelines that generate large amounts of build artifacts or require substantial temporary storage.
By trimming the pre-installed package list, GitHub ensures that runners have sufficient disk space for diverse workloads, from lightweight static site builds to resource-intensive application compilation. This strategy forces a shift from implicit dependency management to explicit declaration, encouraging best practices in software engineering. Developers are now compelled to declare their dependencies within their workflow files, leading to more portable, reproducible, and secure pipelines.
The removal of certain tools is also motivated by maintenance overhead and the availability of alternative installation methods. For instance, packages like Heroku CLI, Leiningen, and Terraform have been removed due to maintenance concerns. Instead of maintaining these tools within the base image, GitHub recommends using tasks to install them on-demand during the workflow execution. This approach reduces the image maintenance burden while still providing access to necessary tools when required. The removal of the R language support and SVN further illustrates a focus on modernizing the development ecosystem, phasing out legacy tools that have limited adoption in contemporary CI/CD practices.
Detailed Software and Tooling Changes
The Ubuntu 24.04 image introduces significant changes to the versions of key development tools. These changes impact the behavior of workflows that rely on default tool installations without explicit version pinning. The following table outlines the most critical differences between the Ubuntu 22.04 and Ubuntu 24.04 images:
| Tool Name | Ubuntu 22.04 Version | Ubuntu 24.04 Version | Notes |
|---|---|---|---|
| PHP | 8.1.* | 8.3.* | The most recent version is installed by default. |
| Java | Previous Default | 17.* | Default Java version switched to 17 for Ubuntu 24.04. |
| Python | Pre-cached versions available | Latest version only | Pre-cached versions unavailable. actions/setup-python installs on-the-fly. |
| Clang | 13, 14 | Latest available | Most recent versions are installed. |
| GCC / G++ / GFortran | Previous versions | Latest available | Most recent versions are installed. |
| Go | Pre-installed versions | Latest available | On-the-fly installation recommended for specific versions. |
| PyPy | Multiple versions | Most recent only | Older versions deprecated. |
| Ruby | Previous versions | 3.3.5 | Version updated to 3.3.5. |
| Node.js | Pre-installed versions | Latest available | On-the-fly installation recommended. |
| Heroku CLI | Latest available | Removed | Removed due to maintenance reasons. |
| Leiningen | Latest available | Removed | Removed due to maintenance reasons. |
| Mono / MSBuild / NuGet | Latest available | Removed | Software not available for Ubuntu 24.04 at this time. |
| Terraform | Latest available | Removed | Removed due to maintenance reasons. |
The removal of the Mono/MSBuild/NuGet ecosystem is particularly significant for .NET developers relying on legacy Mono environments. With these tools no longer available in the base image, workflows must utilize modern .NET SDKs installed via tasks or alternative methods. Similarly, the removal of Terraform and Heroku CLI requires users to integrate these tools into their workflows using community-maintained actions or official installation scripts.
For Python, the removal of pre-cached versions means that the actions/setup-python action will install the requested version on-the-fly during workflow execution. While this adds a slight overhead to job startup time, it ensures that users always have access to the desired Python version without relying on the base image's pre-installed set. This change aligns with the broader trend of dynamic dependency resolution in CI/CD pipelines.
Impacted Cloud Provider and Ecosystem Tools
Beyond core development tools, the Ubuntu 24.04 migration affects various cloud provider CLIs and ecosystem-specific utilities. These tools were previously included in the base image to facilitate common deployment and integration patterns. Their removal necessitates explicit installation steps in workflows that depend on them.
The following tools have been removed or significantly altered in the Ubuntu 24.04 image:
- Development tools: Heroku CLI, Leiningen, Mono/MSBuild/NuGet ecosystem, Terraform, R language support, and SVN.
- Cloud provider tools: Alibaba Cloud CLI, Netlify CLI, OpenShift CLI, and Vercel CLI.
- Rust ecosystem tools: Bindgen, Cbindgen, Cargo audit, Clippy, and Cargo outdated.
- Other utilities: MS SQL Server Client Tools and MarkdownPS Module.
- Docker: All cached Docker images have been removed, requiring explicit pulling of images during workflow execution.
The removal of cached Docker images is a notable change for workflows that rely on pre-loaded images to reduce build time. Users must now explicitly pull required Docker images as part of their workflow steps. While this increases the initial setup time for jobs, it ensures that the images are up-to-date and reduces the base image size. The removal of Rust ecosystem tools like Clippy and Cargo audit requires Rust developers to install these tools explicitly using cargo install commands within their workflows.
These changes reflect a shift toward a more minimal base image, where users are expected to install only the tools they need. This approach reduces the attack surface of the runner environment and simplifies the maintenance of the image repository. However, it requires developers to update their workflow files to include these installation steps, ensuring that all dependencies are explicitly declared.
Workflow Adaptation and Best Practices
To successfully navigate the migration to Ubuntu 24.04, developers should adopt several best practices. The first step is to audit existing workflows to identify dependencies on removed tools or specific version requirements. This involves reviewing workflow files for references to ubuntu-latest and determining whether the underlying tools have changed in a way that could break the build.
Explicit dependency declaration is crucial for maintaining portable and maintainable workflows. Instead of relying on the base image's pre-installed tools, workflows should use community-maintained actions or official installation scripts to set up required environments. For example, instead of assuming the presence of the Heroku CLI, workflows should include a step to install it using the official Heroku installation script. This approach ensures that workflows remain functional regardless of changes to the base image.
Container-based workflows offer another solution for managing dependencies. By using containers to define the runtime environment, developers can isolate their workflows from the underlying runner image. This "container-first" thinking reduces the impact of base image changes and provides greater control over the software environment. Workflows can specify a custom Docker image that includes all necessary tools and dependencies, ensuring consistency across different runner environments.
Version pinning is another effective strategy for managing the transition. By pinning workflows to ubuntu-22.04, teams can avoid immediate disruption while they prepare for the migration. This temporary measure allows time for thorough testing and validation of workflows on the new image. Once the migration is complete, workflows can be updated to use ubuntu-24.04 or continue to use ubuntu-latest if the changes are compatible.
Security considerations also play a role in the migration. The new self-hosted runner requirements emphasize enhanced security, including better isolation between runners and external services, clearer audit trails, and improved compliance with security standards. Developers should review their network security policies, configure webhook rate limit monitoring, and test runners with restricted permissions to ensure that their CI/CD infrastructure remains secure.
Addressing Regression and Error Handling
During the migration, some users may encounter errors related to image mapping or version compatibility. For instance, a common error message involves the failure to map the target OS from the ImageOS environment variable, resulting in a failure for Ubuntu 24.04 runners. This issue may arise in self-hosted runner environments where the ImageOS variable is not correctly set to one of the recognized values, such as ubuntu18, ubuntu20, or ubuntu22.
To resolve such issues, developers should ensure that their workflows explicitly specify the runner image using the runs-on key in the workflow file. For example:
yaml
jobs:
build:
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v4
- name: Build
run: dotnet build
This explicit specification bypasses the ubuntu-latest label and ensures that the workflow runs on the intended image. For self-hosted runners, developers may need to update their environment variables or runner configuration to reflect the new image versions. GitHub's runner-images repository provides detailed documentation and release notes to assist with these adjustments.
In cases where workflows fail due to missing tools or version mismatches, developers should review the error logs to identify the specific cause. This may involve installing missing tools using apt-get, pip, npm, or other package managers, or updating workflow steps to use newer versions of actions that support Ubuntu 24.04. Community-maintained actions and official GitHub actions are frequently updated to support new runner images, ensuring compatibility with the latest versions.
Conclusion
The migration of ubuntu-latest to Ubuntu 24.04 represents a pivotal moment in the evolution of GitHub Actions. By reducing the base image size, removing legacy tools, and enforcing explicit dependency management, GitHub is driving the CI/CD community toward more robust, secure, and maintainable workflows. While this transition requires effort from developers to update their pipelines, the long-term benefits—including improved disk space management, enhanced security, and greater reproducibility—justify the investment.
Teams that proactively audit their workflows, adopt container-based strategies, and pin dependencies to specific versions will navigate this transition with minimal disruption. The shift away from implicit assumptions toward explicit declarations aligns with modern software engineering best practices, ensuring that CI/CD pipelines remain resilient in the face of evolving infrastructure. As the migration concludes in January 2025, the GitHub Actions ecosystem will emerge with a more standardized, efficient, and secure foundation for continuous integration and deployment.