From c124ca5dcd42193dcfa2b233a6a4d72a768e0d4a Mon Sep 17 00:00:00 2001
From: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Date: Wed, 24 Jun 2026 23:38:57 -0700
Subject: [PATCH] docs: document hack/ci/ci.sh lima workflow in test/README.md

Signed-off-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
---
 test/README.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/test/README.md b/test/README.md
index 986e4e92a04..4dec2e91bdc 100644
--- a/test/README.md
+++ b/test/README.md
@@ -42,6 +42,36 @@ go test -v ./libpod/
 go test -v -run TestMyFunction ./pkg/specgen/
 ```
 
+## Reproducing CI failures locally with lima
+
+`hack/ci/ci.sh` runs a CI test suite inside the same lima VM image used by
+upstream CI. The script requires `limactl`, starts a nested-virtualization VM
+with 8 GB of memory, copies this repository into the VM, and runs
+`hack/ci/runner.sh` there, so the host distro does not matter.
+
+The invocation is positional and takes 2 to 4 arguments:
+
+```bash
+hack/ci/ci.sh TEST DISTRO
+hack/ci/ci.sh TEST PRIV DISTRO
+hack/ci/ci.sh TEST MODE PRIV DISTRO
+```
+
+`TEST` is the suite, one of `build`, `apiv2`, `bindings`, `bud`, `compose_v2`,
+`docker_py`, `unit`, `upgrade`, `int`, `sys`, or `machine`. `MODE` is `local`
+or `remote` and defaults to `local`. `PRIV` is `root` or `rootless` and defaults
+to `rootless`. `DISTRO` must be one of `fedora-current`, `fedora-prior`,
+`fedora-rawhide`, or `debian-sid`.
+
+For the `upgrade` suite the `MODE` slot is reused to pass the version to upgrade
+from (e.g. `v5.3.1`) rather than `local`/`remote`.
+
+```bash
+hack/ci/ci.sh sys remote rootless fedora-current
+```
+
+Some parts of the test suite cannot run inside the VM.
+
 # Test utils
 Test utils provide common functions and structs for testing. It includes two structs:
 * `PodmanTest`: Handle the *podman* command and other global resources like temporary