diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
new file mode 100644
index 0000000..e271185
--- /dev/null
+++ b/.gitlab-ci.yml
@@ -0,0 +1,97 @@
+# GitLab CI for aborist.
+#
+# Runs the unit test suite on every push. Lives at the same shape as
+# the sibling repos (`unsandbox.com`, `unfirehose-nextjs-logger`):
+# `tags: build` selects the in-house runner; `before_script` warms up
+# the venv; `script` runs the actual gate.
+#
+# What's NOT in CI:
+#   - `make test-live` — needs the live Hermes endpoint + populated
+#     shards under ~/.aborist/shards. Run by hand via `make test-live`
+#     when iterating on QA quality.
+#   - `make test-crawler` — needs `[crawler]` extras + network access
+#     to real HTML sites. Opt-in via `make test-crawler` locally.
+#   - `make bench-qa` — runs the live LLM bench, ~30-70 min wall-clock.
+#     Run on demand via `make bench-qa-{quick,smoke}` (10s / 30s) or
+#     full `make bench-qa` (full sweep).
+
+stages:
+  - test
+
+variables:
+  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.pip-cache"
+  # Pin the parallelism factor so we don't oversubscribe on shared
+  # runners. pytest-xdist's `-n auto` reads `os.cpu_count()` which on
+  # cgroup-limited containers can over-report the host's cores. Setting
+  # this var caps the worker count regardless. Local `make test` keeps
+  # using -n auto (untouched by this var).
+  PYTEST_XDIST_AUTO_NUM_WORKERS: "4"
+
+# ----------------------------------------------------------------------
+# Default test job — runs the full unit suite via `make test`, which
+# already passes `-n auto` to pytest-xdist for parallelism. On the
+# in-house runner this finishes in ~11s wall-clock (3.4× the serial
+# cost) for the 641-test suite.
+# ----------------------------------------------------------------------
+test:
+  stage: test
+  tags:
+    - build
+  cache:
+    # Key on pyproject.toml so dependency churn invalidates the cache;
+    # otherwise reuse the venv across CI runs to avoid re-installing
+    # editable + dev extras on every push.
+    key:
+      files:
+        - pyproject.toml
+    paths:
+      - .venv/
+      - .pip-cache/
+  before_script:
+    - python3 --version
+    - test -d .venv || python3 -m venv .venv
+    - .venv/bin/pip install --upgrade pip wheel
+    - .venv/bin/pip install -e '.[dev]'
+  script:
+    # `make test` invokes `pytest -q --ignore=tests/crawler -n auto`.
+    # PYTEST_XDIST_AUTO_NUM_WORKERS env var caps the worker count on
+    # the runner; locally `-n auto` uses the full machine.
+    - make test
+  artifacts:
+    when: on_failure
+    paths:
+      - .pytest_cache/
+    expire_in: 1 week
+
+# ----------------------------------------------------------------------
+# Optional: crawler extras + crawler-tagged tests. Opt-in via the
+# `crawler` keyword so it doesn't gate every push (network access +
+# heavier deps).
+# ----------------------------------------------------------------------
+test-crawler:
+  stage: test
+  tags:
+    - build
+  rules:
+    # Only run when explicitly invoked or commit message asks for it.
+    - if: '$CI_COMMIT_MESSAGE =~ /\[ci-crawler\]/'
+    - when: manual
+      allow_failure: true
+  cache:
+    key:
+      files:
+        - pyproject.toml
+    paths:
+      - .venv/
+      - .pip-cache/
+  before_script:
+    - test -d .venv || python3 -m venv .venv
+    - .venv/bin/pip install --upgrade pip wheel
+    - .venv/bin/pip install -e '.[dev,crawler]'
+  script:
+    - make test-crawler
+  artifacts:
+    when: on_failure
+    paths:
+      - .pytest_cache/
+    expire_in: 1 week