container/README.md

@@ -63,6 +63,18 @@ runner and developers can pull it without credentials. If you keep it private,
 add `credentials:` under the workflow's `container:` and log the runner into the
 registry.
 
+Pushing a rebuilt image is not enough on its own: `:latest` is a moving tag, and
+act_runner reuses whatever it cached the first time unless `force_pull: true` is
+set (see `runner-config.example.yaml`). Without it the job log says
+`Image exists? true` and the run behaves as though the image were never
+rebuilt — a tool added to the `Containerfile` reads as missing from the image.
+Either set `force_pull`, or refresh the VM's copy by hand:
+
+```bash
+docker pull git.haxx.space/sjg/trx-rs/sdk:latest
+docker run --rm git.haxx.space/sjg/trx-rs/sdk:latest sccache --version
+```
+
 ### macOS note
 
 Apple's `container` CLI builds through a BuildKit helper VM that is configured

container/runner-config.example.yaml

@@ -33,3 +33,9 @@ container:
   options: "--cpus=2 -v /var/cache/sccache:/sccache"
   # Reuse the host VM's Docker network for the built-in cache/artifact server.
   network: "host"
+  # The workflow pulls the SDK image by the moving `:latest` tag. Without this
+  # the runner logs "Image exists? true" and reuses whatever it cached the
+  # first time, so pushing a rebuilt image has no effect until someone pulls
+  # on the VM by hand — which looks like the image is missing a tool it in
+  # fact has. The extra registry round-trip per job is nothing next to a build.
+  force_pull: true