How to Run Commands on Non-x86 Architectures with GitHub Action

name: Run on Architecture
on:
  push:
    branches:
      - main

jobs:
  run_on_arch:
    runs-on: ubuntu-22.04
    name: Build on ARM Architecture
    steps:
      - uses: actions/checkout@v4

      - uses: uraimo/run-on-arch-action@v2
        name: Run commands on ARM
        with:
          arch: armv7
          distro: ubuntu22.04
          githubToken: ${{ github.token }}
          run: |
            uname -a
            echo ::set-output name=uname::$(uname -a)

Run on Architecture

A GitHub Action that executes commands on non-x86 CPU architectures via QEMU.

What is Run on Architecture GitHub Action?​

This GitHub Action allows you to execute commands on non-x86 CPU architectures such as ARM, AARCH64, S390X, and PPC64LE by leveraging QEMU. It enables you to build and test projects on architectures that are not natively supported by GitHub-hosted runners.

How to Run Commands on Non-x86 Architectures​

Use the arch, distro, and run inputs to define the architecture, Linux distribution, and the commands to run in the container.

with:
  arch: armv7
  distro: ubuntu22.04
  run: |
    uname -a

How to Use a Matrix for Architecture Combinations​

You can use a matrix to build on multiple architecture and distribution combinations:

strategy:
  matrix:
    include:
      - arch: aarch64
        distro: ubuntu22.04
      - arch: ppc64le
        distro: alpine_latest

steps:
  - uses: uraimo/run-on-arch-action@v2
    with:
      arch: ${{ matrix.arch }}
      distro: ${{ matrix.distro }}

How to Cache Docker Images with GitHub Token​

To speed up builds, you can cache Docker images using your GitHub token by passing githubToken:

with:
  githubToken: ${{ github.token }}

How to Customize the Container Environment​

You can pass environment variables, customize the shell, and add Docker run arguments:

with:
  env: |
    VAR_NAME=value
  shell: /bin/bash
  dockerRunArgs: |
    --volume "${PWD}/artifacts:/artifacts"

How to Use a Custom Base Image​

If you need to use a custom base image, set the base_image parameter:

with:
  base_image: riscv64/busybox
  arch: none
  distro: none

Supported Architectures and Distributions​

Here are some valid combinations of architecture and Linux distributions:

Invalid combinations will result in a failure.

QEMU Emulation for Architectures​

This action uses QEMU to emulate different architectures. Due to the nature of software emulation, you should expect slower performance compared to running on native x86 architectures.