Build multi-architecture container images with GitHub Arm-hosted runners
Introduction
Build options for multi-architecture container images
Arm-hosted runners for public repositories
Create a new Arm-hosted runner for private repositories
Run GitHub Actions jobs on the Arm-hosted runner
Next Steps
Build multi-architecture container images with GitHub Arm-hosted runners
Who is this for?
This is an introductory topic for software developers who want to learn how to use Arm-hosted runners for GitHub Actions jobs.
What will you learn?
Upon completion of this Learning Path, you will be able to:
- Build Arm images and multi-architecture images with Arm-hosted runners.
- Use GitHub Actions to automate image builds.
Prerequisites
Before starting, you will need the following:
- A GitHub account (a Team or Enterprise Cloud plan is required for private repositories).
- A Docker Hub account.
Summary
This summary was drafted with an approved AI-assisted workflow and reviewed by Arm contributors before publication. Human technical review remains part of the process so the final page reflects engineering rigor, accuracy, and Arm editorial standards.
You’ll build and publish multi-architecture container images with GitHub Actions using Arm-hosted runners. You’ll compare common build options, including emulation and native builds assembled with a manifest, then run workflows on Arm-managed arm64 runners for public or private repositories. You’ll create a repository, configure secrets for Docker Hub, and define a workflow that builds images for arm64 alongside amd64, then pushes a multi-architecture image. You’ll also review available runner types for private repositories. After triggering a workflow and verifying that Docker Hub lists a manifest with arm64 and amd64 platforms, you’ll confirm that the build and publication steps completed as intended.
Frequently asked questions
These FAQs were drafted with an approved AI-assisted workflow and reviewed by Arm contributors before publication. Human technical review remains part of the process so the final page reflects engineering rigor, accuracy, and Arm editorial standards.
Check the Actions run details for the runner name or labels that indicate an Arm architecture and confirm the workflow selects the Arm-hosted runner. If the run shows a different runner, review the
runs-on setting in the workflow.Confirm the account uses a Team or Enterprise Cloud plan because private repositories require it for Arm-hosted runners. If it still doesn’t appear, review the repository or organization runner settings.
The path explains emulation and manifest-based builds, then uses Arm-hosted runners to perform native arm64 builds and assemble a multi-architecture image. The workflow relies on native Arm execution rather than instruction emulation for the arm64 build.
Add the required registry credentials as repository secrets and reference them in the workflow. Without these secrets, the push step fails to authenticate.
Expect a successful Actions run and a new image tag on Docker Hub with a multi-architecture manifest listing arm64 and amd64. If the platforms are missing, review the build logs to see which architecture jobs ran and which images were pushed.