GitHub has officially announced that custom images for GitHub-hosted runners have reached general availability status. Originally introduced in October 2025 as a public preview feature, these custom images allow organizations to start with GitHub-curated base images and build virtual machine images meticulously tailored to specific workflow requirements. The graduation from preview to GA marks the maturity of an important capability for organizations running high-performance CI/CD pipelines at scale.
Why Custom Images Matter for CI/CD Performance
Standard GitHub-hosted runners spin up fresh virtual machines with a standard set of pre-installed tools. While this provides a clean, predictable environment, for many real-world workflows every job begins with time-consuming package installation steps. These steps download compilers, SDKs, or libraries that rarely change between runs but must be provisioned fresh for each execution. This repetition creates predictable but unnecessary latency that directly impacts developer productivity.
These cold-start dependencies directly consume billable runner minutes and introduce network-related flakiness as package registries may experience transient issues or rate limiting. Custom images shift this overhead from runtime to build time, creating a predictable environment that matches the organization’s production technology stack exactly. By baking dependencies into the image once rather than installing them repeatedly, teams gain faster job startup, more consistent execution times, and reduced dependency on external package mirrors that may be unreliable or slow.
How Custom Runner Images Work
Organizations create custom images using GitHub’s image builder tooling following a straightforward process. Teams begin by selecting a base image from GitHub’s supported options including Ubuntu LTS releases, Windows Server versions, or macOS variants. They then install required software packages, SDKs, and specialized tooling that their builds depend upon. Configuration steps follow for certificates, internal registries, and organization-specific proxies that may be required for security or compliance reasons.
The final artifact is published to GitHub’s runner infrastructure where it becomes available for workflow use. Once published, these custom images become selectable in Actions workflow YAML files under the runs-on field using a simple label reference that developers find familiar. The workflow syntax remains unchanged while the underlying execution environment carries the organization’s specific toolchain and configuration, providing transparency to developers while enabling infrastructure optimization.
Availability and Requirements
Custom runner images are available for GitHub Teams, GitHub Enterprise Cloud, and GitHub Enterprise Server customers. Existing users who participated in the public preview period can continue using their previously created images without any modification or migration steps required. The GA release maintains full backward compatibility with configurations created during the preview era, protecting existing investments in custom image development.
The feature requires using GitHub-hosted larger runners, which provide dedicated compute resources and are billed per minute of execution. These larger runners provide the dedicated resources and appropriate isolation boundaries necessary for custom image workloads while maintaining the elasticity benefits of GitHub-hosted infrastructure versus self-hosted alternatives that require dedicated maintenance and capacity planning.
Practical Use Cases and Real-World Applications
Teams are successfully deploying custom images across several distinct categories of problems. Compliance-heavy environments in financial services and healthcare organizations pre-install mandatory security agents, audit tooling, and compliance scanners that must execute on every build without fail. Complex build dependencies common in mobile and embedded development, including Android SDKs, iOS build tools, and embedded toolchains, can take five to ten minutes to provision fresh on every run, becoming effectively instant when baked into a custom image.
Best Practices for Image Management
GitHub officially recommends treating custom images as infrastructure-as-code from the outset. This means version controlling image definitions in source repositories, automating image builds on a defined schedule or trigger basis, and establishing regular image rotation procedures to incorporate the latest security updates and patches. Treating images as code enables peer review of changes and ensures reproducibility.
Establish clear naming conventions that effectively communicate image contents and versioning schemes to users. Consider adopting a multi-image strategy with a foundational base image containing organization-wide tooling and security requirements, plus specialized images for specific teams or technology stacks that extend the base. This approach balances standardization with flexibility, allowing teams to optimize for their specific requirements while maintaining organizational consistency and reducing duplication of effort.
Sources
Custom images for GitHub-hosted runners are now generally available – GitHub Changelog