Skip to main content

ARM Runners for GitHub Actions

Overview​

When building Docker images for multiple architectures (particularly ARM64/linux/arm64), you have two options:

  1. Cross-compilation - Build ARM64 images on x86_64 runners (default)
  2. Native compilation - Build ARM64 images on native ARM64 runners

Current Workflow Behavior​

Our Docker build workflow is configured to:

  • Build images for both architectures: linux/amd64 and linux/arm64
  • Default: Build all images on x86_64 hosts regardless of target architecture (cross-compilation)
  • Upload individual architecture images to Artifactory (no tags, just digest)
  • Combine them into a manifest list with appropriate tags

Why ARM Runners?​

GitHub's Limitations​

  • GitHub's shared Linux ARM runners are only available for public repositories
  • Private repositories need to provision their own ARM runners for native builds

Benefits of Native ARM Builds​

  • Faster build times for ARM64 images (no emulation overhead)
  • Better compatibility with some ARM-specific dependencies
  • Reduced resource usage compared to cross-compilation

How to Provision ARM Runners​

Prerequisites​

  • GitHub repository with Actions enabled
  • ARM64 host machine (physical or cloud instance)
  • Repository admin permissions

Steps​

  1. Prepare ARM64 Host

    # On your ARM64 machine (e.g., AWS Graviton, Apple Silicon, etc.)
    # Install Docker and other dependencies
    sudo apt update && sudo apt install -y docker.io

  2. Register Runner

    • Go to your GitHub repository → Settings → Actions → Runners
    • Click "New self-hosted runner"
    • Select "Linux" and "ARM64"
    • Follow the provided commands to download and configure the runner

  3. Configure Runner

    # Download runner (use the specific URL from GitHub)
    curl -o actions-runner-linux-arm64-2.x.x.tar.gz -L https://github.com/actions/runner/releases/download/v2.x.x/actions-runner-linux-arm64-2.x.x.tar.gz

    # Extract and configure
    tar xzf ./actions-runner-linux-arm64-2.x.x.tar.gz
    ./config.sh --url https://github.com/your-org/your-repo --token YOUR_TOKEN

  4. Install as Service

    sudo ./svc.sh install
    sudo ./svc.sh start

Using ARM Runners in Workflows​

Default Behavior (Cross-compilation)​

# No additional configuration needed
# All builds happen on x86_64 runners

Native ARM Builds​

# Override the default in your workflow
# Pass values to enable native ARM builds
build:
  uses: ./.github/workflows/docker-build.yml
  with:
    use_native_arm: true  # Example parameter

Key Differences​

AspectCross-compilation (Default)Native ARM Builds
SetupNo additional setup requiredRequires provisioned ARM runner
Build SpeedSlower for ARM64 imagesFaster for ARM64 images
Resource UsageHigher CPU usage on x86_64Distributed across architectures
CompatibilityMay have edge casesBetter compatibility
CostUses existing runnersAdditional runner infrastructure

When to Use Native ARM Runners​

Consider provisioning ARM runners when:

  • You have frequent ARM64 builds
  • Build times are critical
  • You encounter ARM-specific compatibility issues
  • Your project has ARM-specific dependencies

Troubleshooting​

Common Issues​

  • Runner not appearing: Check network connectivity and firewall rules
  • Build failures: Ensure Docker is properly installed and configured
  • Permission errors: Verify runner service has appropriate permissions

Debug Commands​

# Check runner status
sudo ./svc.sh status

# View runner logs
sudo journalctl -u actions.runner.your-org-your-repo.your-runner

Additional Resources​