add CI tests as GitHub actions

Author: jbloom

.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+# Run lint, format-check, and tests on every push to main and on every PR.
+#
+# Local equivalent: `scripts/check.sh` (which expects a local .venv;
+# this workflow uses the runner's python directly so it doesn't depend
+# on that layout).
+
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+# Force JavaScript-based actions to use Node 24 — same reason as
+# docs.yml: GitHub deprecated Node 20 actions in late 2025 and removes
+# Node 20 from runners on 2026-09-16.
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
+permissions:
+  contents: read
+
+# Cancel in-flight runs on the same ref when a new commit lands; PRs
+# rebased many times in quick succession don't queue up wasted minutes.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install package + dev extras
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Fetch upstream Kikawa Auspice JSONs
+        # Real-data tests in tests/test_real_data.py and tests/test_cli.py
+        # skip cleanly when these files are absent. We want them to
+        # actually run in CI, so fetch the upstream JSONs first.
+        run: python examples/fetch_auspice_data.py
+
+      - name: Build Kikawa titer chart specs
+        # tests/test_real_data.py also reads the saved Vega-Lite specs
+        # produced by this script. Ditto for tests/test_cli.py end-to-end.
+        run: python examples/flu-seqneut-2025to2026_titer_charts.py
+
+      - name: Lint (ruff)
+        run: ruff check .
+
+      - name: Format check (black)
+        run: black --check .
+
+      - name: Tests (pytest)
+        run: pytest tests/

.github/workflows/docs.yml

@@ -1,4 +1,8 @@
-# Build the docs on every push to `main` and deploy to GitHub Pages.
+# Build the docs on every push to `main` (then deploy to GitHub Pages)
+# and on every pull request targeting `main` (build only, no deploy).
+# The PR build catches broken mkdocstrings refs, missing images, and
+# unresolved cross-links *before* they land on `main` and break the
+# next deploy.
 #
 # Local equivalent: `scripts/build_docs.sh` (mkdocs build --strict).
 # This workflow file is dormant until the repo is published with Pages
@@ -10,6 +14,8 @@ name: docs
 on:
   push:
     branches: [main]
+  pull_request:
+    branches: [main]
   workflow_dispatch:
 
 # Opt every JavaScript-based action in this workflow into Node.js 24.
@@ -57,6 +63,11 @@ jobs:
           path: ./site
 
   deploy:
+    # Only deploy on push-to-main. PRs (especially from forks) lack
+    # `pages: write` permissions and would publish PR-only content to
+    # the live site if they did. The build job above still runs on PRs
+    # — that's where docs regressions get caught pre-merge.
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     needs: build
     runs-on: ubuntu-latest
     environment:

CLAUDE.md

@@ -56,6 +56,10 @@
   ```bash
   scripts/check.sh
   ```
+  The same three checks run in CI via
+  [`.github/workflows/ci.yml`](.github/workflows/ci.yml) on push to
+  `main` and on PRs (CI also fetches the upstream Kikawa Auspice JSONs
+  so real-data tests run rather than skip). Local green ≈ CI green.
 - **Build docs alongside checks** when changing public API surface:
   ```bash
   scripts/build_docs.sh

README.md

@@ -59,6 +59,23 @@ Then open `site/examples.html` in a browser and, for each example:
 If something visibly regresses, fix it before pushing — there's no
 CI gate that will catch a visual regression for you.
 
+### Continuous integration
+
+[`.github/workflows/ci.yml`](.github/workflows/ci.yml) runs on every
+push to `main` and every pull request: it installs the package, fetches
+the upstream Kikawa Auspice JSONs (so the real-data tests actually
+exercise rather than skip), builds the Kikawa titer chart specs, and
+runs `ruff check`, `black --check`, and `pytest tests/`. This mirrors
+[`scripts/check.sh`](scripts/check.sh) — green locally should mean
+green in CI.
+
+A separate workflow,
+[`.github/workflows/docs.yml`](.github/workflows/docs.yml), builds the
+docs site on every push to `main` and every PR (catching broken
+mkdocstrings refs / missing images / unresolved cross-links before
+merge), and additionally deploys `site/` to GitHub Pages on push to
+`main`.
+
 ### Documentation
 The docs are at
 [https://jbloomlab.github.io/tree-annotated-plot/](https://jbloomlab.github.io/tree-annotated-plot/).