How do I speed up Run-On-Arch builds?

Use the githubToken parameter to cache Docker images in your project's GitHub Package Registry, and leverage the install parameter to pre-install dependencies. However, ensure no secrets are exposed in the cached image layer.

Run-On-Arch vs self-hosted runners for ARM testing: which should I use?

Run-On-Arch is easier to set up and manage within GitHub Actions for multi-arch support, but self-hosted runners offer native performance. Choose Run-On-Arch for convenience and broad architecture coverage; opt for self-hosted if build speed is critical.

Can I use Run-On-Arch for Windows ARM testing?

No, Run-On-Arch currently only supports Linux distributions as listed in the supported platforms table. For Windows ARM, you would need native GitHub runners or self-hosted alternatives.

How to handle segmentation faults in Run-On-Arch?

Update to version 3.0.0 or later, as the README notes this release addresses sporadic segmentation faults. Ensure your workflow uses @v3 to mitigate these CI failures.

How do I specify a custom base image in Run-On-Arch?

Set arch and distro to 'none' and use the base_image parameter with the Docker image name, e.g., '--platform=linux/riscv64 riscv64/ubuntu:24.04'. Be aware of the caching limitation for multiple custom images in a workflow.

Does Run-On-Arch support RISC-V?

Yes, it supports riscv64 with distros like Ubuntu 20.04/22.04/24.04 and Alpine Edge, as shown in the supported platforms table, making it useful for testing on emerging architectures.

Open-Awesome

Run your job on another architecture: arm32, aarch64 and others

BSD-3-ClauseShellv3.1.0

A GitHub Action that executes jobs on non-x86 CPU architectures (ARM, s390x, ppc64le, RISC-V) via QEMU emulation.

GitHub

745 stars168 forks0 contributors

What is Run your job on another architecture: arm32, aarch64 and others?

Run-On-Arch is a GitHub Action that allows developers to run CI/CD jobs on non-x86 CPU architectures like ARM, s390x, ppc64le, and RISC-V through QEMU emulation. It solves the problem of testing and building software for multiple platforms when GitHub's hosted runners only support x86 architecture, enabling cross-platform compatibility checks directly in GitHub workflows.

Target Audience

Developers and teams using GitHub Actions for CI/CD who need to test, build, or run software on ARM, IBM Z, PowerPC, or RISC-V architectures as part of their workflow.

Value Proposition

Developers choose Run-On-Arch because it provides a simple, integrated solution for multi-architecture testing without requiring custom self-hosted runners or complex emulation setup, with support for multiple Linux distributions and Docker image caching for faster builds.

Overview

A Github Action that executes jobs/commands on non-x86 cpu architectures (ARMv6, ARMv7, aarch64, s390x, ppc64le, riscv64) via QEMU

Use Cases

Best For

Testing software compatibility across ARM, PowerPC, and s390x architectures
Building binaries or packages for multiple CPU architectures in CI pipelines
Running integration tests on RISC-V or other emerging architectures
Developing embedded or IoT software that targets ARMv6/ARMv7 platforms
Creating platform-specific Docker images via GitHub Actions
Validating cross-compilation outputs on actual target architectures

Not Ideal For

Performance-critical CI pipelines where emulation slowdown would significantly impact build times
Projects requiring testing on actual physical hardware for accurate embedded systems validation
Workflows that need to test non-Linux operating systems like Windows ARM or macOS
Organizations with strict security policies against caching Docker images in public registries

Pros & Cons

Pros

Wide Architecture Support

Supports ARMv6, ARMv7, aarch64, s390x, ppc64le, and riscv64, enabling testing on virtually all major non-x86 architectures without setting up custom runners.

Flexible Distro Matrix

Works with multiple Linux distributions including Ubuntu, Debian, Fedora, Alpine, and Arch across various versions, allowing precise environment matching for different use cases.

Efficient Caching System

Optional githubToken integration caches Docker images in the project's GitHub Package Registry, speeding up subsequent builds by avoiding re-downloads, as highlighted in the README examples.

Seamless GitHub Integration

Designed to work with GitHub's matrix strategy for parallel testing across arch/distro combinations, making it easy to set up complex CI workflows without external tools.

Cons

Emulation Performance Penalty

Relies on QEMU for software emulation, which the README explicitly warns causes 'a visible impact on performance' compared to native execution, slowing down CI jobs significantly.

Public Image Security Risk

When using the install parameter with githubToken, the resulting image layer is cached publicly in GitHub Package Registry, risking exposure if secrets are inadvertently included in the container state or logs.

Limited Custom Image Caching

The README notes a 'known limitation' where only one base_image configuration can be cached per workflow, reducing flexibility for complex matrix setups with multiple custom images.

Frequently Asked Questions

Related Projects

action-tmate

Debug your GitHub Actions via SSH by using tmate to get access to the runner system itself.

Stars3,531

Forks328

Last commit11 days ago

Paths Filter

Conditionally run actions based on files modified by PR, feature branch or pushed commits

Stars3,100

Forks370

Last commit19 days ago

Setup ssh-agent

GitHub Action to setup `ssh-agent` with a private key

Stars1,458

Forks293

Last commit1 month ago

GitHub Actions to compile LaTeX documents

:octocat: GitHub Action to compile LaTeX documents

Stars1,371

Forks151