Knowledge Vault

ARM64/x64 platform awareness

2 min read

ARM64/x64 platform awareness

Always specify platform explicitly for CI/CD containers to ensure consistent behavior across development and production environments.

Context

Apple Silicon (M1/M2/M3) Macs default to ARM64 architecture for Docker containers. Many CI tools, binaries, and base images are built for x64 (amd64) only. Without explicit platform specification, containers may fail or behave unexpectedly.

Problem

# docker-compose.yml - WRONG: No platform specified
services:
  runner:
    image: myorg/actions-runner:latest
    # On M-series Mac: pulls ARM64 image (if available)
    # On Intel Mac: pulls x64 image
    # Result: Inconsistent behavior, potential binary incompatibilities

When running self-hosted GitHub Actions runners on M-series Macs, ARM64 containers may:

  • Fail to run x64-only binaries (many CI tools)
  • Have performance issues through emulation
  • Produce different build artifacts than production

Solution

Explicitly specify platform in all CI/CD container configurations:

# docker-compose.yml - CORRECT: Explicit platform
services:
  runner:
    image: myorg/actions-runner:latest
    platform: linux/amd64
    # Now always uses x64, regardless of host architecture

For Dockerfiles:

# CORRECT: Pin the platform at build time
FROM --platform=linux/amd64 ubuntu:22.04

For docker run commands:

# CORRECT: Explicit platform flag
docker run --platform linux/amd64 myorg/actions-runner:latest

Reusability

  • Score: 5/5
  • Used in: aloysiusproductions-ops-core self-hosted runners

Trade-offs

  • Pro: Guarantees consistent behavior across architectures
  • Pro: Prevents subtle bugs from architecture differences
  • Pro: Matches production environments (typically x64)
  • Con: Slower on ARM hosts due to emulation (Rosetta 2)
  • Con: Increased resource usage on ARM hosts

Source

Discovered during workflow audit on 2026-01-23. Commit f2ff7c7 added explicit platform: linux/amd64 to docker-compose after CI tools failed on M-series Mac runner host.

Graph View

Backlinks