Skip to main content
← Back to workflows

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

uraimo-run-on-arch-action -
GitHub Action
2.7.2
GitHub Org's stars
Contributors
Categories
CICube banner
The GitHub Actions dashboard helps you spot bottlenecks and optimize your CI pipeline with actionable insights.
Usage
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-arch-action logo

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:

ArchitectureSupported Distros
armv6stretch, buster, bullseye, alpine_latest
armv7ubuntu20.04, ubuntu22.04, alpine_latest
aarch64ubuntu22.04, fedora_latest, alpine_latest
ppc64lealpine_latest, ubuntu22.04
s390xubuntu22.04, bullseye, alpine_latest

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.

Monitoring GitHub Actions Workflows

CICube is a GitHub Actions monitoring tool that provides you with detailed insights into your workflows to further optimize your CI/CD pipeline. With CICube, you will be able to track your workflow runs, understand where the bottlenecks are, and tease out the best from your build times. Go to cicube.io now and create a free account to better optimize your GitHub Actions workflows!

CICube GitHub Actions Workflow Duration Monitoring