diff --git a/.ci/debug/install_utils.sh b/.ci/debug/install_utils.sh
new file mode 100755
index 00000000..b6fcabbd
--- /dev/null
+++ b/.ci/debug/install_utils.sh
@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+
+exec curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
diff --git a/.ci/debug/libdebug.sh b/.ci/debug/libdebug.sh
new file mode 100755
index 00000000..34aa3cc8
--- /dev/null
+++ b/.ci/debug/libdebug.sh
@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+
+infinite_sleep() {
+    echo "Sleeping in foreground..."
+    echo "Attach to container with:"
+    echo
+    echo "-"
+    echo '  docker exec -it $(docker ps -q --filter name=act-*) /bin/bash'
+    echo
+    echo "-"
+    echo
+    echo "Or, to kill this container:"
+    echo "-"
+    echo '  docker kill $(docker ps -q --filter name=act-*)'
+    echo "-"
+
+    echo "(Sleeping now... ctrl+c might not be enough to kill me)"
+
+    while :
+    do
+        sleep 10 &
+        wait $!
+    done
+
+    exit 2
+}
diff --git a/.ci/debug/payloads/commit-event.json b/.ci/debug/payloads/commit-event.json
new file mode 100644
index 00000000..0dc70bd5
--- /dev/null
+++ b/.ci/debug/payloads/commit-event.json
@@ -0,0 +1,5 @@
+{
+  "head_commit": {
+    "message": "Blah blah blah"
+  }
+}
diff --git a/.ci/debug/run_act.sh b/.ci/debug/run_act.sh
new file mode 100755
index 00000000..c8b5e323
--- /dev/null
+++ b/.ci/debug/run_act.sh
@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+
+DEBUG_DIR="$(cd -P -- "$(dirname -- "$0")" && pwd -P)"
+REPO_DIR="$DEBUG_DIR/../.."
+DEBUG_REL_DIR=".ci/debug/"
+
+ACT_TARGET_ACTION="${1-build_and_deploy_preview}"
+if test -n "$ACT_TARGET_ACTION" ; then
+    shift
+fi
+
+ACT_EVENT_PAYLOAD="${1-"${DEBUG_REL_DIR}"payloads/commit-event.json}"
+if test -n "$ACT_EVENT_PAYLOAD" ; then
+    shift
+fi
+
+# note: remaining arguments will be passed to `act` in final `exec`
+
+# need to use "no" so that act doesn't ask the user to set it
+# BREAK_INTERACTIVE_BEFORE_INSTALL=${"$BREAK_INTERACTIVE_BEFORE_INSTALL"-"no"}
+
+pushd "$REPO_DIR"
+trap "popd" exit
+
+echo "All config variables are OPTIONAL. Simply press enter to skip one."
+echo "Current variables set:"
+echo
+echo -n "  BREAK_INTERACTIVE_BEFORE_INSTALL=\"${BREAK_INTERACTIVE_BEFORE_INSTALL}\""
+echo "        # If non-empty, infinite sleep before yarn install"
+echo
+echo "---"
+echo
+
+# act docs: https://github.com/nektos/act
+exec act \
+    -j "${ACT_TARGET_ACTION}" \
+    -e "$ACT_EVENT_PAYLOAD" \
+    -s BREAK_INTERACTIVE_BEFORE_INSTALL="$BREAK_INTERACTIVE_BEFORE_INSTALL" \
+    "$@"
diff --git a/.ci/debug/run_act_break_before_install.sh b/.ci/debug/run_act_break_before_install.sh
new file mode 100755
index 00000000..0b18b111
--- /dev/null
+++ b/.ci/debug/run_act_break_before_install.sh
@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+DEBUG_DIR="$(cd -P -- "$(dirname -- "$0")" && pwd -P)"
+
+# Set flag to be checked by install.sh when it sources debug_install.sh
+export BREAK_INTERACTIVE_BEFORE_INSTALL=yes
+exec "$DEBUG_DIR"/run_act.sh "$@"
diff --git a/.ci/debug/setup_debugging.sh b/.ci/debug/setup_debugging.sh
new file mode 100755
index 00000000..9e827ef7
--- /dev/null
+++ b/.ci/debug/setup_debugging.sh
@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+
+# The GitHub workflow should conditionally call this script when running in ACT
+
+if ! test -n "$ACT" ; then
+    echo "Fatal Error: Cannot call debug_preinstall.sh when not running inside ACT"
+    exit 1
+fi
+
+# `yarn` should be installed in GitHub actions, but when we're debugging
+# with `act`, the 500MB container doesn't include `yarn`, so install it
+if ! which yarn ; then
+    echo "------"
+    echo "Yarn not found (running in act?) - install it..."
+    echo "Node version: $(node --version)"
+    echo "------"
+
+    set -e
+    apt-get update -qq
+    apt-get install -yy curl gnupg2
+    curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
+    echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
+
+    # Also, for some reason we nede to reinstall Node for this to work
+    curl -sL https://deb.nodesource.com/setup_15.x | bash -
+    apt-get install -yy nodejs
+    apt-get install --no-install-recommends yarn
+    set +e
+fi
+
diff --git a/.ci/install.sh b/.ci/install.sh
index 443c7937..be521451 100755
--- a/.ci/install.sh
+++ b/.ci/install.sh
@@ -3,8 +3,12 @@
 CI_DIR="$(cd -P -- "$(dirname -- "$0")" && pwd -P)"
 SPLITGRAPH_DIR="$CI_DIR/.."
 
-if test ! -z "$YARN_CACHE_FOLDER" ; then
+if test -n "$ACT" ; then
+    . "$CI_DIR"/debug/libdebug.sh
+fi
 
+# yarn cache is per branch by default. Clear it with commit pragma [clear cache]
+if test ! -z "$YARN_CACHE_FOLDER" ; then
     if git log --format=%B HEAD -n1 | grep -q '[clear cache]' ; then
         >&2 echo "Clear cache ${YARN_CACHE_FOLDER}..."
         test -d "$YARN_CACHE_FOLDER" && rm -r "$YARN_CACHE_FOLDER"
@@ -14,6 +18,13 @@ if test ! -z "$YARN_CACHE_FOLDER" ; then
     echo "Yarn cache ($YARN_CACHE_FOLDER): $(ls -l "$YARN_CACHE_FOLDER" | wc -l)"
 fi
 
+# For debugging: Sleep in foreground so user can attach to container
+# (I couldn't find how to force act to run the container in interactive mode)
+if test -n "$BREAK_INTERACTIVE_BEFORE_INSTALL" ; then
+    echo "BREAK_INTERACTIVE_ON_INSTALL is set (not empty)"
+    infinite_sleep
+fi
+
 # We need to set the special lockfile name here, because if we use yarn.lock,
 # then when running in the parent monorepo, yarn will think its in its own root
 export WORKSPACE_LOCKFILE=yarn-public-workspace.lock
diff --git a/.github/workflows/build_and_deploy_preview.yml b/.github/workflows/build_and_deploy_preview.yml
index 9c074cdb..c11971b7 100644
--- a/.github/workflows/build_and_deploy_preview.yml
+++ b/.github/workflows/build_and_deploy_preview.yml
@@ -12,7 +12,10 @@ jobs:
       - name: Use Node.js
         uses: actions/setup-node@v1
         with:
-          node-version: 13.x
+          node-version: 15.x
+      - name: Setup ACT debugging container
+        if: ${{ env.ACT }}
+        run: ./.ci/debug/setup_debugging.sh
       - run: ./setup.sh
       - uses: actions/cache@v1
         with:
@@ -21,6 +24,9 @@ jobs:
       - run: ./.ci/install.sh
         env:
           YARN_CACHE_FOLDER: /home/runner/yarn-cache
+
+          # For debugging only, but must be defined here or `act` ignores it
+          BREAK_INTERACTIVE_BEFORE_INSTALL: ${{ secrets.BREAK_INTERACTIVE_BEFORE_INSTALL }}
       - run: ./.ci/build.sh
         env:
           DOCSEARCH_PUBLIC_CLIENT_API_KEY: ${{ secrets.DOCSEARCH_PUBLIC_CLIENT_API_KEY }}
diff --git a/README.md b/README.md
index bfb43a14..2482cb09 100644
--- a/README.md
+++ b/README.md
@@ -22,3 +22,22 @@
 
 - `yarn dev`
   - Run this script to start dev of the docs, after running `yarn install`
+
+## debugging CI
+
+```bash
+
+# Start `act`
+.ci/debug/run_act.sh
+
+# "Break" before running bulk of install step (see `install.sh`)
+.ci/debug/run_act_break_before_install.sh
+
+# The "break" is just an infinite loop of `sleep 10`
+# To get an interactive shell, need to `docker exec` into that container
+
+docker exec -it $(docker ps -q --filter name=act-*) /bin/bash
+
+# If you need to kill the container
+docker kill $(docker ps -q --filter name=act-*)
+```