From 2afbbddee5504a77843b7b5963d98d02cde5af4f Mon Sep 17 00:00:00 2001
From: Hodlinator <172445034+hodlinator@users.noreply.github.com>
Date: Tue, 18 Nov 2025 14:01:05 +0100
Subject: [PATCH 1/2] doc: CI - Clarify how important `env -i` is and why

Would hopefully have helped me in this case: https://github.com/bitcoin/bitcoin/pull/31176#issuecomment-2526410039
Since then however, fd813bf863b1ffa91429de6342285b35bab2bfa4 also made sure a minimal environment is used.
---
 ci/README.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/ci/README.md b/ci/README.md
index a7291284b33..91a3cee30ad 100644
--- a/ci/README.md
+++ b/ci/README.md
@@ -28,8 +28,10 @@ the CI locally you may need to reduce that entropy by running:
 sudo sysctl -w vm.mmap_rnd_bits=28
 ```
 
-It is recommended to run the ci system in a clean env. To run the test stage
-with a specific configuration,
+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.
+To run the test stage with a specific configuration:
 
 ```
 env -i HOME="$HOME" PATH="$PATH" USER="$USER" bash -c 'FILE_ENV="./ci/test/00_setup_env_arm.sh" ./ci/test_run_all.sh'

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 2/2] 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.