From 5ac22543a7de2b0489961a9c465f1fe7e7ba3aa9 Mon Sep 17 00:00:00 2001 From: Eric Larson Date: Tue, 13 Oct 2026 10:20:54 -0400 Subject: [PATCH 1/8] MAINT: Reduce CI usage on staging --- .github/workflows/_reusable-build.yml | 4 +- .github/workflows/_reusable-tests.yml | 66 ++++++++- .github/workflows/codeql.yml | 61 +------- .github/workflows/staging.yml | 140 ++++++++++++++++-- doc/website/docs/development/ci-ghactions.mdx | 14 +- .../docs/development/ci-releasecycle.mdx | 8 +- doc/website/docs/development/ci.mdx | 5 +- 7 files changed, 216 insertions(+), 82 deletions(-) diff --git a/.github/workflows/_reusable-build.yml b/.github/workflows/_reusable-build.yml index afa1edcd0cd..a1ff991619d 100644 --- a/.github/workflows/_reusable-build.yml +++ b/.github/workflows/_reusable-build.yml @@ -117,7 +117,7 @@ jobs: if: matrix.os == 'ubuntu-24.04' || matrix.os == 'macos-26' run: | cmake -B build -S . -DCMAKE_BUILD_TYPE=Release -DUSE_ONNXRUNTIME=ON -DMNE_WARNINGS_AS_ERRORS=ON - cmake --build build + cmake --build build --parallel "$(nproc 2>/dev/null || sysctl -n hw.logicalcpu)" - name: Configure and compile MNE-CPP (Windows) if: matrix.os == 'windows-2025-vs2026' @@ -128,7 +128,7 @@ jobs: cmd.exe /c "call `"$vcvarsPath`" && set > %temp%\vcvars.txt" Get-Content "$env:temp\vcvars.txt" | Foreach-Object { if ($_ -match "^(.*?)=(.*)$") { Set-Content "env:\$($matches[1])" $matches[2] } } cmake -B build -S . -DCMAKE_BUILD_TYPE=Release -DUSE_ONNXRUNTIME=ON -DMNE_WARNINGS_AS_ERRORS=ON - cmake --build build --config Release + cmake --build build --config Release --parallel - name: Deploy binaries run: | diff --git a/.github/workflows/_reusable-tests.yml b/.github/workflows/_reusable-tests.yml index ea449cd1a56..ea0ffbb4dc2 100644 --- a/.github/workflows/_reusable-tests.yml +++ b/.github/workflows/_reusable-tests.yml @@ -31,6 +31,16 @@ on: required: false default: false type: boolean + os_json: + description: "JSON list of runner OSes to test on" + required: false + default: '["ubuntu-24.04", "macos-26", "windows-2025-vs2026"]' + type: string + save_ccache: + description: "Save the ccache and prune older entries (needs actions: write)" + required: false + default: false + type: boolean secrets: CODECOV_TOKEN: required: false @@ -46,7 +56,7 @@ jobs: fail-fast: false max-parallel: 3 matrix: - os: [ubuntu-24.04, macos-26, windows-2025-vs2026] + os: ${{ fromJSON(inputs.os_json) }} steps: - name: Clone repository @@ -164,6 +174,38 @@ jobs: run: | python -c "import mne; mne.datasets.sample.data_path()" + # ── Compiler cache (Linux|MacOS) ─────────────────────────────────────── + # One entry per OS/Qt/coverage configuration, capped by CCACHE_MAXSIZE. + # Only callers that pass save_ccache write it, and then delete the entries + # they supersede, so the total stays at a few hundred MB per configuration + # instead of growing with every run and evicting the other Actions caches. + - name: Set up ccache (Linux|MacOS) + if: runner.os != 'Windows' + shell: bash + run: | + if [ "$RUNNER_OS" = "Linux" ]; then + sudo apt-get install -q ccache + else + brew install ccache + fi + { + echo "CCACHE_DIR=$RUNNER_TEMP/ccache" + echo "CCACHE_BASEDIR=$GITHUB_WORKSPACE" + echo "CCACHE_COMPILERCHECK=content" + echo "CCACHE_MAXSIZE=400M" + echo "CMAKE_C_COMPILER_LAUNCHER=ccache" + echo "CMAKE_CXX_COMPILER_LAUNCHER=ccache" + echo "CCACHE_KEY_PREFIX=ccache-v1-${{ matrix.os }}-qt${{ inputs.qt_version }}-cov${{ inputs.with_code_coverage }}-" + } >> "$GITHUB_ENV" + + - name: Restore ccache (Linux|MacOS) + if: runner.os != 'Windows' + uses: actions/cache/restore@v5 + with: + path: ${{ runner.temp }}/ccache + key: ${{ env.CCACHE_KEY_PREFIX }}${{ github.run_id }} + restore-keys: ${{ env.CCACHE_KEY_PREFIX }} + # ── Build ────────────────────────────────────────────────────────────── # MNE_WARNINGS_AS_ERRORS enforces release gate G5 for the test build too, so # test sources cannot become the loophole through which warnings return. @@ -211,6 +253,28 @@ jobs: cmake -B build -S . -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON -DMNE_WARNINGS_AS_ERRORS=ON cmake --build build --config Release --parallel + - name: Save ccache (Linux|MacOS) + if: runner.os != 'Windows' && inputs.save_ccache + uses: actions/cache/save@v5 + with: + path: ${{ runner.temp }}/ccache + key: ${{ env.CCACHE_KEY_PREFIX }}${{ github.run_id }} + + - name: Prune superseded ccache entries (Linux|MacOS) + if: runner.os != 'Windows' && inputs.save_ccache + shell: bash + env: + GH_TOKEN: ${{ github.token }} + GH_REPO: ${{ github.repository }} + run: | + ccache --show-stats || true + current="${CCACHE_KEY_PREFIX}${{ github.run_id }}" + gh cache list --key "$CCACHE_KEY_PREFIX" --ref "$GITHUB_REF" --limit 100 --json id,key \ + --jq ".[] | select(.key != \"$current\") | .id" | + while read -r id; do + gh cache delete "$id" || true + done + # ── Run tests ────────────────────────────────────────────────────────── # CTest drives the run from the add_test() registrations rather than from a # glob over the binary output directory. A test that is built but written diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 9402b9df0a2..b2bbf41711f 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -5,13 +5,16 @@ name: "CodeQL" +# Not run on pushes to staging: the shared mne-tools runner pool cannot absorb +# an analysis per push, and the weekly schedule covers staging. on: push: - branches: [ "main", "staging" ] + branches: [ "main" ] pull_request: branches: [ "main" ] schedule: - cron: '28 15 * * 1' + workflow_dispatch: concurrency: group: codeql-${{ github.ref }} @@ -38,57 +41,13 @@ jobs: - name: Checkout repository uses: actions/checkout@v5 - - name: Install Python 3.10 - uses: actions/setup-python@v6 - with: - python-version: '3.10' - - - name: Install OpenGL development libraries - run: | - sudo rm -f /etc/apt/sources.list.d/microsoft-*.list /etc/apt/sources.list.d/azure-*.list /etc/apt/sources.list.d/microsoft-*.sources /etc/apt/sources.list.d/azure-*.sources - sudo apt-get update -q - # libxkbcommon-dev: the dynamic Qt toolchain is built with -xcb, so - # Qt6::GuiPrivate now declares a third-party dependency on XKB::XKB. - # find_package(Qt6 COMPONENTS GuiPrivate) and linking require xkbcommon. - sudo apt-get install -q libgl1-mesa-dev libxkbcommon-dev - - - name: Load external dependency versions - shell: bash - run: ./scripts/ci/load_external_deps.sh - - - name: Download Qt toolchain - env: - GH_TOKEN: ${{ secrets.GH_PAT || secrets.GITHUB_TOKEN }} - run: | - ./scripts/ci/download_toolchain.sh \ - --kind qt \ - --version "$QT_VERSION" \ - --linkage dynamic \ - --output-dir "$RUNNER_TEMP/qt" - - - name: Download Eigen package - env: - GH_TOKEN: ${{ secrets.GH_PAT || secrets.GITHUB_TOKEN }} - run: | - ./scripts/ci/download_toolchain.sh \ - --kind eigen \ - --version "$EIGEN_VERSION" \ - --output-dir "$GITHUB_WORKSPACE/src/external/eigen" - - - name: Clone Skigen - run: ./scripts/ci/clone_skigen.sh - - # Initialize CodeQL tools for scanning. + # build-mode none extracts the C/C++ sources without compiling them, so no + # Qt/Eigen toolchain or full build (~4 h on one runner) is needed. - name: Initialize CodeQL uses: github/codeql-action/init@v4 with: languages: ${{ matrix.language }} - # Disable CodeQL TRAP caching: each cache entry is ~3.7 GB and two of - # them (~7.4 GB) dominate the repo's 10 GB Actions cache budget, evicting - # the Qt/sample-data caches via LRU and forcing unnecessary re-downloads. - # The build is a full from-scratch compile every run, so TRAP caching - # only speeds extraction marginally and is not worth the footprint. - trap-caching: false + build-mode: none # If you wish to specify custom queries, you can do so here or in a config file. # By default, queries listed here will override any specified in a config file. # Prefix the list here with "+" to use these queries and those in the config file. @@ -96,12 +55,6 @@ jobs: # Details on CodeQL's query packs refer to : https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs # queries: security-extended,security-and-quality - # Build MNE-CPP - - name: Configure and compile MNE-CPP - run: | - cmake -B build -S . -DCMAKE_BUILD_TYPE=Release - cmake --build build - - name: Perform CodeQL Analysis uses: github/codeql-action/analyze@v4 with: diff --git a/.github/workflows/staging.yml b/.github/workflows/staging.yml index 0541cdb9d8a..ee5d031bf6a 100644 --- a/.github/workflows/staging.yml +++ b/.github/workflows/staging.yml @@ -6,7 +6,11 @@ # Staging Branch Pipeline # ═══════════════════════════════════════════════════════════════════════════ # -# Triggered on pushes to `staging`. +# Pushes to `staging` run only the quality gates and tests. Everything else +# runs nightly (only when `staging` moved since the last nightly) or on manual +# dispatch, and only once staging compiles. The mne-tools runner pool is shared +# by the whole organization, so a full pipeline per push starves other repos. +# A failing nightly opens an issue, which closes when a nightly passes again. # # This is the DEVELOPMENT pipeline: # • Creates/updates a rolling "dev_build" pre-release on GitHub @@ -31,11 +35,14 @@ on: push: branches: - staging + schedule: + - cron: '37 4 * * *' + workflow_dispatch: -# Cancel superseded runs +# Cancel superseded push runs; a push never cancels a nightly or manual run. concurrency: - group: staging-${{ github.ref }} - cancel-in-progress: true + group: staging-${{ github.event_name }}-${{ github.ref }} + cancel-in-progress: ${{ github.event_name == 'push' }} permissions: contents: write @@ -48,11 +55,69 @@ env: jobs: + # ── Decide whether this run publishes dev builds ───────────────────────── + # Manual runs always do, pushes never do, and a nightly does only when + # staging moved since the previous nightly (a failed nightly is not retried + # on the same commit; its issue stays open until a later nightly passes). + Changes: + runs-on: ubuntu-24.04 + permissions: + actions: read + outputs: + release: ${{ steps.check.outputs.release }} + + steps: + - name: Check for new commits since the last nightly + id: check + env: + GH_TOKEN: ${{ github.token }} + GH_REPO: ${{ github.repository }} + run: | + case "${{ github.event_name }}" in + workflow_dispatch) release=true ;; + schedule) + last_sha=$(gh api "repos/$GH_REPO/actions/workflows/staging.yml/runs?event=schedule&branch=${{ github.ref_name }}&status=completed&per_page=1" \ + --jq '.workflow_runs[0].head_sha // ""') + if [ "$last_sha" = "${{ github.sha }}" ]; then + echo "No new commits since the last nightly ($last_sha)" + release=false + else + release=true + fi + ;; + *) release=false ;; + esac + echo "release=$release" >> "$GITHUB_OUTPUT" + # ── Create / update dev_build pre-release ──────────────────────────────── + # Gated on staging compiling on every test configuration, so a broken build + # never replaces the last good dev_build. Failing tests do not block it; they + # fail the run and open the nightly failure issue instead. CreateDevRelease: runs-on: ubuntu-24.04 + needs: [Changes, Tests, TestsMinQt] + if: ${{ !cancelled() && needs.Changes.outputs.release == 'true' }} + permissions: + contents: write + actions: read steps: + - name: Check that every test configuration compiled + env: + GH_TOKEN: ${{ github.token }} + GH_REPO: ${{ github.repository }} + run: | + gh api --paginate "repos/$GH_REPO/actions/runs/${{ github.run_id }}/attempts/${{ github.run_attempt }}/jobs?per_page=100" \ + --jq '.jobs[] | select(.name | test("^Tests(MinQt)? / ")) | + [.name, ([.steps[] | select(.name | startswith("Configure and compile MNE-CPP")) | select(.conclusion != "skipped") | .conclusion] | first // "missing")] | @tsv' \ + > compiled.tsv + cat compiled.tsv + test -s compiled.tsv + if awk -F'\t' '$2 != "success" { bad = 1 } END { exit !bad }' compiled.tsv; then + echo "::error::Not every test configuration compiled, so dev_build is left unchanged." + exit 1 + fi + - name: Clone repository uses: actions/checkout@v5 @@ -88,57 +153,65 @@ jobs: # ── Platform release builds (parallel) ─────────────────────────────────── Linux: needs: CreateDevRelease + if: ${{ !cancelled() && needs.CreateDevRelease.result == 'success' }} uses: ./.github/workflows/release-linux.yml secrets: inherit MacOS: needs: CreateDevRelease + if: ${{ !cancelled() && needs.CreateDevRelease.result == 'success' }} uses: ./.github/workflows/release-macos.yml secrets: inherit Windows: needs: CreateDevRelease + if: ${{ !cancelled() && needs.CreateDevRelease.result == 'success' }} uses: ./.github/workflows/release-windows.yml secrets: inherit # ── Installers (after all platform builds) ───────────────────────────── Installer: needs: [Linux, MacOS, Windows] + if: ${{ !cancelled() && needs.Linux.result == 'success' && needs.MacOS.result == 'success' && needs.Windows.result == 'success' }} uses: ./.github/workflows/release-installer.yml secrets: inherit - # ── Build compatibility matrix (min + max Qt) ─────────────────────────── - BuildMinQt: - uses: ./.github/workflows/_reusable-build.yml - with: - qt_version: min - - BuildMaxQt: - uses: ./.github/workflows/_reusable-build.yml - with: - qt_version: max + # No separate min/max Qt build-only jobs here: Tests and TestsMinQt compile + # the same tree with the same warnings-as-errors flags, and the release + # builds exercise deployment. # ── Tests with coverage threshold & regression checks ──────────────────── # Coverage is only collected on Ubuntu; macOS/Windows always run without it. # Floor and regression tolerance come from tools/quality/coverage_policy.json. Tests: uses: ./.github/workflows/_reusable-tests.yml + permissions: + contents: read + actions: write # prune superseded ccache entries with: with_code_coverage: true upload_codecov: true enforce_coverage_gate: true + save_ccache: true secrets: CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} + # The min-Qt endpoint is a compatibility check, so Linux is enough. TestsMinQt: uses: ./.github/workflows/_reusable-tests.yml + permissions: + contents: read + actions: write # prune superseded ccache entries with: qt_version: min + os_json: '["ubuntu-24.04"]' + save_ccache: true # ── Doxygen API documentation (dev) ────────────────────────────────────── Doxygen: runs-on: ubuntu-24.04 needs: CreateDevRelease + if: ${{ !cancelled() && needs.CreateDevRelease.result == 'success' }} steps: - name: Clone repository @@ -243,6 +316,8 @@ jobs: # ── Documentation gate (T4.4): API docs, screenshots, site build ──────── Docs: + needs: CreateDevRelease + if: ${{ !cancelled() && needs.CreateDevRelease.result == 'success' }} uses: ./.github/workflows/_reusable-docs.yml with: channel: dev @@ -252,6 +327,7 @@ jobs: Website: runs-on: ubuntu-24.04 needs: [CreateDevRelease, Quality, Docs] + if: ${{ !cancelled() && needs.CreateDevRelease.result == 'success' && needs.Quality.result == 'success' && needs.Docs.result == 'success' }} steps: - name: Clone repository @@ -298,6 +374,7 @@ jobs: WebAssembly: runs-on: ubuntu-24.04 needs: CreateDevRelease + if: ${{ !cancelled() && needs.CreateDevRelease.result == 'success' }} steps: - name: Clone repository @@ -432,7 +509,42 @@ jobs: # ── Checksums and signing evidence (after every asset upload) ───────── ReleaseEvidence: needs: [Installer, Doxygen, WebAssembly] + if: ${{ !cancelled() && needs.Installer.result == 'success' && needs.Doxygen.result == 'success' && needs.WebAssembly.result == 'success' }} uses: ./.github/workflows/_reusable-release-evidence.yml with: tag: dev_build secrets: inherit + + # ── Nightly failure issue ──────────────────────────────────────────────── + # Opens (or comments on) one tracking issue when a nightly fails, and closes + # it when a later nightly passes. + NightlyStatus: + runs-on: ubuntu-24.04 + needs: [Changes, Quality, Tests, TestsMinQt, CreateDevRelease, Linux, MacOS, Windows, Installer, Doxygen, Docs, Website, WebAssembly, ReleaseEvidence] + if: always() && github.event_name == 'schedule' && needs.Changes.outputs.release == 'true' + permissions: + issues: write + + steps: + - name: Open, update or close the nightly failure issue + env: + GH_TOKEN: ${{ github.token }} + GH_REPO: ${{ github.repository }} + FAILED: ${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }} + RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} + run: | + title="Nightly staging build failed" + number=$(gh issue list --state open --search "\"$title\" in:title" --json number,title \ + --jq "map(select(.title == \"$title\")) | .[0].number // empty") + if [ "$FAILED" = "true" ]; then + body="The nightly staging pipeline failed on ${{ github.sha }}: $RUN_URL" + if [ -n "$number" ]; then + gh issue comment "$number" --body "$body" + else + gh issue create --title "$title" --body "$body + + This issue closes automatically when a nightly run passes again." + fi + elif [ -n "$number" ]; then + gh issue close "$number" --comment "The nightly staging pipeline passed again on ${{ github.sha }}: $RUN_URL" + fi diff --git a/doc/website/docs/development/ci-ghactions.mdx b/doc/website/docs/development/ci-ghactions.mdx index 27c629ac9ae..450f97e335c 100644 --- a/doc/website/docs/development/ci-ghactions.mdx +++ b/doc/website/docs/development/ci-ghactions.mdx @@ -14,7 +14,7 @@ MNE-CPP's CI is organized around the [Main – Staging – Feature branch model] | Event type | Workflow Name | Workflow Script | Effect | | ---------- | ------------- | --------------- | ------ | | Pull Requests → `staging` or `main` | `PullRequest` | [pull-request.yml](https://github.com/mne-tools/mne-cpp/blob/staging/.github/workflows/pull-request.yml) | Build matrix (Qt min + max) and tests on all platforms. PR cannot be merged until all jobs pass. | -| Pushes to `staging` | `Staging` | [staging.yml](https://github.com/mne-tools/mne-cpp/blob/staging/.github/workflows/staging.yml) | Dev release binaries, code coverage with threshold/regression checks, dev website + Doxygen deployment, CodeQL analysis. | +| Pushes to `staging`, nightly | `Staging` | [staging.yml](https://github.com/mne-tools/mne-cpp/blob/staging/.github/workflows/staging.yml) | On push: tests with code coverage threshold/regression checks and quality gates. Nightly: also dev release binaries and dev website + Doxygen deployment. | | Pushes to `main` | `Main` | [main.yml](https://github.com/mne-tools/mne-cpp/blob/main/.github/workflows/main.yml) | Builds, tests, stable website + Doxygen deployment. | | Tag `v*` on `main` | `Main` (release jobs) | [main.yml](https://github.com/mne-tools/mne-cpp/blob/main/.github/workflows/main.yml) | Full stable release: platform binaries (Linux, macOS, Windows), installers, WebAssembly, Codecov upload. | | Pushes to the `wasm` branch | `WasmTest` | [wasmtest.yml](https://github.com/mne-tools/mne-cpp/blob/main/.github/workflows/wasmtest.yml) | Creates new versions of the WebAssembly capable MNE-CPP applications and makes them accessible via the repository's `gh-pages` branch. | @@ -45,14 +45,18 @@ The PR cannot be merged until all matrix jobs pass. This ensures that every chan ## How the Staging Workflow Works -`staging.yml` is the active development pipeline, triggered on every push to `staging`. It: +`staging.yml` is the active development pipeline. GitHub-hosted runners are shared by every repository in the `mne-tools` organization, so each push to `staging` runs only: + +- The static **quality gates** +- Tests with **code coverage** on all platforms — enforcing a minimum threshold (50%) and detecting coverage regressions — plus tests against the minimum Qt version on Linux + +The full pipeline runs nightly when `staging` has changed since the last nightly, and on manual dispatch (**Actions → Staging → Run workflow**). Once every test configuration compiles (failing tests do not block it), it: - Creates or updates the **`dev_build`** pre-release on GitHub with the latest development binaries -- Builds with both minimum and maximum Qt versions -- Runs tests with **code coverage** — enforcing a minimum threshold (50%) and detecting coverage regressions - Invokes the platform-specific release workflows (`release-linux.yml`, `release-macos.yml`, `release-windows.yml`, `release-installer.yml`) to produce development binaries tagged as `dev_build` - Deploys the **dev** version of the documentation website to `/dev/` and Doxygen API docs to `/dev/` -- Runs **CodeQL** security analysis + +A failing nightly opens a "Nightly staging build failed" issue, which closes automatically when a later nightly passes. **CodeQL** security analysis runs weekly and on `main` (`codeql.yml`). ## How the Main / Release Workflow Works diff --git a/doc/website/docs/development/ci-releasecycle.mdx b/doc/website/docs/development/ci-releasecycle.mdx index 1d7f865a56b..7b7a3d2079a 100644 --- a/doc/website/docs/development/ci-releasecycle.mdx +++ b/doc/website/docs/development/ci-releasecycle.mdx @@ -45,11 +45,11 @@ The `main` branch always reflects a **production-ready** state. It is updated on The `staging` branch is the active development integration branch. Feature branches are merged here via pull requests. - Every push to `staging` triggers: - - Cross-platform builds (minimum and maximum supported Qt versions) - - Unit tests with **code coverage** — threshold checks (≥ 50%) and regression detection + - Cross-platform tests with **code coverage** — threshold checks (≥ 50%) and regression detection — plus tests against the minimum supported Qt version on Linux +- Nightly, when `staging` has changed, the pipeline also produces: - A rolling **dev pre-release** (`dev_build`) with binaries for all platforms - Deployment of the **dev** version of the website (at `/dev/`) and Doxygen API docs (at `/dev/`) - - CodeQL security analysis +- CodeQL security analysis runs weekly ### Feature Branches @@ -79,7 +79,7 @@ The website and Doxygen API docs are deployed in two versions simultaneously: | Version | URL | Updated by | |---------|-----|-----------| | **Stable** | `mne-cpp.github.io` / `mne-cpp.github.io/doxygen-api` | Pushes to `main` | -| **Dev** | `mne-cpp.github.io/dev/` / `mne-cpp.github.io/doxygen-api/dev/` | Pushes to `staging` | +| **Dev** | `mne-cpp.github.io/dev/` / `mne-cpp.github.io/doxygen-api/dev/` | Nightly builds of `staging` | Both versions are served from the same repository and branch (`gh-pages`), using subdirectory isolation — stable at the root, dev under `/dev/`. A version dropdown in the website header lets users switch between stable and dev documentation. diff --git a/doc/website/docs/development/ci.mdx b/doc/website/docs/development/ci.mdx index d4f0b22cd51..d31678920f2 100644 --- a/doc/website/docs/development/ci.mdx +++ b/doc/website/docs/development/ci.mdx @@ -7,7 +7,7 @@ sidebar_label: Continuous Integration Every change to MNE-CPP is automatically built, tested, and — for releases — packaged across **Windows, Linux, and macOS** before it reaches users. The CI system runs on [GitHub Actions](https://docs.github.com/en/actions) and is organized around the [Main – Staging – Feature branch model](ci-releasecycle.mdx). -Pull requests cannot be merged until all platform jobs pass. Development builds are published on every push to `staging`; stable release binaries are created when a version tag (`v*`) is pushed on `main`. +Pull requests cannot be merged until all platform jobs pass. Development builds are published nightly from `staging`; stable release binaries are created when a version tag (`v*`) is pushed on `main`. ## Guides @@ -21,7 +21,8 @@ Pull requests cannot be merged until all platform jobs pass. Development builds | Branch / Event | Workflow | What Happens | |----------------|----------|--------------| | Pull request → `staging` or `main` | `pull-request.yml` | Build matrix (Qt min + max) + tests on all platforms | -| Push to `staging` | `staging.yml` | Dev release binaries, coverage checks, dev website + Doxygen, CodeQL | +| Push to `staging` | `staging.yml` | Tests with coverage checks, quality gates | +| Nightly (when `staging` changed) | `staging.yml` | Tests, then dev release binaries, dev website + Doxygen | | Push to `main` | `main.yml` | Tests, stable website + Doxygen deployment | | Tag `v*` on `main` | `main.yml` | Full stable release: platform binaries, installers, WebAssembly | | Push to `wasm` | `wasmtest.yml` | WebAssembly build deployed to GitHub Pages | From 7afef4e41c6c8d0c162447797a371112c2f59b1a Mon Sep 17 00:00:00 2001 From: Eric Larson Date: Tue, 13 Oct 2026 12:02:40 -0400 Subject: [PATCH 2/8] MAINT: Drop duplicate builds from the PR pipeline The test jobs already compile the same tree with MNE_WARNINGS_AS_ERRORS, so the separate min/max Qt build jobs only repeat that work. Min-Qt tests now run on Linux only. A PR goes from 15 to 6 jobs and from 5 macOS jobs to 1, which matters because the mne-tools runner pool is shared and only 5 macOS jobs can run at once. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/pull-request.yml | 23 ++++++++----------- doc/website/docs/development/ci-ghactions.mdx | 11 ++++----- doc/website/docs/development/ci.mdx | 2 +- 3 files changed, 15 insertions(+), 21 deletions(-) diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml index aa9363ee4e9..83fbcbada96 100644 --- a/.github/workflows/pull-request.yml +++ b/.github/workflows/pull-request.yml @@ -9,9 +9,9 @@ # Triggered on pull requests targeting `staging` or `main`. # # This is the FEATURE BRANCH pipeline: -# • Verifies the project builds across all platforms -# • Tests min + max supported Qt versions -# • Runs the full test suite (without coverage — that's done on staging) +# • Runs the full test suite on all platforms with the maximum supported Qt +# (without coverage — that's done on staging) +# • Runs it with the minimum supported Qt on Linux # • No deployments, no releases # # Branch model: Feature → Staging → Main @@ -34,17 +34,10 @@ env: jobs: - # ── Build compatibility: minimum supported Qt ──────────────────────────── - BuildMinQt: - uses: ./.github/workflows/_reusable-build.yml - with: - qt_version: min - - # ── Build compatibility: maximum supported Qt ──────────────────────────── - BuildMaxQt: - uses: ./.github/workflows/_reusable-build.yml - with: - qt_version: max + # No separate min/max Qt build-only jobs: the test jobs compile the same tree + # with the same warnings-as-errors flags. The runner pool is shared by the + # whole mne-tools organization (and only 5 macOS jobs run at once), so + # duplicate builds delay every repository's CI. # ── Tests (no coverage collection) ────────────────────────────────────── Tests: @@ -53,10 +46,12 @@ jobs: with_code_coverage: false upload_codecov: false + # The min-Qt endpoint is a compatibility check, so Linux is enough. TestsMinQt: uses: ./.github/workflows/_reusable-tests.yml with: qt_version: min + os_json: '["ubuntu-24.04"]' # ── Quality gates (static, no build) ──────────────────────────────────── Quality: diff --git a/doc/website/docs/development/ci-ghactions.mdx b/doc/website/docs/development/ci-ghactions.mdx index 450f97e335c..8ad5f20be13 100644 --- a/doc/website/docs/development/ci-ghactions.mdx +++ b/doc/website/docs/development/ci-ghactions.mdx @@ -13,7 +13,7 @@ MNE-CPP's CI is organized around the [Main – Staging – Feature branch model] | Event type | Workflow Name | Workflow Script | Effect | | ---------- | ------------- | --------------- | ------ | -| Pull Requests → `staging` or `main` | `PullRequest` | [pull-request.yml](https://github.com/mne-tools/mne-cpp/blob/staging/.github/workflows/pull-request.yml) | Build matrix (Qt min + max) and tests on all platforms. PR cannot be merged until all jobs pass. | +| Pull Requests → `staging` or `main` | `PullRequest` | [pull-request.yml](https://github.com/mne-tools/mne-cpp/blob/staging/.github/workflows/pull-request.yml) | Build and tests on all platforms (maximum Qt), plus minimum Qt on Linux. PR cannot be merged until all jobs pass. | | Pushes to `staging`, nightly | `Staging` | [staging.yml](https://github.com/mne-tools/mne-cpp/blob/staging/.github/workflows/staging.yml) | On push: tests with code coverage threshold/regression checks and quality gates. Nightly: also dev release binaries and dev website + Doxygen deployment. | | Pushes to `main` | `Main` | [main.yml](https://github.com/mne-tools/mne-cpp/blob/main/.github/workflows/main.yml) | Builds, tests, stable website + Doxygen deployment. | | Tag `v*` on `main` | `Main` (release jobs) | [main.yml](https://github.com/mne-tools/mne-cpp/blob/main/.github/workflows/main.yml) | Full stable release: platform binaries (Linux, macOS, Windows), installers, WebAssembly, Codecov upload. | @@ -34,12 +34,11 @@ These are called by the main pipeline workflows using `workflow_call`. ## How the Pull Request Workflow Works -When a contributor opens or updates a pull request targeting `staging` (or `main`), `pull-request.yml` runs a build-and-test matrix: +When a contributor opens or updates a pull request targeting `staging` (or `main`), `pull-request.yml` runs: -1. **Checks out** the PR branch. -2. **Builds** twice — once with the **minimum** supported Qt version and once with the **maximum** — to ensure compatibility across the supported Qt range. -3. **Runs tests** via the reusable test workflow (without coverage uploads). -4. **Builds Doxygen** documentation to verify it compiles without errors. +1. The static **quality gates**. +2. **Builds and tests** with the **maximum** supported Qt version on Linux, macOS, and Windows, and with the **minimum** supported Qt version on Linux, via the reusable test workflow (without coverage uploads). +3. **Builds the documentation** to verify it compiles without errors. The PR cannot be merged until all matrix jobs pass. This ensures that every change is validated on Linux, macOS, and Windows before it reaches the `staging` branch. diff --git a/doc/website/docs/development/ci.mdx b/doc/website/docs/development/ci.mdx index d31678920f2..e0a4db08ef4 100644 --- a/doc/website/docs/development/ci.mdx +++ b/doc/website/docs/development/ci.mdx @@ -20,7 +20,7 @@ Pull requests cannot be merged until all platform jobs pass. Development builds | Branch / Event | Workflow | What Happens | |----------------|----------|--------------| -| Pull request → `staging` or `main` | `pull-request.yml` | Build matrix (Qt min + max) + tests on all platforms | +| Pull request → `staging` or `main` | `pull-request.yml` | Build + tests on all platforms (max Qt), min Qt on Linux | | Push to `staging` | `staging.yml` | Tests with coverage checks, quality gates | | Nightly (when `staging` changed) | `staging.yml` | Tests, then dev release binaries, dev website + Doxygen | | Push to `main` | `main.yml` | Tests, stable website + Doxygen deployment | From 43d3bb9e9ec3f445bf61c491bf73853b234660f6 Mon Sep 17 00:00:00 2001 From: Eric Larson Date: Tue, 13 Oct 2026 12:13:50 -0400 Subject: [PATCH 3/8] MAINT: Run the staging nightly when the shared runners are idle Over the last four weeks the mne-tools runner pool was quietest from about 01:00 to 04:00 UTC, while MNE-Python traffic picks up from 04:00-05:00 UTC and staging pushes usually start around 07:00 UTC. Starting at 01:13 UTC puts the release-build burst after the tests (~1.5 h) inside that window. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/staging.yml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/.github/workflows/staging.yml b/.github/workflows/staging.yml index ee5d031bf6a..ea185b890ec 100644 --- a/.github/workflows/staging.yml +++ b/.github/workflows/staging.yml @@ -36,7 +36,11 @@ on: branches: - staging schedule: - - cron: '37 4 * * *' + # 01:13 UTC: over Sep–Oct 2026 the mne-tools runner pool was quietest from + # about 01:00 to 04:00 UTC (MNE-Python, MNE-BIDS and MNE-BIDS-Pipeline CI + # all near idle), and staging pushes usually start around 07:00 UTC. The + # tests take ~1.5 h, so the release-build burst lands around 02:45–04:15. + - cron: '13 1 * * *' workflow_dispatch: # Cancel superseded push runs; a push never cancels a nightly or manual run. From 61b3a3208cb6c503415e5d4632890d1a615dff1e Mon Sep 17 00:00:00 2001 From: Eric Larson Date: Tue, 13 Oct 2026 14:17:26 -0400 Subject: [PATCH 4/8] MAINT: Share the macOS ccache between staging and PRs Coverage is only collected on Linux, but the cache key included the with_code_coverage input on every OS. Staging (coverage on) and PRs (coverage off) therefore saved and looked up different macOS keys for identical builds, so PRs could never hit the macOS cache. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/_reusable-tests.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/_reusable-tests.yml b/.github/workflows/_reusable-tests.yml index ea0ffbb4dc2..8c3bc4bf8bd 100644 --- a/.github/workflows/_reusable-tests.yml +++ b/.github/workflows/_reusable-tests.yml @@ -195,7 +195,8 @@ jobs: echo "CCACHE_MAXSIZE=400M" echo "CMAKE_C_COMPILER_LAUNCHER=ccache" echo "CMAKE_CXX_COMPILER_LAUNCHER=ccache" - echo "CCACHE_KEY_PREFIX=ccache-v1-${{ matrix.os }}-qt${{ inputs.qt_version }}-cov${{ inputs.with_code_coverage }}-" + # Coverage only changes the compile on Linux, so macOS shares one key. + echo "CCACHE_KEY_PREFIX=ccache-v1-${{ matrix.os }}-qt${{ inputs.qt_version }}-cov${{ runner.os == 'Linux' && inputs.with_code_coverage }}-" } >> "$GITHUB_ENV" - name: Restore ccache (Linux|MacOS) From b6c8ac4e4e41da056049fd3397e350a61f0de9ad Mon Sep 17 00:00:00 2001 From: Christoph Dinh Date: Wed, 14 Oct 2026 22:45:07 +0200 Subject: [PATCH 5/8] MAINT: Keep the quality coverage while reducing CI usage The runner savings stay; the parts that dropped checks come back where they are cheap or rare: - Staging nightly and manual runs test min Qt on all three OSes again, so every published dev build and the release gate evidence cover each OS x Qt pair. Pushes keep min Qt on Linux only. - The docs gate (API docs, screenshots, site build; Linux, ~20 min) runs on every push again; only the website deployment waits for the nightly. - PRs into main (releases) test min Qt on all three OSes. - CodeQL keeps the reduced triggers but analyses a real build again, now compiled in parallel, so Qt-generated code and template instantiations are covered (build-mode none skips them). --- .github/workflows/codeql.yml | 60 +++++++++++++++++-- .github/workflows/pull-request.yml | 4 +- .github/workflows/staging.yml | 9 +-- doc/website/docs/development/ci-ghactions.mdx | 9 +-- doc/website/docs/development/ci.mdx | 2 +- 5 files changed, 69 insertions(+), 15 deletions(-) diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index b2bbf41711f..d0af8762805 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -6,7 +6,8 @@ name: "CodeQL" # Not run on pushes to staging: the shared mne-tools runner pool cannot absorb -# an analysis per push, and the weekly schedule covers staging. +# an analysis per push, and the weekly schedule covers staging. The analysis +# keeps a real build so moc/uic output and template instantiations are seen. on: push: branches: [ "main" ] @@ -41,13 +42,58 @@ jobs: - name: Checkout repository uses: actions/checkout@v5 - # build-mode none extracts the C/C++ sources without compiling them, so no - # Qt/Eigen toolchain or full build (~4 h on one runner) is needed. + - name: Install Python 3.10 + uses: actions/setup-python@v6 + with: + python-version: '3.10' + + - name: Install OpenGL development libraries + run: | + sudo rm -f /etc/apt/sources.list.d/microsoft-*.list /etc/apt/sources.list.d/azure-*.list /etc/apt/sources.list.d/microsoft-*.sources /etc/apt/sources.list.d/azure-*.sources + sudo apt-get update -q + # libxkbcommon-dev: the dynamic Qt toolchain is built with -xcb, so + # Qt6::GuiPrivate now declares a third-party dependency on XKB::XKB. + # find_package(Qt6 COMPONENTS GuiPrivate) and linking require xkbcommon. + sudo apt-get install -q libgl1-mesa-dev libxkbcommon-dev + + - name: Load external dependency versions + shell: bash + run: ./scripts/ci/load_external_deps.sh + + - name: Download Qt toolchain + env: + GH_TOKEN: ${{ secrets.GH_PAT || secrets.GITHUB_TOKEN }} + run: | + ./scripts/ci/download_toolchain.sh \ + --kind qt \ + --version "$QT_VERSION" \ + --linkage dynamic \ + --output-dir "$RUNNER_TEMP/qt" + + - name: Download Eigen package + env: + GH_TOKEN: ${{ secrets.GH_PAT || secrets.GITHUB_TOKEN }} + run: | + ./scripts/ci/download_toolchain.sh \ + --kind eigen \ + --version "$EIGEN_VERSION" \ + --output-dir "$GITHUB_WORKSPACE/src/external/eigen" + + - name: Clone Skigen + run: ./scripts/ci/clone_skigen.sh + + # Initialize CodeQL tools for scanning. - name: Initialize CodeQL uses: github/codeql-action/init@v4 with: languages: ${{ matrix.language }} - build-mode: none + build-mode: manual + # Disable CodeQL TRAP caching: each cache entry is ~3.7 GB and two of + # them (~7.4 GB) dominate the repo's 10 GB Actions cache budget, evicting + # the Qt/sample-data caches via LRU and forcing unnecessary re-downloads. + # The build is a full from-scratch compile every run, so TRAP caching + # only speeds extraction marginally and is not worth the footprint. + trap-caching: false # If you wish to specify custom queries, you can do so here or in a config file. # By default, queries listed here will override any specified in a config file. # Prefix the list here with "+" to use these queries and those in the config file. @@ -55,6 +101,12 @@ jobs: # Details on CodeQL's query packs refer to : https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs # queries: security-extended,security-and-quality + # Build MNE-CPP + - name: Configure and compile MNE-CPP + run: | + cmake -B build -S . -DCMAKE_BUILD_TYPE=Release + cmake --build build --parallel "$(nproc)" + - name: Perform CodeQL Analysis uses: github/codeql-action/analyze@v4 with: diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml index 83fbcbada96..a7ccb0e6061 100644 --- a/.github/workflows/pull-request.yml +++ b/.github/workflows/pull-request.yml @@ -46,12 +46,12 @@ jobs: with_code_coverage: false upload_codecov: false - # The min-Qt endpoint is a compatibility check, so Linux is enough. + # Min-Qt on Linux; release PRs into main test it on all three OSes. TestsMinQt: uses: ./.github/workflows/_reusable-tests.yml with: qt_version: min - os_json: '["ubuntu-24.04"]' + os_json: ${{ github.base_ref == 'main' && '["ubuntu-24.04", "macos-26", "windows-2025-vs2026"]' || '["ubuntu-24.04"]' }} # ── Quality gates (static, no build) ──────────────────────────────────── Quality: diff --git a/.github/workflows/staging.yml b/.github/workflows/staging.yml index ea185b890ec..656a52fd9bd 100644 --- a/.github/workflows/staging.yml +++ b/.github/workflows/staging.yml @@ -200,7 +200,8 @@ jobs: secrets: CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} - # The min-Qt endpoint is a compatibility check, so Linux is enough. + # Min-Qt on Linux per push; on all three OSes nightly and on manual runs, so + # the published dev build and the G1 evidence still cover every OS x Qt pair. TestsMinQt: uses: ./.github/workflows/_reusable-tests.yml permissions: @@ -208,7 +209,7 @@ jobs: actions: write # prune superseded ccache entries with: qt_version: min - os_json: '["ubuntu-24.04"]' + os_json: ${{ github.event_name == 'push' && '["ubuntu-24.04"]' || '["ubuntu-24.04", "macos-26", "windows-2025-vs2026"]' }} save_ccache: true # ── Doxygen API documentation (dev) ────────────────────────────────────── @@ -319,9 +320,9 @@ jobs: retention-days: 30 # ── Documentation gate (T4.4): API docs, screenshots, site build ──────── + # Runs on every push (Linux only, ~20 min): it is the docs/API gate. Only + # the Website deployment waits for the nightly. Docs: - needs: CreateDevRelease - if: ${{ !cancelled() && needs.CreateDevRelease.result == 'success' }} uses: ./.github/workflows/_reusable-docs.yml with: channel: dev diff --git a/doc/website/docs/development/ci-ghactions.mdx b/doc/website/docs/development/ci-ghactions.mdx index 8ad5f20be13..6437797f8f9 100644 --- a/doc/website/docs/development/ci-ghactions.mdx +++ b/doc/website/docs/development/ci-ghactions.mdx @@ -13,8 +13,8 @@ MNE-CPP's CI is organized around the [Main – Staging – Feature branch model] | Event type | Workflow Name | Workflow Script | Effect | | ---------- | ------------- | --------------- | ------ | -| Pull Requests → `staging` or `main` | `PullRequest` | [pull-request.yml](https://github.com/mne-tools/mne-cpp/blob/staging/.github/workflows/pull-request.yml) | Build and tests on all platforms (maximum Qt), plus minimum Qt on Linux. PR cannot be merged until all jobs pass. | -| Pushes to `staging`, nightly | `Staging` | [staging.yml](https://github.com/mne-tools/mne-cpp/blob/staging/.github/workflows/staging.yml) | On push: tests with code coverage threshold/regression checks and quality gates. Nightly: also dev release binaries and dev website + Doxygen deployment. | +| Pull Requests → `staging` or `main` | `PullRequest` | [pull-request.yml](https://github.com/mne-tools/mne-cpp/blob/staging/.github/workflows/pull-request.yml) | Build and tests on all platforms (maximum Qt), plus minimum Qt on Linux (on all platforms for PRs into `main`). PR cannot be merged until all jobs pass. | +| Pushes to `staging`, nightly | `Staging` | [staging.yml](https://github.com/mne-tools/mne-cpp/blob/staging/.github/workflows/staging.yml) | On push: tests with code coverage threshold/regression checks, quality and documentation gates. Nightly: also minimum-Qt tests on all platforms, dev release binaries and dev website + Doxygen deployment. | | Pushes to `main` | `Main` | [main.yml](https://github.com/mne-tools/mne-cpp/blob/main/.github/workflows/main.yml) | Builds, tests, stable website + Doxygen deployment. | | Tag `v*` on `main` | `Main` (release jobs) | [main.yml](https://github.com/mne-tools/mne-cpp/blob/main/.github/workflows/main.yml) | Full stable release: platform binaries (Linux, macOS, Windows), installers, WebAssembly, Codecov upload. | | Pushes to the `wasm` branch | `WasmTest` | [wasmtest.yml](https://github.com/mne-tools/mne-cpp/blob/main/.github/workflows/wasmtest.yml) | Creates new versions of the WebAssembly capable MNE-CPP applications and makes them accessible via the repository's `gh-pages` branch. | @@ -48,14 +48,15 @@ The PR cannot be merged until all matrix jobs pass. This ensures that every chan - The static **quality gates** - Tests with **code coverage** on all platforms — enforcing a minimum threshold (50%) and detecting coverage regressions — plus tests against the minimum Qt version on Linux +- The **documentation gate** (API docs, screenshots, website build) -The full pipeline runs nightly when `staging` has changed since the last nightly, and on manual dispatch (**Actions → Staging → Run workflow**). Once every test configuration compiles (failing tests do not block it), it: +The full pipeline runs nightly when `staging` has changed since the last nightly, and on manual dispatch (**Actions → Staging → Run workflow**). It also runs the minimum-Qt tests on all three platforms. Once every test configuration compiles (failing tests do not block it), it: - Creates or updates the **`dev_build`** pre-release on GitHub with the latest development binaries - Invokes the platform-specific release workflows (`release-linux.yml`, `release-macos.yml`, `release-windows.yml`, `release-installer.yml`) to produce development binaries tagged as `dev_build` - Deploys the **dev** version of the documentation website to `/dev/` and Doxygen API docs to `/dev/` -A failing nightly opens a "Nightly staging build failed" issue, which closes automatically when a later nightly passes. **CodeQL** security analysis runs weekly and on `main` (`codeql.yml`). +A failing nightly opens a "Nightly staging build failed" issue, which closes automatically when a later nightly passes. **CodeQL** security analysis, on a full build, runs weekly, on `main` and on manual dispatch (`codeql.yml`). ## How the Main / Release Workflow Works diff --git a/doc/website/docs/development/ci.mdx b/doc/website/docs/development/ci.mdx index e0a4db08ef4..288ca52d556 100644 --- a/doc/website/docs/development/ci.mdx +++ b/doc/website/docs/development/ci.mdx @@ -22,7 +22,7 @@ Pull requests cannot be merged until all platform jobs pass. Development builds |----------------|----------|--------------| | Pull request → `staging` or `main` | `pull-request.yml` | Build + tests on all platforms (max Qt), min Qt on Linux | | Push to `staging` | `staging.yml` | Tests with coverage checks, quality gates | -| Nightly (when `staging` changed) | `staging.yml` | Tests, then dev release binaries, dev website + Doxygen | +| Nightly (when `staging` changed) | `staging.yml` | Tests (min Qt on all platforms), then dev release binaries, dev website + Doxygen | | Push to `main` | `main.yml` | Tests, stable website + Doxygen deployment | | Tag `v*` on `main` | `main.yml` | Full stable release: platform binaries, installers, WebAssembly | | Push to `wasm` | `wasmtest.yml` | WebAssembly build deployed to GitHub Pages | From 5445f298bca57e93f684bb31cfc75459f1d95c7e Mon Sep 17 00:00:00 2001 From: Christoph Dinh Date: Wed, 14 Oct 2026 23:02:29 +0200 Subject: [PATCH 6/8] MAINT: Test every OS x Qt pair per staging push; build releases when the build changes Every push runs the quality and docs gates and all six test configurations, so each failure and coverage change is reported on the commit that caused it. The release builds, installers, WebAssembly and deployments also run on pushes that change CMakeLists.txt, cmake/, scripts/{build,ci,deploy}/ or .github/workflows/ (any doubt, e.g. a force push, builds), besides nightly and manual runs. --- .github/workflows/staging.yml | 39 +++++++++++++------ doc/website/docs/development/ci-ghactions.mdx | 8 ++-- .../docs/development/ci-releasecycle.mdx | 4 +- doc/website/docs/development/ci.mdx | 6 +-- 4 files changed, 37 insertions(+), 20 deletions(-) diff --git a/.github/workflows/staging.yml b/.github/workflows/staging.yml index 656a52fd9bd..931ef769c50 100644 --- a/.github/workflows/staging.yml +++ b/.github/workflows/staging.yml @@ -6,10 +6,12 @@ # Staging Branch Pipeline # ═══════════════════════════════════════════════════════════════════════════ # -# Pushes to `staging` run only the quality gates and tests. Everything else -# runs nightly (only when `staging` moved since the last nightly) or on manual -# dispatch, and only once staging compiles. The mne-tools runner pool is shared -# by the whole organization, so a full pipeline per push starves other repos. +# Every push to `staging` runs the quality and docs gates and all tests (three +# OSes, minimum and maximum Qt). The release builds, installers, WebAssembly +# and deployments run on pushes that touch the build or packaging, nightly +# (only when `staging` moved since the last nightly) and on manual dispatch, +# and only once staging compiles. The mne-tools runner pool is shared by the +# whole organization, so they are skipped where a push cannot affect them. # A failing nightly opens an issue, which closes when a nightly passes again. # # This is the DEVELOPMENT pipeline: @@ -60,25 +62,41 @@ env: jobs: # ── Decide whether this run publishes dev builds ───────────────────────── - # Manual runs always do, pushes never do, and a nightly does only when - # staging moved since the previous nightly (a failed nightly is not retried - # on the same commit; its issue stays open until a later nightly passes). + # Manual runs always do, pushes do when they touch the build or packaging, + # and a nightly does only when staging moved since the previous nightly (a + # failed nightly is not retried on the same commit; its issue stays open + # until a later nightly passes). Changes: runs-on: ubuntu-24.04 permissions: actions: read + contents: read outputs: release: ${{ steps.check.outputs.release }} steps: - - name: Check for new commits since the last nightly + - name: Decide whether to build releases id: check env: GH_TOKEN: ${{ github.token }} GH_REPO: ${{ github.repository }} + BEFORE: ${{ github.event.before }} run: | case "${{ github.event_name }}" in workflow_dispatch) release=true ;; + push) + # Any doubt (new branch, force push, more files than the API lists) builds. + release=true + if [ -n "$BEFORE" ] && [ "$BEFORE" != "0000000000000000000000000000000000000000" ] && + files=$(gh api "repos/$GH_REPO/compare/$BEFORE...${{ github.sha }}" \ + --jq 'if (.files | length) < 300 then .files[].filename else "too-many" end'); then + if ! printf '%s\n' "$files" | + grep -qE '(^|/)CMakeLists\.txt$|^cmake/|^scripts/(build|ci|deploy)/|^\.github/workflows/|^too-many$'; then + echo "No build or packaging files changed" + release=false + fi + fi + ;; schedule) last_sha=$(gh api "repos/$GH_REPO/actions/workflows/staging.yml/runs?event=schedule&branch=${{ github.ref_name }}&status=completed&per_page=1" \ --jq '.workflow_runs[0].head_sha // ""') @@ -200,8 +218,8 @@ jobs: secrets: CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} - # Min-Qt on Linux per push; on all three OSes nightly and on manual runs, so - # the published dev build and the G1 evidence still cover every OS x Qt pair. + # Min-Qt on all three OSes, so every push and the G1 evidence cover each + # OS x Qt pair. TestsMinQt: uses: ./.github/workflows/_reusable-tests.yml permissions: @@ -209,7 +227,6 @@ jobs: actions: write # prune superseded ccache entries with: qt_version: min - os_json: ${{ github.event_name == 'push' && '["ubuntu-24.04"]' || '["ubuntu-24.04", "macos-26", "windows-2025-vs2026"]' }} save_ccache: true # ── Doxygen API documentation (dev) ────────────────────────────────────── diff --git a/doc/website/docs/development/ci-ghactions.mdx b/doc/website/docs/development/ci-ghactions.mdx index 6437797f8f9..b8075567abd 100644 --- a/doc/website/docs/development/ci-ghactions.mdx +++ b/doc/website/docs/development/ci-ghactions.mdx @@ -14,7 +14,7 @@ MNE-CPP's CI is organized around the [Main – Staging – Feature branch model] | Event type | Workflow Name | Workflow Script | Effect | | ---------- | ------------- | --------------- | ------ | | Pull Requests → `staging` or `main` | `PullRequest` | [pull-request.yml](https://github.com/mne-tools/mne-cpp/blob/staging/.github/workflows/pull-request.yml) | Build and tests on all platforms (maximum Qt), plus minimum Qt on Linux (on all platforms for PRs into `main`). PR cannot be merged until all jobs pass. | -| Pushes to `staging`, nightly | `Staging` | [staging.yml](https://github.com/mne-tools/mne-cpp/blob/staging/.github/workflows/staging.yml) | On push: tests with code coverage threshold/regression checks, quality and documentation gates. Nightly: also minimum-Qt tests on all platforms, dev release binaries and dev website + Doxygen deployment. | +| Pushes to `staging`, nightly | `Staging` | [staging.yml](https://github.com/mne-tools/mne-cpp/blob/staging/.github/workflows/staging.yml) | On push: tests with code coverage threshold/regression checks on all platforms with minimum and maximum Qt, quality and documentation gates. On pushes that touch the build or packaging, nightly and on manual dispatch: also dev release binaries and dev website + Doxygen deployment. | | Pushes to `main` | `Main` | [main.yml](https://github.com/mne-tools/mne-cpp/blob/main/.github/workflows/main.yml) | Builds, tests, stable website + Doxygen deployment. | | Tag `v*` on `main` | `Main` (release jobs) | [main.yml](https://github.com/mne-tools/mne-cpp/blob/main/.github/workflows/main.yml) | Full stable release: platform binaries (Linux, macOS, Windows), installers, WebAssembly, Codecov upload. | | Pushes to the `wasm` branch | `WasmTest` | [wasmtest.yml](https://github.com/mne-tools/mne-cpp/blob/main/.github/workflows/wasmtest.yml) | Creates new versions of the WebAssembly capable MNE-CPP applications and makes them accessible via the repository's `gh-pages` branch. | @@ -44,13 +44,13 @@ The PR cannot be merged until all matrix jobs pass. This ensures that every chan ## How the Staging Workflow Works -`staging.yml` is the active development pipeline. GitHub-hosted runners are shared by every repository in the `mne-tools` organization, so each push to `staging` runs only: +`staging.yml` is the active development pipeline. Every push to `staging` runs: - The static **quality gates** -- Tests with **code coverage** on all platforms — enforcing a minimum threshold (50%) and detecting coverage regressions — plus tests against the minimum Qt version on Linux +- Tests with **code coverage** on all platforms — enforcing a minimum threshold (50%) and detecting coverage regressions — plus tests against the minimum Qt version on all platforms - The **documentation gate** (API docs, screenshots, website build) -The full pipeline runs nightly when `staging` has changed since the last nightly, and on manual dispatch (**Actions → Staging → Run workflow**). It also runs the minimum-Qt tests on all three platforms. Once every test configuration compiles (failing tests do not block it), it: +GitHub-hosted runners are shared by every repository in the `mne-tools` organization, so the release part of the pipeline runs only where it can be affected: on pushes that change `CMakeLists.txt`, `cmake/`, `scripts/build/`, `scripts/ci/`, `scripts/deploy/` or `.github/workflows/`, nightly when `staging` has changed since the last nightly, and on manual dispatch (**Actions → Staging → Run workflow**). Once every test configuration compiles (failing tests do not block it), it: - Creates or updates the **`dev_build`** pre-release on GitHub with the latest development binaries - Invokes the platform-specific release workflows (`release-linux.yml`, `release-macos.yml`, `release-windows.yml`, `release-installer.yml`) to produce development binaries tagged as `dev_build` diff --git a/doc/website/docs/development/ci-releasecycle.mdx b/doc/website/docs/development/ci-releasecycle.mdx index 7b7a3d2079a..18b9167151f 100644 --- a/doc/website/docs/development/ci-releasecycle.mdx +++ b/doc/website/docs/development/ci-releasecycle.mdx @@ -45,8 +45,8 @@ The `main` branch always reflects a **production-ready** state. It is updated on The `staging` branch is the active development integration branch. Feature branches are merged here via pull requests. - Every push to `staging` triggers: - - Cross-platform tests with **code coverage** — threshold checks (≥ 50%) and regression detection — plus tests against the minimum supported Qt version on Linux -- Nightly, when `staging` has changed, the pipeline also produces: + - Cross-platform tests with **code coverage** — threshold checks (≥ 50%) and regression detection — plus tests against the minimum supported Qt version on all platforms +- Pushes that touch the build or packaging, nightly runs (when `staging` has changed) and manual runs also produce: - A rolling **dev pre-release** (`dev_build`) with binaries for all platforms - Deployment of the **dev** version of the website (at `/dev/`) and Doxygen API docs (at `/dev/`) - CodeQL security analysis runs weekly diff --git a/doc/website/docs/development/ci.mdx b/doc/website/docs/development/ci.mdx index 288ca52d556..2db0b5458f8 100644 --- a/doc/website/docs/development/ci.mdx +++ b/doc/website/docs/development/ci.mdx @@ -7,7 +7,7 @@ sidebar_label: Continuous Integration Every change to MNE-CPP is automatically built, tested, and — for releases — packaged across **Windows, Linux, and macOS** before it reaches users. The CI system runs on [GitHub Actions](https://docs.github.com/en/actions) and is organized around the [Main – Staging – Feature branch model](ci-releasecycle.mdx). -Pull requests cannot be merged until all platform jobs pass. Development builds are published nightly from `staging`; stable release binaries are created when a version tag (`v*`) is pushed on `main`. +Pull requests cannot be merged until all platform jobs pass. Development builds are published from `staging` on pushes that touch the build or packaging, and nightly; stable release binaries are created when a version tag (`v*`) is pushed on `main`. ## Guides @@ -21,8 +21,8 @@ Pull requests cannot be merged until all platform jobs pass. Development builds | Branch / Event | Workflow | What Happens | |----------------|----------|--------------| | Pull request → `staging` or `main` | `pull-request.yml` | Build + tests on all platforms (max Qt), min Qt on Linux | -| Push to `staging` | `staging.yml` | Tests with coverage checks, quality gates | -| Nightly (when `staging` changed) | `staging.yml` | Tests (min Qt on all platforms), then dev release binaries, dev website + Doxygen | +| Push to `staging` | `staging.yml` | Tests with coverage checks (min + max Qt, all platforms), quality and docs gates | +| Push touching the build, nightly, manual | `staging.yml` | Also dev release binaries, dev website + Doxygen | | Push to `main` | `main.yml` | Tests, stable website + Doxygen deployment | | Tag `v*` on `main` | `main.yml` | Full stable release: platform binaries, installers, WebAssembly | | Push to `wasm` | `wasmtest.yml` | WebAssembly build deployed to GitHub Pages | From d695259d58c59755c1c6aceff1db4682cdf67d84 Mon Sep 17 00:00:00 2001 From: Christoph Dinh Date: Thu, 15 Oct 2026 00:03:09 +0200 Subject: [PATCH 7/8] MAINT: Hand push releases to a non-cancelled run; narrow the release filter A push no longer builds releases in its own run, which the next push could cancel after dev_build was deleted. If staging compiles and the build or packaging changed since the last dev build, the push starts a release-only manual run instead; later pushes do not cancel it, and it skips the tests the push already ran. The filter ignores src/testframes/ and doc/ and only counts the staging and release workflows, which the release builds do not depend on otherwise: over the last four weeks it would have matched 39 of 106 pushes instead of 74. The compile gate is a job of its own, shared by both paths. --- .github/workflows/staging.yml | 89 +++++++++++++------ doc/website/docs/development/ci-ghactions.mdx | 2 +- 2 files changed, 65 insertions(+), 26 deletions(-) diff --git a/.github/workflows/staging.yml b/.github/workflows/staging.yml index 931ef769c50..ee8370affc4 100644 --- a/.github/workflows/staging.yml +++ b/.github/workflows/staging.yml @@ -8,10 +8,12 @@ # # Every push to `staging` runs the quality and docs gates and all tests (three # OSes, minimum and maximum Qt). The release builds, installers, WebAssembly -# and deployments run on pushes that touch the build or packaging, nightly -# (only when `staging` moved since the last nightly) and on manual dispatch, -# and only once staging compiles. The mne-tools runner pool is shared by the -# whole organization, so they are skipped where a push cannot affect them. +# and deployments run nightly (only when `staging` moved since the last +# nightly), on manual dispatch, and after a push that changed the build or +# packaging since the last dev build, as a separate run that later pushes do +# not cancel. They only start once staging compiles. The mne-tools runner pool +# is shared by the whole organization, so they are skipped where a push cannot +# affect them. # A failing nightly opens an issue, which closes when a nightly passes again. # # This is the DEVELOPMENT pipeline: @@ -44,6 +46,11 @@ on: # tests take ~1.5 h, so the release-build burst lands around 02:45–04:15. - cron: '13 1 * * *' workflow_dispatch: + inputs: + release_only: + description: "Skip the tests (a push already compiled this commit) and only build and publish releases" + type: boolean + default: false # Cancel superseded push runs; a push never cancels a nightly or manual run. concurrency: @@ -62,10 +69,11 @@ env: jobs: # ── Decide whether this run publishes dev builds ───────────────────────── - # Manual runs always do, pushes do when they touch the build or packaging, - # and a nightly does only when staging moved since the previous nightly (a - # failed nightly is not retried on the same commit; its issue stays open - # until a later nightly passes). + # Manual runs and a nightly with new commits do (a failed nightly is not + # retried on the same commit; its issue stays open until a later nightly + # passes). A push never does itself: if it changed the build or packaging + # since the last dev build, it hands the release to a manual run, because + # the next push would cancel the push run after dev_build was deleted. Changes: runs-on: ubuntu-24.04 permissions: @@ -73,6 +81,7 @@ jobs: contents: read outputs: release: ${{ steps.check.outputs.release }} + handoff: ${{ steps.check.outputs.handoff }} steps: - name: Decide whether to build releases @@ -80,20 +89,23 @@ jobs: env: GH_TOKEN: ${{ github.token }} GH_REPO: ${{ github.repository }} - BEFORE: ${{ github.event.before }} run: | + handoff=false case "${{ github.event_name }}" in workflow_dispatch) release=true ;; push) - # Any doubt (new branch, force push, more files than the API lists) builds. - release=true - if [ -n "$BEFORE" ] && [ "$BEFORE" != "0000000000000000000000000000000000000000" ] && - files=$(gh api "repos/$GH_REPO/compare/$BEFORE...${{ github.sha }}" \ + release=false + # Build and packaging files; tests and docs are not part of the release builds. + # Any doubt (no dev build yet, too many files to list) hands off. + handoff=true + if base=$(gh api "repos/$GH_REPO/git/ref/tags/dev_build" --jq .object.sha 2>/dev/null) && + base=$(gh api "repos/$GH_REPO/git/tags/$base" --jq .object.sha 2>/dev/null || echo "$base") && + files=$(gh api "repos/$GH_REPO/compare/$base...${{ github.sha }}" \ --jq 'if (.files | length) < 300 then .files[].filename else "too-many" end'); then - if ! printf '%s\n' "$files" | - grep -qE '(^|/)CMakeLists\.txt$|^cmake/|^scripts/(build|ci|deploy)/|^\.github/workflows/|^too-many$'; then - echo "No build or packaging files changed" - release=false + if ! printf '%s\n' "$files" | grep -vE '^(src/testframes|doc)/' | + grep -qE '(^|/)CMakeLists\.txt$|^cmake/|^scripts/(build|ci|deploy)/|^\.github/workflows/(staging\.yml|release-[^/]*|_reusable-release[^/]*)$|^too-many$'; then + echo "No build or packaging change since the last dev build ($base)" + handoff=false fi fi ;; @@ -110,17 +122,17 @@ jobs: *) release=false ;; esac echo "release=$release" >> "$GITHUB_OUTPUT" + echo "handoff=$handoff" >> "$GITHUB_OUTPUT" - # ── Create / update dev_build pre-release ──────────────────────────────── - # Gated on staging compiling on every test configuration, so a broken build - # never replaces the last good dev_build. Failing tests do not block it; they - # fail the run and open the nightly failure issue instead. - CreateDevRelease: + # ── Compile gate ────────────────────────────────────────────────────────── + # Releases start only once staging compiles on every test configuration, so a + # broken build never replaces the last good dev_build. Failing tests do not + # block it; they fail the run (and open the nightly failure issue). + Compiled: runs-on: ubuntu-24.04 needs: [Changes, Tests, TestsMinQt] - if: ${{ !cancelled() && needs.Changes.outputs.release == 'true' }} + if: ${{ !cancelled() && !inputs.release_only && (needs.Changes.outputs.release == 'true' || needs.Changes.outputs.handoff == 'true') }} permissions: - contents: write actions: read steps: @@ -140,6 +152,31 @@ jobs: exit 1 fi + # ── Hand a push's release to a run that later pushes do not cancel ─────── + Handoff: + runs-on: ubuntu-24.04 + needs: [Changes, Compiled] + if: ${{ !cancelled() && github.event_name == 'push' && needs.Changes.outputs.handoff == 'true' && needs.Compiled.result == 'success' }} + permissions: + actions: write + + steps: + - name: Start the release run + env: + GH_TOKEN: ${{ github.token }} + GH_REPO: ${{ github.repository }} + run: gh workflow run staging.yml --ref "${{ github.ref_name }}" -f release_only=true + + # ── Create / update dev_build pre-release ──────────────────────────────── + # A release-only run follows a push run that already passed the compile gate. + CreateDevRelease: + runs-on: ubuntu-24.04 + needs: [Changes, Compiled] + if: ${{ !cancelled() && needs.Changes.outputs.release == 'true' && (inputs.release_only || needs.Compiled.result == 'success') }} + permissions: + contents: write + + steps: - name: Clone repository uses: actions/checkout@v5 @@ -206,6 +243,7 @@ jobs: # Coverage is only collected on Ubuntu; macOS/Windows always run without it. # Floor and regression tolerance come from tools/quality/coverage_policy.json. Tests: + if: ${{ !inputs.release_only }} uses: ./.github/workflows/_reusable-tests.yml permissions: contents: read @@ -221,6 +259,7 @@ jobs: # Min-Qt on all three OSes, so every push and the G1 evidence cover each # OS x Qt pair. TestsMinQt: + if: ${{ !inputs.release_only }} uses: ./.github/workflows/_reusable-tests.yml permissions: contents: read @@ -542,7 +581,7 @@ jobs: # it when a later nightly passes. NightlyStatus: runs-on: ubuntu-24.04 - needs: [Changes, Quality, Tests, TestsMinQt, CreateDevRelease, Linux, MacOS, Windows, Installer, Doxygen, Docs, Website, WebAssembly, ReleaseEvidence] + needs: [Changes, Quality, Tests, TestsMinQt, Compiled, CreateDevRelease, Linux, MacOS, Windows, Installer, Doxygen, Docs, Website, WebAssembly, ReleaseEvidence] if: always() && github.event_name == 'schedule' && needs.Changes.outputs.release == 'true' permissions: issues: write diff --git a/doc/website/docs/development/ci-ghactions.mdx b/doc/website/docs/development/ci-ghactions.mdx index b8075567abd..5fa96eb0449 100644 --- a/doc/website/docs/development/ci-ghactions.mdx +++ b/doc/website/docs/development/ci-ghactions.mdx @@ -50,7 +50,7 @@ The PR cannot be merged until all matrix jobs pass. This ensures that every chan - Tests with **code coverage** on all platforms — enforcing a minimum threshold (50%) and detecting coverage regressions — plus tests against the minimum Qt version on all platforms - The **documentation gate** (API docs, screenshots, website build) -GitHub-hosted runners are shared by every repository in the `mne-tools` organization, so the release part of the pipeline runs only where it can be affected: on pushes that change `CMakeLists.txt`, `cmake/`, `scripts/build/`, `scripts/ci/`, `scripts/deploy/` or `.github/workflows/`, nightly when `staging` has changed since the last nightly, and on manual dispatch (**Actions → Staging → Run workflow**). Once every test configuration compiles (failing tests do not block it), it: +GitHub-hosted runners are shared by every repository in the `mne-tools` organization, so the release part of the pipeline runs only where it can be affected: nightly when `staging` has changed since the last nightly, on manual dispatch (**Actions → Staging → Run workflow**), and after a push that changed the build or packaging since the last dev build (a `CMakeLists.txt` or `cmake/` outside the tests, `scripts/build/`, `scripts/ci/`, `scripts/deploy/`, or the staging and release workflows). Such a push starts the release as a separate run, which later pushes do not cancel. Once every test configuration compiles (failing tests do not block it), it: - Creates or updates the **`dev_build`** pre-release on GitHub with the latest development binaries - Invokes the platform-specific release workflows (`release-linux.yml`, `release-macos.yml`, `release-windows.yml`, `release-installer.yml`) to produce development binaries tagged as `dev_build` From 2d027e206092191ceb4ca569d81a2500047c4e1b Mon Sep 17 00:00:00 2001 From: Christoph Dinh Date: Thu, 15 Oct 2026 09:55:35 +0200 Subject: [PATCH 8/8] MAINT: Build WebAssembly on every staging push and on PRs WebAssembly breaks in ways no other build sees (32 sources have WebAssembly-only code paths), so it can't wait for a release run. The build moves to a reusable workflow that every staging push and every PR runs (one Linux job); staging publishes it to dev_build and the demo site only in release runs. scripts/wasm/ now also counts as a packaging change. --- .github/workflows/_reusable-wasm.yml | 112 ++++++++++++++++++ .github/workflows/pull-request.yml | 5 + .github/workflows/staging.yml | 105 ++++------------ doc/website/docs/development/ci-ghactions.mdx | 6 +- .../docs/development/ci-releasecycle.mdx | 1 + doc/website/docs/development/ci.mdx | 4 +- 6 files changed, 144 insertions(+), 89 deletions(-) create mode 100644 .github/workflows/_reusable-wasm.yml diff --git a/.github/workflows/_reusable-wasm.yml b/.github/workflows/_reusable-wasm.yml new file mode 100644 index 00000000000..feb8b9651f4 --- /dev/null +++ b/.github/workflows/_reusable-wasm.yml @@ -0,0 +1,112 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright (c) 2026 MNE-CPP Authors +# Christoph Dinh + +# Builds the WebAssembly applications and examples (Linux only). Callers that +# publish them pass upload_artifact and deploy the "wasm-build" artifact. + +name: Reusable WebAssembly build + +on: + workflow_call: + inputs: + upload_artifact: + description: "Upload out/wasm as the wasm-build artifact" + required: false + default: false + type: boolean + +env: + FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true' + +jobs: + WasmBuild: + runs-on: ubuntu-24.04 + + steps: + - name: Clone repository + uses: actions/checkout@v5 + + - name: Install dependencies + run: | + sudo rm -f /etc/apt/sources.list.d/microsoft-*.list /etc/apt/sources.list.d/azure-*.list /etc/apt/sources.list.d/microsoft-*.sources /etc/apt/sources.list.d/azure-*.sources + sudo apt-get update -qq + sudo apt-get install -qq build-essential libgl1-mesa-dev ninja-build + + - name: Setup Emscripten + run: | + cd .. + git clone https://github.com/emscripten-core/emsdk.git + cd emsdk + ./emsdk install 4.0.7 + ./emsdk activate 4.0.7 + + - name: Load external dependency versions + shell: bash + run: ./scripts/ci/load_external_deps.sh + + - name: Download pre-built WASM Qt binaries + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + gh release download qt_binaries -p "qt6_${QT_VERSION_TOKEN}_static_binaries_wasm.tar.gz" -D /tmp + mkdir -p "${RUNNER_TOOL_CACHE}/Qt/${QT_VERSION}/wasm_multithread" + tar xf "/tmp/qt6_${QT_VERSION_TOKEN}_static_binaries_wasm.tar.gz" -C "${RUNNER_TOOL_CACHE}/Qt/${QT_VERSION}/wasm_multithread" + echo "Qt6_DIR=${RUNNER_TOOL_CACHE}/Qt/${QT_VERSION}" >> "$GITHUB_ENV" + + - name: Download host Qt binaries for cross-compilation + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + gh release download qt_binaries -p "qt6_${QT_VERSION_TOKEN}_static_binaries_linux.tar.gz" -D /tmp + mkdir -p "${RUNNER_TOOL_CACHE}/Qt/${QT_VERSION}/gcc_64" + tar xf "/tmp/qt6_${QT_VERSION_TOKEN}_static_binaries_linux.tar.gz" -C "${RUNNER_TOOL_CACHE}/Qt/${QT_VERSION}/gcc_64" + + - name: Download Eigen package + env: + GH_TOKEN: ${{ secrets.GH_PAT || secrets.GITHUB_TOKEN }} + run: | + ./scripts/ci/download_toolchain.sh \ + --kind eigen \ + --version "$EIGEN_VERSION" \ + --output-dir "$GITHUB_WORKSPACE/src/external/eigen" + + - name: Download ONNX Runtime (WASM) + env: + GH_TOKEN: ${{ secrets.GH_PAT || secrets.GITHUB_TOKEN }} + run: | + ./scripts/ci/download_toolchain.sh \ + --kind onnxruntime \ + --version "$ONNXRUNTIME_VERSION" \ + --platform wasm \ + --output-dir "$GITHUB_WORKSPACE/src/external/onnxruntime" + + - name: Clone Skigen + run: ./scripts/ci/clone_skigen.sh + + - name: Build WASM + run: | + source ../emsdk/emsdk_env.sh + ./scripts/wasm/wasm.sh --emsdk 4.0.7 + + - name: Prepare WASM artifacts + run: | + rm -rf out/wasm/bin/mne_analyze_plugins + rm -rf resources/data + cp resources/design/logos/qtlogo.svg out/wasm/bin/qtlogo.svg + if [ -d "out/wasm/examples" ]; then + cp resources/design/logos/qtlogo.svg out/wasm/examples/qtlogo.svg + fi + # Replace bare Qt HTML with branded loading screens & inject COOP/COEP SW + ./scripts/wasm/wasm_postbuild.sh out/wasm/bin + if [ -d "out/wasm/examples" ]; then + ./scripts/wasm/wasm_postbuild.sh out/wasm/examples + fi + + - name: Upload WASM build + if: inputs.upload_artifact + uses: actions/upload-artifact@v7 + with: + name: wasm-build + path: out/wasm + retention-days: 1 diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml index a7ccb0e6061..fe199e6e3be 100644 --- a/.github/workflows/pull-request.yml +++ b/.github/workflows/pull-request.yml @@ -118,3 +118,8 @@ jobs: channel: stable secrets: inherit + # ── WebAssembly build (Linux only, no deployment) ─────────────────────── + WasmBuild: + uses: ./.github/workflows/_reusable-wasm.yml + secrets: inherit + diff --git a/.github/workflows/staging.yml b/.github/workflows/staging.yml index ee8370affc4..aef6d1d086a 100644 --- a/.github/workflows/staging.yml +++ b/.github/workflows/staging.yml @@ -6,9 +6,9 @@ # Staging Branch Pipeline # ═══════════════════════════════════════════════════════════════════════════ # -# Every push to `staging` runs the quality and docs gates and all tests (three -# OSes, minimum and maximum Qt). The release builds, installers, WebAssembly -# and deployments run nightly (only when `staging` moved since the last +# Every push to `staging` runs the quality and docs gates, all tests (three +# OSes, minimum and maximum Qt) and the WebAssembly build. The release builds, +# installers and deployments (including the WebAssembly one) run nightly (only when `staging` moved since the last # nightly), on manual dispatch, and after a push that changed the build or # packaging since the last dev build, as a separate run that later pushes do # not cancel. They only start once staging compiles. The mne-tools runner pool @@ -103,7 +103,7 @@ jobs: files=$(gh api "repos/$GH_REPO/compare/$base...${{ github.sha }}" \ --jq 'if (.files | length) < 300 then .files[].filename else "too-many" end'); then if ! printf '%s\n' "$files" | grep -vE '^(src/testframes|doc)/' | - grep -qE '(^|/)CMakeLists\.txt$|^cmake/|^scripts/(build|ci|deploy)/|^\.github/workflows/(staging\.yml|release-[^/]*|_reusable-release[^/]*)$|^too-many$'; then + grep -qE '(^|/)CMakeLists\.txt$|^cmake/|^scripts/(build|ci|deploy|wasm)/|^\.github/workflows/(staging\.yml|release-[^/]*|_reusable-release[^/]*)$|^too-many$'; then echo "No build or packaging change since the last dev build ($base)" handoff=false fi @@ -432,90 +432,25 @@ jobs: git push origin main # ── WebAssembly (dev) ──────────────────────────────────────────────────── + WasmBuild: + uses: ./.github/workflows/_reusable-wasm.yml + with: + upload_artifact: true + secrets: inherit + + # Builds on every run (WebAssembly breaks in ways no other build sees), but + # publishes only in release runs. WebAssembly: runs-on: ubuntu-24.04 - needs: CreateDevRelease - if: ${{ !cancelled() && needs.CreateDevRelease.result == 'success' }} + needs: [CreateDevRelease, WasmBuild] + if: ${{ !cancelled() && needs.CreateDevRelease.result == 'success' && needs.WasmBuild.result == 'success' }} steps: - - name: Clone repository - uses: actions/checkout@v5 - - - name: Install dependencies - run: | - sudo rm -f /etc/apt/sources.list.d/microsoft-*.list /etc/apt/sources.list.d/azure-*.list /etc/apt/sources.list.d/microsoft-*.sources /etc/apt/sources.list.d/azure-*.sources - sudo apt-get update -qq - sudo apt-get install -qq build-essential libgl1-mesa-dev ninja-build - - - name: Setup Emscripten - run: | - cd .. - git clone https://github.com/emscripten-core/emsdk.git - cd emsdk - ./emsdk install 4.0.7 - ./emsdk activate 4.0.7 - - - name: Load external dependency versions - shell: bash - run: ./scripts/ci/load_external_deps.sh - - - name: Download pre-built WASM Qt binaries - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: | - gh release download qt_binaries -p "qt6_${QT_VERSION_TOKEN}_static_binaries_wasm.tar.gz" -D /tmp - mkdir -p "${RUNNER_TOOL_CACHE}/Qt/${QT_VERSION}/wasm_multithread" - tar xf "/tmp/qt6_${QT_VERSION_TOKEN}_static_binaries_wasm.tar.gz" -C "${RUNNER_TOOL_CACHE}/Qt/${QT_VERSION}/wasm_multithread" - echo "Qt6_DIR=${RUNNER_TOOL_CACHE}/Qt/${QT_VERSION}" >> "$GITHUB_ENV" - - - name: Download host Qt binaries for cross-compilation - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: | - gh release download qt_binaries -p "qt6_${QT_VERSION_TOKEN}_static_binaries_linux.tar.gz" -D /tmp - mkdir -p "${RUNNER_TOOL_CACHE}/Qt/${QT_VERSION}/gcc_64" - tar xf "/tmp/qt6_${QT_VERSION_TOKEN}_static_binaries_linux.tar.gz" -C "${RUNNER_TOOL_CACHE}/Qt/${QT_VERSION}/gcc_64" - - - name: Download Eigen package - env: - GH_TOKEN: ${{ secrets.GH_PAT || secrets.GITHUB_TOKEN }} - run: | - ./scripts/ci/download_toolchain.sh \ - --kind eigen \ - --version "$EIGEN_VERSION" \ - --output-dir "$GITHUB_WORKSPACE/src/external/eigen" - - - name: Download ONNX Runtime (WASM) - env: - GH_TOKEN: ${{ secrets.GH_PAT || secrets.GITHUB_TOKEN }} - run: | - ./scripts/ci/download_toolchain.sh \ - --kind onnxruntime \ - --version "$ONNXRUNTIME_VERSION" \ - --platform wasm \ - --output-dir "$GITHUB_WORKSPACE/src/external/onnxruntime" - - - name: Clone Skigen - run: ./scripts/ci/clone_skigen.sh - - - name: Build WASM - run: | - source ../emsdk/emsdk_env.sh - ./scripts/wasm/wasm.sh --emsdk 4.0.7 - - - name: Prepare WASM artifacts - run: | - rm -rf out/wasm/bin/mne_analyze_plugins - rm -rf resources/data - cp resources/design/logos/qtlogo.svg out/wasm/bin/qtlogo.svg - if [ -d "out/wasm/examples" ]; then - cp resources/design/logos/qtlogo.svg out/wasm/examples/qtlogo.svg - fi - # Replace bare Qt HTML with branded loading screens & inject COOP/COEP SW - ./scripts/wasm/wasm_postbuild.sh out/wasm/bin - if [ -d "out/wasm/examples" ]; then - ./scripts/wasm/wasm_postbuild.sh out/wasm/examples - fi + - name: Download WASM build + uses: actions/download-artifact@v8 + with: + name: wasm-build + path: out/wasm - name: Package and upload WASM to dev_build release env: @@ -581,7 +516,7 @@ jobs: # it when a later nightly passes. NightlyStatus: runs-on: ubuntu-24.04 - needs: [Changes, Quality, Tests, TestsMinQt, Compiled, CreateDevRelease, Linux, MacOS, Windows, Installer, Doxygen, Docs, Website, WebAssembly, ReleaseEvidence] + needs: [Changes, Quality, Tests, TestsMinQt, Compiled, WasmBuild, CreateDevRelease, Linux, MacOS, Windows, Installer, Doxygen, Docs, Website, WebAssembly, ReleaseEvidence] if: always() && github.event_name == 'schedule' && needs.Changes.outputs.release == 'true' permissions: issues: write diff --git a/doc/website/docs/development/ci-ghactions.mdx b/doc/website/docs/development/ci-ghactions.mdx index 5fa96eb0449..a0d913ad9a4 100644 --- a/doc/website/docs/development/ci-ghactions.mdx +++ b/doc/website/docs/development/ci-ghactions.mdx @@ -13,8 +13,8 @@ MNE-CPP's CI is organized around the [Main – Staging – Feature branch model] | Event type | Workflow Name | Workflow Script | Effect | | ---------- | ------------- | --------------- | ------ | -| Pull Requests → `staging` or `main` | `PullRequest` | [pull-request.yml](https://github.com/mne-tools/mne-cpp/blob/staging/.github/workflows/pull-request.yml) | Build and tests on all platforms (maximum Qt), plus minimum Qt on Linux (on all platforms for PRs into `main`). PR cannot be merged until all jobs pass. | -| Pushes to `staging`, nightly | `Staging` | [staging.yml](https://github.com/mne-tools/mne-cpp/blob/staging/.github/workflows/staging.yml) | On push: tests with code coverage threshold/regression checks on all platforms with minimum and maximum Qt, quality and documentation gates. On pushes that touch the build or packaging, nightly and on manual dispatch: also dev release binaries and dev website + Doxygen deployment. | +| Pull Requests → `staging` or `main` | `PullRequest` | [pull-request.yml](https://github.com/mne-tools/mne-cpp/blob/staging/.github/workflows/pull-request.yml) | Build and tests on all platforms (maximum Qt), plus minimum Qt on Linux (on all platforms for PRs into `main`), and the WebAssembly build. PR cannot be merged until all jobs pass. | +| Pushes to `staging`, nightly | `Staging` | [staging.yml](https://github.com/mne-tools/mne-cpp/blob/staging/.github/workflows/staging.yml) | On push: tests with code coverage threshold/regression checks on all platforms with minimum and maximum Qt, quality and documentation gates, and the WebAssembly build. On pushes that touch the build or packaging, nightly and on manual dispatch: also dev release binaries and dev website + Doxygen deployment. | | Pushes to `main` | `Main` | [main.yml](https://github.com/mne-tools/mne-cpp/blob/main/.github/workflows/main.yml) | Builds, tests, stable website + Doxygen deployment. | | Tag `v*` on `main` | `Main` (release jobs) | [main.yml](https://github.com/mne-tools/mne-cpp/blob/main/.github/workflows/main.yml) | Full stable release: platform binaries (Linux, macOS, Windows), installers, WebAssembly, Codecov upload. | | Pushes to the `wasm` branch | `WasmTest` | [wasmtest.yml](https://github.com/mne-tools/mne-cpp/blob/main/.github/workflows/wasmtest.yml) | Creates new versions of the WebAssembly capable MNE-CPP applications and makes them accessible via the repository's `gh-pages` branch. | @@ -39,6 +39,7 @@ When a contributor opens or updates a pull request targeting `staging` (or `main 1. The static **quality gates**. 2. **Builds and tests** with the **maximum** supported Qt version on Linux, macOS, and Windows, and with the **minimum** supported Qt version on Linux, via the reusable test workflow (without coverage uploads). 3. **Builds the documentation** to verify it compiles without errors. +4. **Builds WebAssembly** (without deploying it). The PR cannot be merged until all matrix jobs pass. This ensures that every change is validated on Linux, macOS, and Windows before it reaches the `staging` branch. @@ -49,6 +50,7 @@ The PR cannot be merged until all matrix jobs pass. This ensures that every chan - The static **quality gates** - Tests with **code coverage** on all platforms — enforcing a minimum threshold (50%) and detecting coverage regressions — plus tests against the minimum Qt version on all platforms - The **documentation gate** (API docs, screenshots, website build) +- The **WebAssembly build** (the dev deployment waits for the release run) GitHub-hosted runners are shared by every repository in the `mne-tools` organization, so the release part of the pipeline runs only where it can be affected: nightly when `staging` has changed since the last nightly, on manual dispatch (**Actions → Staging → Run workflow**), and after a push that changed the build or packaging since the last dev build (a `CMakeLists.txt` or `cmake/` outside the tests, `scripts/build/`, `scripts/ci/`, `scripts/deploy/`, or the staging and release workflows). Such a push starts the release as a separate run, which later pushes do not cancel. Once every test configuration compiles (failing tests do not block it), it: diff --git a/doc/website/docs/development/ci-releasecycle.mdx b/doc/website/docs/development/ci-releasecycle.mdx index 18b9167151f..43d1d4b7104 100644 --- a/doc/website/docs/development/ci-releasecycle.mdx +++ b/doc/website/docs/development/ci-releasecycle.mdx @@ -46,6 +46,7 @@ The `staging` branch is the active development integration branch. Feature branc - Every push to `staging` triggers: - Cross-platform tests with **code coverage** — threshold checks (≥ 50%) and regression detection — plus tests against the minimum supported Qt version on all platforms + - The **WebAssembly** build - Pushes that touch the build or packaging, nightly runs (when `staging` has changed) and manual runs also produce: - A rolling **dev pre-release** (`dev_build`) with binaries for all platforms - Deployment of the **dev** version of the website (at `/dev/`) and Doxygen API docs (at `/dev/`) diff --git a/doc/website/docs/development/ci.mdx b/doc/website/docs/development/ci.mdx index 2db0b5458f8..ae33b1d1ba7 100644 --- a/doc/website/docs/development/ci.mdx +++ b/doc/website/docs/development/ci.mdx @@ -20,8 +20,8 @@ Pull requests cannot be merged until all platform jobs pass. Development builds | Branch / Event | Workflow | What Happens | |----------------|----------|--------------| -| Pull request → `staging` or `main` | `pull-request.yml` | Build + tests on all platforms (max Qt), min Qt on Linux | -| Push to `staging` | `staging.yml` | Tests with coverage checks (min + max Qt, all platforms), quality and docs gates | +| Pull request → `staging` or `main` | `pull-request.yml` | Build + tests on all platforms (max Qt), min Qt on Linux, WebAssembly build | +| Push to `staging` | `staging.yml` | Tests with coverage checks (min + max Qt, all platforms), quality and docs gates, WebAssembly build | | Push touching the build, nightly, manual | `staging.yml` | Also dev release binaries, dev website + Doxygen | | Push to `main` | `main.yml` | Tests, stable website + Doxygen deployment | | Tag `v*` on `main` | `main.yml` | Full stable release: platform binaries, installers, WebAssembly |