From 552eb90071fd246ba40037f74329403b72453047 Mon Sep 17 00:00:00 2001
From: Hodlinator <172445034+hodlinator@users.noreply.github.com>
Date: Mon, 17 Nov 2025 15:06:56 +0100
Subject: [PATCH] doc: CI - Describe qemu-user-static usage

Should help in cases such as: https://github.com/bitcoin/bitcoin/pull/31144#issuecomment-2450578651
---
 ci/README.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/ci/README.md b/ci/README.md
index 91a3cee30ad..9abfce14fc1 100644
--- a/ci/README.md
+++ b/ci/README.md
@@ -28,6 +28,15 @@ the CI locally you may need to reduce that entropy by running:
 sudo sysctl -w vm.mmap_rnd_bits=28
 ```
 
+To run a test that requires emulating a CPU architecture different from the
+host, we may rely on the container environment recognizing foreign executables
+and automatically running them using `qemu`. The following sets us up to do so
+(also works for `podman`):
+
+```
+docker run --rm --privileged docker.io/multiarch/qemu-user-static --reset -p yes
+```
+
 It is recommended to run the CI system in a clean environment. The `env -i`
 command below ensures that *only* specified environment variables are propagated
 into the local CI.