Skip to content

ADR 0005 — Multi-arch container images, Cosign keyless and SBOM attestations

  • Status: Accepted
  • Date: 2026-04-27
  • Deciders: André Luiz Gallon

Context

The project is open source and meant to be deployed on heterogeneous hardware (Apple Silicon laptops, Linux servers, ARM64 SBCs). We also want consumers to be able to verify that the image they pull is the artefact actually built by our CI from this repository, and to know exactly which packages are inside.

Decision

  • The release pipeline (.github/workflows/release.yml) is triggered on tags v* and produces, for both services:
  • Multi-arch images (linux/amd64, linux/arm64) pushed to ghcr.io/<owner>/web-agent-{agent,dashboard} with semver tags (vX.Y.Z, X.Y, latest).
  • Cosign keyless signature using GitHub OIDC — no long-lived keys are stored anywhere.
  • SPDX SBOM generated by Syft and attached as a registry attestation via actions/attest-sbom.
  • A GitHub Release with auto-generated notes (commits since the previous tag) and the SBOM JSON files attached.
  • Verification command is published in the release notes: 
    cosign verify ghcr.io/<owner>/web-agent-agent:vX.Y.Z \
  --certificate-identity-regexp "https://github.com/.*/.github/workflows/release.yml@refs/tags/v.*" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Consequences

  • ✅ Consumers can prove that an image was built by this repo's CI on a specific tag — basis for SLSA Level 3 provenance.
  • ✅ ARM64 hosts (Raspberry Pi, AWS Graviton, Apple Silicon dev VMs) pull native images.
  • ✅ SBOM in the registry makes vulnerability triage tractable.
  • ⚠️ Multi-arch builds are slower in CI (~5–10 min); buildx cache scoped per arch keeps it acceptable.

Alternatives considered

  • Long-lived signing keys checked into a Vault — keyless OIDC is simpler, more secure and cheaper.
  • Notation — Cosign has wider tooling adoption today and the same threat model.