Organization-wide community-health files and the shared, reusable GitHub Actions CI system used across the SciML ecosystem.

Two things live here:

1. Default community-health files (issue templates, etc.) that GitHub applies to every SciML repo that doesn't define its own. See GitHub's docs on default community health files.
2. Reusable workflows under .github/workflows/ — the topic of the rest of this document. Instead of every package copy-pasting the same CI.yml, Documentation.yml, etc., each package calls a shared workflow with a few lines. Fixes and improvements land here once and every consumer picks them up.

• How it works
• Versioning: the @v1 moving tag
• Quick start
• Workflow reference
  • tests.yml · downstream.yml · downgrade.yml · documentation.yml · runic.yml · format-check.yml / format-suggestions-on-pr.yml · spellcheck.yml · benchmark.yml · tagbot.yml · dependabot-automerge.yml · docs-preview-cleanup.yml · major-version-tag.yml
• Monorepos: sublibrary CI
  • Monorepo structure — full layout spec in Monorepo.md
  • How sublibrary tests run
  • test_groups.toml
  • grouped-tests.yml (root matrix)
  • Dependency-graph change detection
  • sublibrary-project-tests.yml
  • sublibrary-downgrade.yml
• Recommended repository setup
• Secrets
• Full examples
• Releasing changes to these workflows
• Sources

A package's workflow becomes a thin caller that delegates to a reusable workflow here via uses:. The caller supplies its own triggers (on:) and concurrency; the reusable workflow does the work.

# .github/workflows/CI.yml in a consuming repo
name: CI
on:
  pull_request:
    branches: [master]
  push:
    branches: [master]

jobs:
  test:
    uses: "SciML/.github/.github/workflows/tests.yml@v1"
    secrets: "inherit"

Notes that apply to every caller:

• secrets: "inherit" forwards the calling repo's secrets (e.g. CODECOV_TOKEN, DOCUMENTER_KEY) to the reusable workflow. Without it, coverage upload and docs deploy can't authenticate. inherit does not propagate across nested reusable-workflow calls — each level must re-declare it.
• Triggers and concurrency: must live in the caller. Reusable workflows can't define their own push/pull_request triggers.
• Pin with @v1 (see below).

Consumers pin the major tag:

uses: "SciML/.github/.github/workflows/tests.yml@v1"

@v1 is a moving tag that always points at the latest v1.x.y release; major-version-tag.yml advances it automatically when a vX.Y.Z tag is pushed. Repos that want an immutable pin can use @v1.2.3.

• Backward-compatible change → new v1.x.y; @v1 consumers get it automatically.
• Breaking change (removing an input, switching a tool) → v2.0.0; @v1 consumers are unaffected and opt in by switching to @v2.

See RELEASING.md for the full process.

A standard (non-monorepo) package typically has these callers. Each is a few lines:

Monorepos (a package with lib/<sublibrary>/ sub-packages) add one more — sublibrary CI.

A copy-pasteable starter set is in Full examples.

All inputs are optional unless marked required. Defaults are shown.

Runs a package's test suite: checkout → setup Julia → cache → build → Pkg.test → process coverage → upload to Codecov.

It also transitively develops in-repo [sources] path dependencies of the tested project. On Julia < 1.11 (where [sources] isn't auto-resolved), it walks the project's [sources], Pkg.develops each in-repo path dep, and recurses into their [sources] too. This is what lets a monorepo sublibrary be tested via project: lib/X without a hand-written develop step.

jobs:
  test:
    uses: "SciML/.github/.github/workflows/tests.yml@v1"
    secrets: "inherit"

With a group matrix:

jobs:
  test:
    strategy:
      fail-fast: false
      matrix:
        group: [Core, InterfaceI, InterfaceII]
        version: ["1", "lts"]
    uses: "SciML/.github/.github/workflows/tests.yml@v1"
    with:
      group: "${{ matrix.group }}"
      julia-version: "${{ matrix.version }}"
    secrets: "inherit"

Integration test: checks out a downstream repository that depends on this package, develops the PR's version into it, and runs the downstream test suite — catching breakage you'd otherwise only find after release.

jobs:
  downstream:
    strategy:
      fail-fast: false
      matrix:
        repo: [OrdinaryDiffEq.jl, ModelingToolkit.jl]
    uses: "SciML/.github/.github/workflows/downstream.yml@v1"
    with:
      repo: "${{ matrix.repo }}"
    secrets: "inherit"

Runs the test suite with the oldest declared-compatible versions of every dependency (via julia-actions/julia-downgrade-compat) to catch under-specified [compat] lower bounds.

jobs:
  downgrade:
    uses: "SciML/.github/.github/workflows/downgrade.yml@v1"
    secrets: "inherit"

Downgrade is strict: the reusable workflow hardcodes allow_reresolve: false and exposes no allow-reresolve input. The skip list is auto-populated with all Julia stdlibs, so callers no longer hand-list Pkg,TOML,Statistics,… — pass skip only for genuinely-extra deps. The caller-facing julia-version default is "lts", the LTS alias (currently 1.10), tracking the LTS as it advances. (Auto-skip and the lts default land via SciML/.github #73; strict allow_reresolve: false is already in effect.)

Builds and deploys Documenter documentation (and runs doctests, with coverage).

jobs:
  docs:
    uses: "SciML/.github/.github/workflows/documentation.yml@v1"
    secrets: "inherit"

Checks formatting with Runic — the SciML standard formatter. Fails if any tracked file isn't Runic-formatted.

jobs:
  runic:
    uses: "SciML/.github/.github/workflows/runic.yml@v1"
    secrets: "inherit"

Runic exemptions (do not roll Runic out to these): JumpProcesses.jl and Catalyst.jl are exempt from Runic at the maintainer's (Sam Isaacson) request — they stay on their own JuliaFormatter (Format) setup. Don't add runic.yml to these repos or reformat them with Runic.

JuliaFormatter-based alternatives, for repos not yet on Runic. format-check.yml fails on misformatted files; format-suggestions-on-pr.yml posts formatting suggestions as PR comments. Inputs: directory ("."), julia-version ("1"), juliaformatter-version ("2"), concurrent-jobs (false), cancel-in-progress (true). New repos should prefer runic.yml.

Spell-checks the repo with crate-ci/typos. No inputs.

jobs:
  spellcheck:
    uses: "SciML/.github/.github/workflows/spellcheck.yml@v1"
    secrets: "inherit"

Don't carry a typos ignore/version pin in each repo — the shared workflow tracks a current typos, so you get fixes and dictionary updates centrally.

Runs benchmarks (via AirspeedVelocity.jl) and reports results on PRs. Input: julia-version ("1").

Creates GitHub releases/tags when a package is registered, via JuliaRegistries/TagBot. Tags one package — the root, or a monorepo sublibrary when subdir is set. The if-guard (workflow_dispatch or JuliaTagBot actor) and the permissions block live in the reusable workflow; the caller keeps the issue_comment / workflow_dispatch triggers. token and ssh (DOCUMENTER_KEY) come from secrets: inherit.

# .github/workflows/TagBot.yml
name: TagBot
on:
  issue_comment:
    types: [created]
  workflow_dispatch:
jobs:
  tagbot:
    uses: "SciML/.github/.github/workflows/tagbot.yml@v1"
    secrets: "inherit"

Monorepo (tag the root + each sublibrary):

jobs:
  tagbot:
    uses: "SciML/.github/.github/workflows/tagbot.yml@v1"
    secrets: "inherit"
  tagbot-sublibraries:
    strategy:
      fail-fast: false
      matrix:
        package: [lib/Foo, lib/Bar]
    uses: "SciML/.github/.github/workflows/tagbot.yml@v1"
    with:
      subdir: "${{ matrix.package }}"
    secrets: "inherit"

Auto-approves and enables auto-merge on Dependabot PRs matching the configured update types / ecosystems. GitHub still requires the PR's status checks to pass before merging, so only green PRs fast-track. The repo must have auto-merge enabled (ideally with required status checks via branch protection).

# .github/workflows/DependabotAutoMerge.yml
name: Dependabot Auto-merge
on: pull_request
permissions:
  contents: write
  pull-requests: write
jobs:
  automerge:
    uses: "SciML/.github/.github/workflows/dependabot-automerge.yml@v1"
    secrets: "inherit"

Deletes a closed PR's Documenter preview from the docs branch and squashes that branch's history to one commit so it doesn't grow unbounded (Documenter's DocPreviewCleanup).

# .github/workflows/DocPreviewCleanup.yml
name: Doc Preview Cleanup
on:
  pull_request:
    types: [closed]
permissions:
  contents: write
jobs:
  cleanup:
    uses: "SciML/.github/.github/workflows/docs-preview-cleanup.yml@v1"
    secrets: "inherit"

The release-plumbing workflow that lives here and runs on this repo (not a workflow_call consumer). On a vX.Y.Z tag push it force-moves the floating vX tag to that commit, so @vX consumers track the latest vX.Y.Z. See Releasing.

A SciML monorepo is a package with sub-packages under lib/<name>/, each with its own Project.toml and test/runtests.jl (e.g. OrdinaryDiffEq, ModelingToolkit, Optimization, NonlinearSolve). Sublibrary CI runs each sublibrary's tests, and — crucially — only the ones a change actually affects.

The full canonical layout — umbrella root + lib/<Name> packages, the [sources] dependency graph, the one-group-one-folder test structure with dependency-driven per-group Project.tomls, group naming and the <REPO>_TEST_GROUP env var, test_groups.toml, the thin @v1 workflow set, and the standard repo files — is specified in Monorepo.md, the reference for setting up a new monorepo. The reference implementation is SciML/OrdinaryDiffEq.jl. The remainder of this section is the CI-mechanics summary.

sublibrary-project-tests.yml computes the affected sublibraries (see change detection) and runs each via tests.yml with project: lib/X — i.e. lib/X/test/runtests.jl directly, with the test group passed through group-env-name. It needs no per-repo root runtests.jl dispatcher, because tests.yml transitively develops the sublibrary's in-repo [sources]. Per-sublibrary versions / runners / timeouts come from each sublib's test_groups.toml (below).

The same file format declares test groups in two places:

• lib/<name>/test/test_groups.toml — a sublibrary's groups, expanded by the (diff-filtered) sublibrary CI below.
• test/test_groups.toml (repo root) — the root package's own groups, expanded by grouped-tests.yml so the root CI.yml is a thin caller instead of a hand-maintained matrix. Works for non-monorepos too.

A sublibrary file looks like:

[Core]
versions = ["lts", "1", "pre"]

[GPU]
versions = ["1"]
runner = ["self-hosted", "Linux", "X64", "gpu"]
timeout = 60

[QA]
versions = ["lts", "1"]

Per-group fields:

Default when there's no test_groups.toml: for a sublibrary, Core on ["lts","1","pre"] + QA on ["lts","1"]; for the root matrix (grouped-tests.yml), a single Core group (the whole suite) on ["lts","1","pre"]. (See Monorepo.md for the version-set rollout.)

The group name reaches the sublibrary's runtests.jl through an env var. In the project model that var is group-env-name (default GROUP; OrdinaryDiffEq uses ODEDIFFEQ_TEST_GROUP). A sublibrary's runtests.jl typically does:

const GROUP = get(ENV, "GROUP", "All")
if GROUP == "All" || GROUP == "Core"
    # functional tests
end
if GROUP == "All" || GROUP == "QA"
    # Aqua / JET / allocation tests
end

A package's root test groups can be declared once in a root test/test_groups.toml and run via grouped-tests.yml, instead of hand-maintaining a group × version matrix in each repo's CI.yml. The root CI.yml becomes a thin caller:

# .github/workflows/CI.yml
name: CI
on:
  pull_request:
    branches: [master]
    paths-ignore: ['docs/**']
  push:
    branches: [master]
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
jobs:
  tests:
    uses: "SciML/.github/.github/workflows/grouped-tests.yml@v1"
    secrets: "inherit"

and test/test_groups.toml carries the matrix (per-group versions express what would otherwise be a base matrix plus exclude:/include: rows):

[InterfaceI]
versions = ["lts", "1", "pre"]

[AD]
versions = ["lts"]                              # this group only on lts

[QA]
versions = ["lts", "1"]

[Downstream]
versions = ["lts", "1", "pre"]
continue_on_error = true                        # non-fatal group

[GPU]
versions = ["1"]
runner = ["self-hosted", "Linux", "X64", "gpu"]

[Core]
versions = ["lts", "1"]
os = ["ubuntu-latest", "windows-latest", "macos-latest"]   # OS matrix: runs once per OS

grouped-tests.yml runs compute_affected_sublibraries.jl --root-matrix to turn that into the job matrix, then runs each group × version × os cell via tests.yml (project: '.'), dispatching the group through group-env-name (default GROUP) — the same env var the package's runtests.jl already reads. Unlike the per-sublibrary matrix it is not diff-filtered: the root package runs all of its groups on every push/PR.

Not monorepo-only. Any single package can adopt it: with no test/test_groups.toml the default is a single Core group (the whole suite) on ["lts","1","pre"], so a non-monorepo gets the standard version matrix from a near-zero-line CI.yml, and can split into groups later.

A monorepo therefore has two test workflows: grouped-tests.yml for the root package's own groups, and sublibrary-project-tests.yml for the (incremental) lib/<name> sublibraries.

scripts/compute_affected_sublibraries.jl reads the inter-sublibrary dependency graph from each lib/*/Project.toml [deps] (test-only [extras]/[targets] deps do not propagate), then given the changed files:

• A changed sublibrary is directly affected (full version matrix).
• Sublibraries that (transitively) depend on it are downstream-affected and run on the latest stable ("1") only.
• Changes confined to a sublibrary's test/ don't propagate to dependents.
• Changes outside lib/ select nothing (the root suite is covered by CI.yml).

The script's output modes:

Lists the affected lib/* (with change detection) and runs each via tests.yml project: lib/X, expanding test_groups.toml. No root dispatcher needed.

jobs:
  sublibrary-ci:
    uses: "SciML/.github/.github/workflows/sublibrary-project-tests.yml@v1"
    secrets: "inherit"

OrdinaryDiffEq-style caller (custom group env + bounds checking):

jobs:
  sublibrary-ci:
    uses: "SciML/.github/.github/workflows/sublibrary-project-tests.yml@v1"
    with:
      group-env-name: ODEDIFFEQ_TEST_GROUP
      check-bounds: auto
    secrets: "inherit"

Downgrade-compat tests for each lib/* sublibrary.

jobs:
  downgrade-sublibraries:
    uses: "SciML/.github/.github/workflows/sublibrary-downgrade.yml@v1"
    secrets: "inherit"

Downgrade is strict: the reusable workflow hardcodes allow_reresolve: false and exposes no allow-reresolve input. The skip list is auto-populated with all Julia stdlibs plus the in-repo lib/* sublibrary names (path-[sources] packages must not be downgrade-pinned), so callers no longer hand-list them — pass skip only for genuinely-extra deps. The caller-facing julia-version default is "lts", the LTS alias (currently 1.10), tracking the LTS as it advances. (Auto-skip and the lts default land via SciML/.github #73; strict allow_reresolve: false is already in effect.)

• Use secrets: "inherit" on every caller.
• Dependabot for GitHub Actions (keeps actions/checkout etc. current). Don't carry a per-repo crate-ci/typos ignore — the shared spellcheck.yml manages typos centrally. Only include a Julia package-ecosystem block for directories that actually contain a Project.toml.
• No CompatHelper.yml. [compat] bumps come from Dependabot's Julia ecosystem support; CompatHelper is retired in this system.
• Coverage: add CODECOV_TOKEN (see below) and leave coverage: true.
• Formatting: prefer runic.yml.

Forwarded via secrets: "inherit". Set these in the consuming repo (or org):

.github/workflows/CI.yml:

name: CI
on:
  pull_request:
    branches: [master]
    paths-ignore: ['docs/**']
  push:
    branches: [master]
    paths-ignore: ['docs/**']
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
jobs:
  test:
    strategy:
      fail-fast: false
      matrix:
        version: ["1", "lts"]
    uses: "SciML/.github/.github/workflows/tests.yml@v1"
    with:
      julia-version: "${{ matrix.version }}"
    secrets: "inherit"

.github/workflows/Downgrade.yml, Documentation.yml, FormatCheck.yml (runic.yml), SpellCheck.yml, Downstream.yml follow the one-job pattern shown in each workflow's section above.

.github/workflows/SublibraryCI.yml:

name: Sublibrary CI
on:
  pull_request:
    branches: [master]
    paths-ignore: ['docs/**']
  push:
    branches: [master]
    paths-ignore: ['docs/**']
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
jobs:
  sublibrary-ci:
    uses: "SciML/.github/.github/workflows/sublibrary-project-tests.yml@v1"
    secrets: "inherit"

.github/workflows/DowngradeSublibraries.yml:

name: Downgrade Sublibraries
on:
  pull_request:
    branches: [master]
    paths-ignore: ['docs/**']
  push:
    branches: [master]
    paths-ignore: ['docs/**']
jobs:
  downgrade-sublibraries:
    uses: "SciML/.github/.github/workflows/sublibrary-downgrade.yml@v1"
    secrets: "inherit"

Merge to master, then tag a semver release; major-version-tag.yml moves @v1 for you (or run it manually via workflow_dispatch if a tag-push run doesn't fire). Full process in RELEASING.md. Breaking changes get a new major (v2.0.0) so @v1 consumers aren't disrupted.

This repo has its own CI (ci.yml): actionlint (which bundles shellcheck) lints every workflow and the shell in their run: steps, and a Julia test suite (test/runtests.jl) covers scripts/compute_affected_sublibraries.jl (the sublibrary affected-set detection). Keep both green when changing workflows or the script — they ship to the whole org via @v1.

• GitHub: Reusing workflows
• GitHub: Default community health files
• julia-actions — setup-julia, cache, julia-buildpkg, julia-runtest, julia-processcoverage, julia-downgrade-compat
• Runic.jl · JuliaFormatter.jl
• crate-ci/typos · Documenter.jl · AirspeedVelocity.jl · Codecov
• Pkg [sources]