diff --git a/.woodpecker.yml b/.woodpecker.yml
new file mode 100644
index 0000000..cfefb6d
--- /dev/null
+++ b/.woodpecker.yml
@@ -0,0 +1,17 @@
+pipeline:
+  lint:
+    image: git.qcode.ch/nakamochi/ci-zig0.10.1:v2
+    commands:
+      - ./tools/fmt-check.sh
+  test:
+    image: git.qcode.ch/nakamochi/ci-zig0.10.1:v2
+    commands:
+      - zig build test
+  aarch64:
+    image: git.qcode.ch/nakamochi/ci-zig0.10.1:v2
+    commands:
+      - zig build -Ddriver=fbev -Dtarget=aarch64-linux-musl
+  sdl2:
+    image: git.qcode.ch/nakamochi/ci-zig0.10.1:v2
+    commands:
+      - zig build -Ddriver=sdl2
diff --git a/README.md b/README.md
index 4a4959f..262cb0d 100644
--- a/README.md
+++ b/README.md
@@ -40,7 +40,38 @@ when browsing `git blame`:
 
     git config blame.ignoreRevsFile .git-blame-ignore-revs
 
-see also the contributing section.
+see also the [contributing](#contributing) section.
+
+## CI automated checks
+
+the CI runs code format checks, tests and builds for fbdev+evdev on aarch64
+and SDL2. it requires a container image with zig and clang tools such as
+clang-format.
+
+to make a new image and switch the CI to use it, first modify the
+[ci-containerfile](tools/ci-containerfile) and produce the image locally:
+
+    podman build --rm -t ndg-ci -f ./tools/ci-containerfile \
+      --build-arg ZIGURL=https://ziglang.org/download/0.10.1/zig-linux-x86_64-0.10.1.tar.xz
+
+then tag it with the target URL, for example:
+
+    podman tag localhost/ndg-ci git.qcode.ch/nakamochi/ci-zig0.10.1:v1
+
+generate an [access token](https://git.qcode.ch/user/settings/applications),
+login to the container registry and push the image to remote:
+
+    podman login git.qcode.ch
+    podman push git.qcode.ch/nakamochi/ci-zig0.10.1:v1
+
+the image will be available at
+https://git.qcode.ch/nakamochi/-/packages/
+
+finally, delete the access token from
+https://git.qcode.ch/user/settings/applications
+
+what's left is to update the CI [build pipeline](.woodpecker.yml) and delete
+the older version of the image.
 
 ## contributing
 
diff --git a/tools/ci-containerfile b/tools/ci-containerfile
new file mode 100644
index 0000000..31babd9
--- /dev/null
+++ b/tools/ci-containerfile
@@ -0,0 +1,15 @@
+# ci container file for compiling and testing zig projects.
+# requires a ZIGURL build arg. for instance:
+# podman build --rm -t ci-zig0.10.1 -f ci-containerfile \
+#   --build-arg ZIGURL=https://ziglang.org/download/0.10.1/zig-linux-x86_64-0.10.1.tar.xz
+
+FROM alpine:3.17.1
+
+ARG ZIGURL
+RUN apk add --no-cache curl xz sdl2-dev clang15-extra-tools && \
+    mkdir -p /tools/zig && \
+    cd /tools/zig && \
+    curl -o zig.tar.xz $ZIGURL && \
+    tar -xf zig.tar.xz --strip-components=1 && \
+    rm zig.tar.xz
+ENV PATH="/tools/zig:$PATH"