github-actions-container-build

GitHub Actions Container Build

Build multi-architecture container images in GitHub Actions using Podman and native ARM64 runners.

Core Principles

Choose Your Workflow

CRITICAL: Ask these questions before generating any workflow.

Question 1: Is your GitHub repository public?

• Yes → Use github-actions-workflow-matrix-build.yml (free standard ARM64 runners, 10-50x faster)
• No → Go to Question 2

Question 2: Do you have GitHub Team/Enterprise + willing to pay for ARM64 builds?

• Yes → Use ARM64 larger runners (custom setup required, paid per minute)
• No → Use github-actions-workflow-qemu.yml (free QEMU emulation, slower but works on free tier)

1. Push-by-Digest (2025 Best Practice - Default)

Matrix builds use push-by-digest pattern:

• Images pushed by digest without intermediate :amd64/:arm64 tags
• Only tiny digest files (~70 bytes) transfer as artifacts
• Registry stays clean (no tag clutter)
• Same debug experience with --platform flag

# Build job
- name: Push by digest
  run: |
    podman push \
      --digestfile /tmp/digest \
      localhost/build:${{ matrix.arch }} \
      docker://${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}

# Merge job
- name: Create manifest from digests
  run: |
    podman manifest create "$IMAGE:latest"
    podman manifest add "$IMAGE:latest" "docker://$IMAGE@${AMD64_DIGEST}"
    podman manifest add "$IMAGE:latest" "docker://$IMAGE@${ARM64_DIGEST}"
    podman manifest push --all "$IMAGE:latest" "docker://$IMAGE:latest"

Debug specific architecture:

podman pull --platform linux/arm64 ghcr.io/OWNER/REPO:latest

2. Matrix Builds (Public Repos)

For public repositories - use GitHub-hosted standard ARM64 runners:

• 10-50x faster builds (native vs. emulation)
• Better reliability and accuracy
• Lower CI costs
• Completely free for public repos
• Not available for private repos

strategy:
  matrix:
    include:
      - arch: amd64
        runner: ubuntu-24.04
      - arch: arm64
        runner: ubuntu-24.04-arm  # Standard ARM64 runner (public repos only)