docs: add tutorial on running GitHub Actions locally with act

Explains using act to run the existing docker-build.yml workflow (job: build)
locally before pushing. Notes act cannot run the windows-build.yml job.
Verified locally with act -j build — job succeeded.

Author: behnamasadi

README.md

@@ -227,6 +227,7 @@ See **[BUILDING.md](BUILDING.md)** for CMake configuration, Docker usage (includ
 - [Memory Error Detection with AddressSanitizer and Valgrind](docs/memory_leaking_valgrind.md)
 - [Generating and Debugging Dump File](docs/generating_and_debugging_dump_file.md)
 - [Static analysis and linting with clang-tidy](docs/clang_tidy.md)
+- [Running GitHub Actions locally with `act` (test CI before you push)](docs/run_github_actions_locally_with_act.md)
 
 ## Data File Storage Parsing
 

docs/run_github_actions_locally_with_act.md

@@ -0,0 +1,141 @@
+# Running GitHub Actions Locally with `act`
+
+Push, wait for GitHub, watch it fail, fix, push again — that loop is slow.
+[`act`](https://github.com/nektos/act) runs your **existing** GitHub Actions
+workflows on your own machine inside Docker, using the **same
+`.github/workflows/*.yml` files** — no extra config, no duplicated scripts.
+Get it green locally, *then* push.
+
+> This is the plain, standard tool most developers use. There is nothing to
+> customize: `act` reads the workflow you already have.
+
+---
+
+## 1. Prerequisite: Docker
+
+`act` runs each job in a container, so Docker must be installed and running:
+
+```bash
+docker --version      # must succeed
+docker ps             # daemon must be up
+```
+
+If Docker isn't installed, see https://docs.docker.com/engine/install/.
+
+---
+
+## 2. Install `act`
+
+Pick whichever fits your setup — they all install the same tool:
+
+```bash
+# a) One-line install script (Linux/macOS) → installs to ./bin or a path you give
+curl -sSL https://raw.githubusercontent.com/nektos/act/master/install.sh | bash -s -- -b ~/.local/bin
+
+# b) As a GitHub CLI extension (if you already have `gh`)
+gh extension install nektos/gh-act      # then run it as:  gh act ...
+
+# c) Package managers
+brew install act                        # macOS / Linuxbrew
+# Arch:            sudo pacman -S act
+# Windows (choco): choco install act-cli
+```
+
+Verify:
+
+```bash
+act --version
+```
+
+---
+
+## 3. First run: choose an image size
+
+The **first** time you run `act`, it asks which runner image to use. Pick
+**Medium** — it's the standard `catthehacker/ubuntu` image that has git, curl,
+build-essential, etc. (The choice is saved to `~/.actrc`.)
+
+```
+? Please choose the default image you want to use with act:
+  - Large   (~17GB, closest to GitHub's runner)
+  > Medium  (~500MB, has the common tools)   ← choose this
+  - Micro   (~200MB, node only)
+```
+
+---
+
+## 4. Everyday commands
+
+```bash
+act -l                 # list the jobs act found in .github/workflows
+act                    # run the default event (push) — runs all matching jobs
+act -j build           # run ONE job by id (recommended)
+act pull_request       # simulate a pull_request event instead of push
+act -n                 # dry run: print the plan, execute nothing
+act -v                 # verbose, when something misbehaves
+```
+
+### For THIS repo
+
+The CI here builds inside Docker (`docker-build.yml`, job id **`build`**,
+runner `ubuntu-24.04`):
+
+```bash
+act -j build
+```
+
+`act` automatically shares your host's Docker daemon with the job, so the
+workflow's own `docker build ...` steps work without extra flags.
+
+---
+
+## 5. The workflow: green locally → push
+
+```bash
+act -j build           # 1. run CI locally
+# ...fix anything that fails, repeat until green...
+git add -A && git commit -m "..."
+git push               # 2. push only once it passed locally
+```
+
+That's the whole idea — no scripts, no hooks required.
+
+### Optional: make it automatic before every push
+
+If you want the check to run on its own, add a one-line Git `pre-push` hook.
+This is optional; `act` on its own is already enough.
+
+```bash
+cat > .git/hooks/pre-push <<'EOF'
+#!/usr/bin/env bash
+act -j build || { echo "❌ local CI failed — push aborted"; exit 1; }
+EOF
+chmod +x .git/hooks/pre-push
+```
+
+Bypass it any time with `git push --no-verify`.
+
+---
+
+## 6. Good to know (limitations)
+
+- **`act` ≈ GitHub, not identical.** It uses `catthehacker` images, not
+  GitHub's exact runner image. Close enough to catch the vast majority of
+  failures; for maximum parity choose the **Large** image.
+- **Linux jobs only.** `act` cannot run `windows-latest` or `macos-latest`
+  jobs. This repo's `windows-build.yml` therefore **cannot** run under `act` —
+  only the Linux `docker-build.yml` job does.
+- **First run is slow** — it pulls the runner image (and here, builds the
+  project's Docker image). Later runs reuse cached layers and are much faster.
+- **Secrets:** pass them with `act -s NAME=value` or `--secret-file` if a
+  workflow needs them (this repo's build doesn't).
+
+---
+
+## TL;DR
+
+```bash
+docker ps                 # Docker running?
+act -l                    # what jobs exist?
+act -j build              # run CI locally  → green? then git push
+```