diff --git a/.github/workflows/package-apisix-runtime-deb-ubuntu20.04.yml b/.github/workflows/package-apisix-runtime-deb-ubuntu20.04.yml
index f1153eaca..7a7dfee7d 100644
--- a/.github/workflows/package-apisix-runtime-deb-ubuntu20.04.yml
+++ b/.github/workflows/package-apisix-runtime-deb-ubuntu20.04.yml
@@ -13,15 +13,57 @@ on:
       - '*.md'
   schedule:
     - cron: '0 0 * * *'
+  workflow_dispatch:
+    inputs:
+      runtime_version:
+        description: "apisix-runtime version to stamp into the package"
+        required: false
+        default: "1.0.1"
+      apisix_nginx_module_ver:
+        description: "apisix-nginx-module tag or branch (empty = the pinned default)"
+        required: false
+        default: ""
+      iteration:
+        description: "package revision, e.g. 0 or 0mybranch"
+        required: false
+        default: "0"
+      image_base:
+        description: "base image"
+        required: false
+        default: "ubuntu"
+      image_tag:
+        description: "base image tag"
+        required: false
+        default: "24.04"
 
 jobs:
   build:
     runs-on: ubuntu-latest
-    timeout-minutes: 60
+    timeout-minutes: 90
     env:
-      BUILD_APISIX_RUNTIME_VERSION: 1.0.1
+      BUILD_APISIX_RUNTIME_VERSION: ${{ inputs.runtime_version || '1.0.1' }}
+      APISIX_NGINX_MODULE_VER: ${{ inputs.apisix_nginx_module_ver || '' }}
+      ITERATION: ${{ inputs.iteration || '0' }}
+      IMAGE_BASE: ${{ inputs.image_base || 'ubuntu' }}
+      IMAGE_TAG: ${{ inputs.image_tag || '24.04' }}
+      BUILDKIT_PROGRESS: plain
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
+
+      - name: validate inputs
+        run: |
+          if [[ ! "$BUILD_APISIX_RUNTIME_VERSION" =~ ^[0-9A-Za-z._-]+$ ]]; then
+            echo "invalid runtime_version: $BUILD_APISIX_RUNTIME_VERSION" >&2
+            exit 1
+          fi
+          if [[ -n "$APISIX_NGINX_MODULE_VER" && ! "$APISIX_NGINX_MODULE_VER" =~ ^[A-Za-z0-9._/-]+$ ]]; then
+            echo "invalid apisix_nginx_module_ver: $APISIX_NGINX_MODULE_VER" >&2
+            exit 1
+          fi
+          if [[ ! "$ITERATION" =~ ^[0-9A-Za-z._+-]+$ ]]; then
+            echo "invalid iteration: $ITERATION" >&2
+            exit 1
+          fi
 
       - name: install dependencies
         run: |
@@ -29,25 +71,32 @@ jobs:
 
       - name: build apisix-runtime deb
         run: |
-          make package type=deb app=apisix-runtime runtime_version=${BUILD_APISIX_RUNTIME_VERSION} image_base=ubuntu image_tag=24.04
-
-      - name: run ubuntu 24.04 docker and mapping apisix-runtime deb into container
-        run: |
-          docker run -itd -v /home/runner/work/apisix-build-tools/apisix-build-tools/output:/output --name ubuntu24.04Instance --net="host" docker.io/ubuntu:24.04 /bin/bash
+          make package type=deb app=apisix-runtime \
+            runtime_version="$BUILD_APISIX_RUNTIME_VERSION" \
+            apisix_nginx_module_ver="$APISIX_NGINX_MODULE_VER" \
+            iteration="$ITERATION" \
+            image_base="$IMAGE_BASE" image_tag="$IMAGE_TAG"
 
-      - name: install deb in container
+      - name: locate the built deb
         run: |
-          docker exec ubuntu24.04Instance bash -c "dpkg -i /output/apisix-runtime_${BUILD_APISIX_RUNTIME_VERSION}-0~ubuntu24.04_amd64.deb"
+          deb=$(ls output/apisix-runtime_*.deb)
+          echo "DEB_PATH=$deb" >> "$GITHUB_ENV"
+          echo "DEB_NAME=$(basename "$deb")" >> "$GITHUB_ENV"
 
-      - name: check and ensure apisix-runtime is installed
+      - name: install the deb in a clean container and check the runtime version
         run: |
-          export APISIX_RUNTIME_VER=$(docker exec ubuntu24.04Instance bash -c "openresty -V" 2>&1 | awk '/-O2 -DAPISIX_RUNTIME_VER=/{print $5}' | awk -v FS="=" '{print $2}')
-          if [ "$APISIX_RUNTIME_VER" != "${BUILD_APISIX_RUNTIME_VERSION}" ]; then exit 1; fi
+          docker run --rm -v "$PWD/output:/output" "$IMAGE_BASE:$IMAGE_TAG" bash -c '
+            set -e
+            dpkg -i "/output/$1"
+            openresty -V 2>&1 | tr " " "\n" | grep -o "APISIX_RUNTIME_VER=.*" > /tmp/ver
+            cat /tmp/ver
+            test "$(cut -d= -f2 /tmp/ver)" = "$2"
+          ' _ "$DEB_NAME" "$BUILD_APISIX_RUNTIME_VERSION"
 
       - name: Publish Artifact
         uses: actions/upload-artifact@v4.0.0
         with:
-          name: apisix-runtime_${{ env.BUILD_APISIX_RUNTIME_VERSION }}-0~ubuntu24.04_amd64.deb
-          path: output/apisix-runtime_${{ env.BUILD_APISIX_RUNTIME_VERSION }}-0~ubuntu24.04_amd64.deb
-          retention-days: 5
+          name: ${{ env.DEB_NAME }}
+          path: ${{ env.DEB_PATH }}
+          retention-days: 14
           if-no-files-found: error
diff --git a/Makefile b/Makefile
index dc67e5f8a..8a10206a2 100644
--- a/Makefile
+++ b/Makefile
@@ -27,6 +27,9 @@ openresty="apisix-runtime"
 artifact="0"
 runtime_version=0
 build_latest=
+### git ref (tag or branch) of apisix-nginx-module to build against;
+### empty keeps the default pinned in build-apisix-runtime.sh
+apisix_nginx_module_ver=
 apisix_repo="https://github.com/apache/apisix"
 apisix_runtime_repo="https://github.com/api7/apisix-build-tools.git"
 dashboard_repo="https://github.com/apache/apisix-dashboard"
@@ -101,6 +104,7 @@ define build_runtime
 		--build-arg IMAGE_BASE=$(image_base) \
 		--build-arg IMAGE_TAG=$(image_tag) \
 		--build-arg BUILD_LATEST=$(build_latest) \
+		--build-arg APISIX_NGINX_MODULE_VER=$(apisix_nginx_module_ver) \
 		--build-arg CODE_PATH=$(4) \
     --platform $(arch) \
 		-f ./dockerfiles/Dockerfile.$(2).$(3) .
@@ -114,6 +118,7 @@ define build_runtime
 		--build-arg IMAGE_BASE=$(image_base) \
 		--build-arg IMAGE_TAG=$(image_tag) \
 		--build-arg BUILD_LATEST=$(build_latest) \
+		--build-arg APISIX_NGINX_MODULE_VER=$(apisix_nginx_module_ver) \
 		--build-arg CODE_PATH=$(4) \
 		--load \
 		--cache-from=$(cache_from) \
diff --git a/build-apisix-runtime.sh b/build-apisix-runtime.sh
index fa231d529..39ae11d0f 100755
--- a/build-apisix-runtime.sh
+++ b/build-apisix-runtime.sh
@@ -33,6 +33,9 @@ if [[ ! "$apisix_nginx_module_ver" =~ ^[A-Za-z0-9._/-]+$ ]]; then
     echo "ERROR: invalid apisix_nginx_module_ver: $apisix_nginx_module_ver" >&2
     exit 1
 fi
+# a branch ref carries slashes, which would turn the checkout into a nested
+# directory and break every path relative to it
+apisix_nginx_module_dir="apisix-nginx-module-${apisix_nginx_module_ver//\//-}"
 wasm_nginx_module_ver="0.7.0"
 lua_var_nginx_module_ver="v0.5.3"
 lua_resty_events_ver="0.2.0"
@@ -111,11 +114,11 @@ else
 fi
 
 if [ "$repo" == apisix-nginx-module ]; then
-    cp -r "$prev_workdir" "./apisix-nginx-module-${apisix_nginx_module_ver}"
+    cp -r "$prev_workdir" "./${apisix_nginx_module_dir}"
 else
     git clone --depth=1 -b "$apisix_nginx_module_ver" -- \
         https://github.com/api7/apisix-nginx-module.git \
-        "apisix-nginx-module-${apisix_nginx_module_ver}"
+        "${apisix_nginx_module_dir}"
 fi
 
 if [ "$repo" == wasm-nginx-module ]; then
@@ -138,7 +141,7 @@ cd ngx_multi_upstream_module-${ngx_multi_upstream_module_ver} || exit 1
 ./patch.sh ../openresty-${OPENRESTY_VERSION}
 cd ..
 
-cd "apisix-nginx-module-${apisix_nginx_module_ver}/patch" || exit 1
+cd "${apisix_nginx_module_dir}/patch" || exit 1
 ./patch.sh ../../openresty-${OPENRESTY_VERSION}
 cd ../..
 
@@ -171,9 +174,9 @@ fi
     $debug_args \
     --add-module=../mod_dubbo-${mod_dubbo_ver} \
     --add-module=../ngx_multi_upstream_module-${ngx_multi_upstream_module_ver} \
-    --add-module="../apisix-nginx-module-${apisix_nginx_module_ver}" \
-    --add-module="../apisix-nginx-module-${apisix_nginx_module_ver}/src/stream" \
-    --add-module="../apisix-nginx-module-${apisix_nginx_module_ver}/src/meta" \
+    --add-module="../${apisix_nginx_module_dir}" \
+    --add-module="../${apisix_nginx_module_dir}/src/stream" \
+    --add-module="../${apisix_nginx_module_dir}/src/meta" \
     --add-module=../wasm-nginx-module-${wasm_nginx_module_ver} \
     --add-module=../lua-var-nginx-module-${lua_var_nginx_module_ver} \
     --add-module=../lua-resty-events-${lua_resty_events_ver} \
@@ -220,7 +223,7 @@ sudo install -d "$OR_PREFIX"/lualib/resty/events/compat/
 sudo install -m 644 lualib/resty/events/compat/*.lua "$OR_PREFIX"/lualib/resty/events/compat/
 cd ..
 
-cd "apisix-nginx-module-${apisix_nginx_module_ver}" || exit 1
+cd "${apisix_nginx_module_dir}" || exit 1
 sudo OPENRESTY_PREFIX="$OR_PREFIX" make install
 cd ..
 
diff --git a/dockerfiles/Dockerfile.apisix-runtime.deb b/dockerfiles/Dockerfile.apisix-runtime.deb
index cda3dfe89..fadb59c9d 100644
--- a/dockerfiles/Dockerfile.apisix-runtime.deb
+++ b/dockerfiles/Dockerfile.apisix-runtime.deb
@@ -10,6 +10,7 @@ ARG RUNTIME_VERSION
 ARG IMAGE_BASE
 ARG IMAGE_TAG
 ARG BUILD_LATEST
+ARG APISIX_NGINX_MODULE_VER
 ARG CODE_PATH
 
 ENV IMAGE_BASE=${IMAGE_BASE}
@@ -17,6 +18,8 @@ ENV IMAGE_TAG=${IMAGE_TAG}
 ENV version=${VERSION}
 ENV runtime_version=${RUNTIME_VERSION}
 ENV build_latest=${BUILD_LATEST:-}
+# empty keeps the default pinned in build-apisix-runtime.sh
+ENV apisix_nginx_module_ver=${APISIX_NGINX_MODULE_VER:-}
 
 COPY ${CODE_PATH} ./
 
diff --git a/dockerfiles/Dockerfile.apisix-runtime.rpm b/dockerfiles/Dockerfile.apisix-runtime.rpm
index 82e3b07ca..bf1d03684 100644
--- a/dockerfiles/Dockerfile.apisix-runtime.rpm
+++ b/dockerfiles/Dockerfile.apisix-runtime.rpm
@@ -10,11 +10,14 @@ ARG RUNTIME_VERSION
 ARG IMAGE_BASE
 ARG IMAGE_TAG
 ARG CODE_PATH
+ARG APISIX_NGINX_MODULE_VER
 
 ENV IMAGE_BASE=${IMAGE_BASE}
 ENV IMAGE_TAG=${IMAGE_TAG}
 ENV version=${VERSION}
 ENV runtime_version=${RUNTIME_VERSION}
+# empty keeps the default pinned in build-apisix-runtime.sh
+ENV apisix_nginx_module_ver=${APISIX_NGINX_MODULE_VER:-}
 
 COPY ${CODE_PATH} ./