Add TestGroups reusable workflow with auto-discovery

[lkdvos]

What this adds

Running a large Julia test suite as a single job is slow: everything runs sequentially and a failure in one area blocks everything else. The standard fix is to split tests into groups and run them in parallel on separate runners — but this has historically required each package to manually maintain its own CI matrix, updating it every time a new test group is added or removed.

This PR introduces TestGroups.yml, a shared reusable workflow for all QuantumKitHub packages that handles this automatically. Add a subfolder under test/, and it gets picked up and run on its own runner — no CI configuration changes needed.

What it does

When a package's CI triggers the workflow, three things happen in sequence:

1. Discover — the workflow checks out the package and scans the test/ directory for subfolders. Each subfolder (except excluded ones like setup/ and gpu/) becomes a test group.

2. Run in parallel — one CI job is launched per combination of (test group × Julia version × operating system). With the defaults, that's core (min, ubuntu), core (1, ubuntu), core (min, macos), … all running simultaneously. The test suite inside each job receives the group name as an argument, and ParallelTestRunner.jl routes it to the right files.

3. Report a single result — a final ci-success job collects the outcome of every parallel job and reports a single, stable check. This is the only check you need to configure in branch protection rules, regardless of how many test groups exist.

There is also a fast path for draft PRs: the matrix collapses to a single OS and Julia version, and --fast is forwarded to the test suite so individual tests can skip expensive work during development.

How to adopt this in a package

Step 1 — Organise test/ into subfolders

test/
├── setup/            ← shared utilities loaded by other groups (excluded from CI)
│   └── setup.jl
├── core/
│   └── runtests.jl
├── linalg/
│   └── runtests.jl
└── runtests.jl       ← entry point, delegates via ParallelTestRunner.jl

Each subfolder is independent and runs on its own runner. The setup/ folder is excluded by default.

Step 2 — Wire up runtests.jl with ParallelTestRunner.jl

# test/runtests.jl
using ParallelTestRunner
ParallelTestRunner.runtests()

ParallelTestRunner reads the group name passed by the workflow and includes the matching subfolder's runtests.jl.

Step 3 — Add a workflow file to the package

Create .github/workflows/Tests.yml (or update the existing one):

name: Tests

on:
  push:
    branches: [main]
    tags: '*'
  pull_request:
  workflow_dispatch:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}

jobs:
  tests:
    uses: "QuantumKitHub/QuantumKitHubActions/.github/workflows/TestGroups.yml@main"
    with:
      fast: ${{ github.event.pull_request.draft == true }}
    secrets:
      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

That's it. No matrix to maintain. Adding a new test group means creating a new subfolder — the workflow picks it up automatically.

Step 4 — Set up branch protection (optional but recommended)

In the repository settings under Branch protection rules, add ci-success as a required status check on main. This single check name stays stable no matter how many test groups are added, renamed, or removed.

Available options

All options have sensible defaults — most packages won't need to set any of them.

Option	Default	What it does
exclude	["setup", "gpu"]	Subfolders to skip during discovery
julia-version	["min", "1"]	Julia versions to test against
os	all three major platforms	Operating systems to test on
fast	false	Draft PR mode: single OS/version + --fast flag
nthreads	2	Julia threads per job
timeout-minutes	60	Per-job time limit
coverage	true	Upload coverage to Codecov (Linux + julia 1 only)
localregistry	—	Private registry URLs, if needed

🤖 Generated with Claude Code

[kshyatt]

Is there a way to actively exclude some directories from (GitHub) CI, such as GPU tests?

[lkdvos]

yes, it is the exclude: option described above (which defaults to ["setup", "gpu"] I think)