Test matrix

repomatic builds two GitHub Actions test matrices for every project: a full matrix (pushes to the default branch and scheduled runs) and a reduced pull-request matrix (fast feedback on PRs). Both are pre-computed by the metadata job from the project’s [tool.repomatic.test-matrix.*] configuration, so a project shapes its matrix without hand-editing workflow YAML.

This page is the guide: how to decide what the matrix should test, which GitHub-hosted runners exist and how they trade off on speed, and a worked example. For the per-key configuration reference (types, defaults), see the configuration page.

How the matrix is built

The base axes are os and python-version, seeded from repomatic’s defaults (TEST_RUNNERS_FULL/TEST_RUNNERS_PR and TEST_PYTHON_FULL/TEST_PYTHON_PR in repomatic/matrix_axes.py). A project then reshapes the matrix through a fixed chain of transformations, each a [tool.repomatic.test-matrix.*] key, applied in this order:

1. replace: swap axis values in place.

2. remove: drop axis values from an axis.

3. variations: add extra axis values (full matrix only), including brand-new axes.

4. exclude: remove specific combinations.

5. include: add or augment combinations. GitHub processes include after exclude. A directive that merges into at least one surviving job augments those jobs only; a directive that matches no surviving job (because it fully re-specifies an excluded combination) is appended as a new standalone job. A partial include does not resurrect excluded slices.

A separate unstable pass (full matrix only) flags matching combinations continue-on-error. Because the order is fixed, the transforms compose predictably. variations and unstable touch only the full matrix, keeping the PR matrix a small curated set. See workflows § Dynamic test matrices for why this exists (GitHub’s static strategy.matrix cannot express it) and the configuration reference for each key.

Inspect the computed matrix

To see the matrix your configuration actually produces, render it as a grid with repomatic show-test-matrix: one row per Python version, one column per runner, each cell flagging whether that job runs stable, unstable (continue-on-error), or is absent (—).

$ repomatic show-test-matrix full
╭────────┬──────────────────┬──────────────┬─────────────┬────────────────┬────────────────┬──────────────╮
│ Python │ ubuntu-26.04-arm │ ubuntu-26.04 │ macos-26    │ macos-26-intel │ windows-11-arm │ windows-2025 │
├────────┼──────────────────┼──────────────┼─────────────┼────────────────┼────────────────┼──────────────┤
│ 3.10   │ ✅ stable        │ ✅ stable    │ ✅ stable   │ ✅ stable      │ —              │ ✅ stable    │
│ 3.14   │ ✅ stable        │ ✅ stable    │ ✅ stable   │ ✅ stable      │ ✅ stable      │ ✅ stable    │
│ 3.14t  │ ✅ stable        │ —            │ —           │ —              │ —              │ —            │
│ 3.15   │ ⁉️ unstable      │ ⁉️ unstable  │ ⁉️ unstable │ ⁉️ unstable    │ ⁉️ unstable    │ ⁉️ unstable  │
╰────────┴──────────────────┴──────────────┴─────────────┴────────────────┴────────────────┴──────────────╯

With no [tool.repomatic.test-matrix.*] overrides, this is the built-in default: the six runners from the inventory below, the default Python versions, and the rows the transform chain contributes: the 3.15 prerelease flagged unstable, the free-threaded 3.14t build pinned to a single runner as a stable smoke test, and windows-11-arm dropped on 3.10.

The reduced pull-request matrix keeps one runner per OS and two Python versions, for faster feedback:

$ repomatic show-test-matrix pr
╭────────┬──────────────────┬───────────┬──────────────╮
│ Python │ ubuntu-26.04-arm │ macos-26  │ windows-2025 │
├────────┼──────────────────┼───────────┼──────────────┤
│ 3.10   │ ✅ stable        │ ✅ stable │ ✅ stable    │
│ 3.14   │ ✅ stable        │ ✅ stable │ ✅ stable    │
╰────────┴──────────────────┴───────────┴──────────────╯

The grid honors the global --table-format option, so the same view renders as GitHub-flavored Markdown, CSV, JSON, and the rest. For the raw GitHub Actions matrix the metadata job hands to CI: the os and python-version axes plus the include/exclude directives that shape them, request the test_matrix (or test_matrix_pr) key from repomatic metadata:

$ repomatic metadata test_matrix --format json

Choosing what to test

A matrix is a budget. Every cell costs runner minutes and adds to wall-clock. Spend the budget where a failure is both likely and informative; keep everything speculative cheap.

Cover the shipped configuration broadly

The combination your users actually install — released dependencies on a stable Python — earns the widest spread of operating systems and Python versions. This is the core of the matrix: a regression here reaches everyone, so it is worth catching on every platform.

Probe forward-looking axes narrowly

Anything not yet shipped is an early-warning signal, not a support promise: a prerelease Python, a dependency’s development branch, an unreleased build. Run each on a single runner. If it breaks you want a heads-up, not a cross-platform report, and once that version ships the broad shipped-config coverage picks it up anyway. Flag these jobs continue-on-error through test-matrix.unstable so an expected breakage does not fail the build.

A prerelease Python says so in its job title. repomatic attaches a python-label key to those cells, spelling the version the way pyenv and actions/setup-python name a development build, so the job reads ⁉️ ubuntu-26.04 / py3.15-dev and its continue-on-error marking carries its own explanation. That label is display-only: uv does not parse the -dev form, so the python-version axis keeps the bare 3.15, and 3.15 remains the value a test-matrix directive has to name.

Smoke-test released build flavors on one runner

A free-threaded build (the t suffix, officially supported since 3.14) is a released flavor of a version the shipped-config slice already covers on every platform: the same interpreter, just compiled without the GIL. Because it is released, it is expected to work, so it runs stable, not continue-on-error like a prerelease. But re-running the whole suite on every platform buys little: one runner catches a free-threading-specific break, and the base version’s cross-platform coverage handles the rest. So a flavor takes the narrow spread of a forward-looking probe with the stable outcome of shipped config. repomatic pins 3.14t to its fastest Linux runner by default; to add another flavor, give it a python-version variation pinned to one runner with exclude (the worked example’s pattern) and leave it out of test-matrix.unstable.

Pin the dependency floor and any known-regression release

When a project supports a range of a core dependency (say >= 2.3), CI by default only ever exercises whatever the lockfile resolves to, usually the newest version. The floor is declared but never verified, so it rots silently until a downstream user on an older version hits the break. Add the floor as an explicit matrix value so the bottom of the range runs on every CI pass.

Add any single mid-range release whose behavior a workaround specifically targets, too. That release is the one version where the shim is load-bearing, so it is the one version that catches the shim regressing: bracketing the range with floor and latest alone would miss it.

When the dependency’s patch releases are not reliably behavior-stable — some projects re-cut a patch to fix a mid-stream regression — go further and pin every release in the range, not just the floor and the one regression you happen to know about. You cannot predict which patch shifts behavior, so testing each release is the only way to bound the perimeter. The newest is covered by the moving released value; pin every earlier one. That list grows by one each time the dependency ships, so back it with a test (see Guard the matrix with a test below) that fails when the matrix falls behind.

Pin each dependency-version to one Python

A pinned dependency-version is there to test the dependency, and a dependency’s behavior rarely turns on the Python version: its shims are version-of-the-dependency logic, not version-of-Python logic. Python compatibility is already covered broadly by the shipped-config slice (every Python on the released dependency). So run each pinned version on a single Python rather than the full set. The floor Python is the natural pick: min-dependency × min-Python is the realistic oldest-environment corner, and pinning to one Python keeps the dependency × Python product from multiplying.

For the same reason, keep pinned (old) dependency-versions off the prerelease Python. “Oldest supported dependency × a Python that is not released yet” is a combination no user runs; reserve the prerelease-Python probe for the released dependency.

Pinning a value to a single cell is verbose in the exclude model. Say you carry a floor (4.2) and one regression-prone release (5.0) of acme, and want each on a single cell: the floor Python of the fastest runner. You add them as matrix values, which multiplies them across every OS and Python, then exclude every combination but the one you want, including the prerelease Python (per the rule above). With the slow-architecture twins removed (as in the worked example below) four runners and three Pythons remain, so each pinned version costs five excludes:

[tool.repomatic]
# Released acme everywhere, plus the floor and the regression release.
test-matrix.variations.acme-version = ["4.2", "5.0", "released"]
# Pin 4.2 and 5.0 each to (ubuntu-26.04-arm, 3.10) by dropping every other cell.
test-matrix.exclude = [
  { "os" = "ubuntu-26.04", "acme-version" = "4.2" },
  { "os" = "macos-26", "acme-version" = "4.2" },
  { "os" = "windows-2025", "acme-version" = "4.2" },
  { "python-version" = "3.14", "acme-version" = "4.2" },
  { "python-version" = "3.15", "acme-version" = "4.2" },
  { "os" = "ubuntu-26.04", "acme-version" = "5.0" },
  { "os" = "macos-26", "acme-version" = "5.0" },
  { "os" = "windows-2025", "acme-version" = "5.0" },
  { "python-version" = "3.14", "acme-version" = "5.0" },
  { "python-version" = "3.15", "acme-version" = "5.0" },
]

test-matrix.full-include states each cell directly instead, dropping the acme-version axis altogether: released becomes the default and each pin is one explicit exception that lists only what differs from the shipped configuration (unset axes inherit the defaults: released dependencies, stable state). The variation and its ten excludes become a one-line include and two rows:

[tool.repomatic]
# Released acme everywhere (the broad shipped-config slice)...
test-matrix.include = [{ "acme-version" = "released" }]
# ...plus the floor and regression release pinned to one cell each.
test-matrix.full-include = [
  { "os" = "ubuntu-26.04-arm", "python-version" = "3.10", "acme-version" = "4.2" },
  { "os" = "ubuntu-26.04-arm", "python-version" = "3.10", "acme-version" = "5.0" },
]

Both produce the same jobs: released acme across every runner and Python, plus 4.2 and 5.0 on the single floor cell. The full-include rows join the full matrix only; the PR matrix ignores them. Reach for variations plus exclude when a pinned version should instead span every Python, as in the worked example below.

Select runners by measured speed, not architecture

When you reduce to one runner per OS, pick the fastest one for your workload, measured from your own CI. Do not reflexively choose the ARM image because it is “the future”: architecture speed is not uniform across operating systems (see the inventory below), and the faster choice differs per platform. When you do not need to test both architectures of an OS, drop the slower twin entirely rather than carrying it.

The phrase for your workload is load-bearing. The architecture gap is wide for a parallel, compute-heavy job (a pytest --numprocesses=auto suite that scales with cores) and narrow-to-nonexistent for a job dominated by checkout and dependency install. So the right runner differs by job type, not just by project: see § Architecture speed is workload-dependent for the split repomatic measured between its heavy test suite and its light mechanical jobs.

For a compute-bound parallel workload, that measurement keeps landing on the same runner: ubuntu-26.04-arm is the fastest repomatic has measured and sits in the cheapest tier (GitHub bills hosted macOS at roughly 10x Linux minutes, and ARM Linux matches or beats x86 Linux on both speed and price). So when you need a single fast runner — the PR Linux slot, a single-runner flavor smoke test, or a pinned dependency cell — ubuntu-26.04-arm is the default pick. macos-26 is fast too, but its minute multiplier makes it a poor default; reserve it and the Windows runners for the OS coverage only they provide.

Guard the matrix with a test

A test matrix is configuration, and configuration rots silently: a new dependency release, a raised floor, or a typo’d runner name does not announce itself. Back the matrix with a unit test that re-derives what should be tested from the project’s own metadata and compares it to what the matrix does test, turning drift into a failing CI check instead of a bug a user reports later.

The highest-value check ties a pinned dependency axis to its declared specifier: assert that the pinned versions equal the releases the specifier allows (reading the release list from the package index), minus the newest, which the released value already covers. A freshly published release then fails the test until it is pinned; a pin that drops below a raised floor, or that gets yanked, fails until it is removed. A cheaper, network-free companion asserts the lowest pinned version equals the specifier’s floor, catching a floor change that forgot the matrix even when the index is unreachable.

The same spirit covers the matrix’s other invariants: its lowest Python should equal the project’s requires-python floor, and every exclude should reference a real axis value: a misspelled runner silently excludes nothing and runs the job anyway, which repomatic’s lint-repo check flags as a no-op exclude.

GitHub-hosted runner inventory

repomatic’s full matrix spans both architectures of each OS; the reduced PR set keeps one per OS. The runners (defined in repomatic/matrix_axes.py):

Runner	OS	Architecture	In PR set	Notes
ubuntu-26.04-arm	Linux	ARM64	yes	Fastest measured on the parallel suite, cheapest tier; default single-runner pick (PR Linux slot, flavor smoke tests, pinned cells).
ubuntu-26.04	Linux	x86-64	no	x86 Linux coverage in the full matrix. Still labelled preview by GitHub, see below.
macos-26	macOS	ARM64 (Apple silicon)	yes	Faster macOS image, fast overall, but billed at ~10x Linux minutes; use only when macOS coverage is needed.
macos-26-intel	macOS	x86-64	no	Legacy Intel; ~2x slower than macos-26.
windows-11-arm	Windows	ARM64	no	Compute ties windows-2025; full-matrix only, for native ARM64 execution coverage.
windows-2025	Windows	x86-64	yes	Compute tied with windows-11-arm; the PR-set Windows pick.

Every job runs on one of these six. The light mechanical jobs and the Linux Nuitka build hosts included: “where is the suite exercised” and “what may a job run on” are one question, so lint-repo fails any runs-on: naming something else. Each extra image is one more to track, pin and migrate, and the one that used to sit outside the axes lost the measurement that justified it (see § The lean-image question, settled).

Preview images and what “stable” means here

GitHub still labels the Ubuntu 26.04 pair preview, and repomatic ships them as stable test axes anyway. That is a deliberate reading of what the label governs, worth stating because it is the one place this project overrides a vendor’s own classification.

An image is treated as stable here once it has been validated against this suite, not once GitHub relabels it. The preview flag primarily gates whether an image is eligible to sit behind ubuntu-latest and the other -latest aliases. This project never uses those aliases: a floating alias re-points to a new image with no commit to review, so a breakage arrives detached from any change, which is why lint-repo rejects a -latest runner outright. With the alias question off the table, what remains is whether the image runs the suite correctly and quickly, and that is measurable.

It was measured before the swap. Both images ran the full matrix as continue-on-error cells over consecutive pushes, alongside the GA runners they would replace:

Python	ubuntu-24.04-arm (GA)	ubuntu-26.04-arm (preview)
3.10	66s	56s
3.14	114s	82s
3.15	120s	118s

Faster at two of three versions, tied at the third, with nothing failing. That is the evidence the swap rests on, and the § Measuring your own recipe is how to reproduce it.

Caution

The residual risk is capacity, not correctness. GitHub warns that a preview image’s capacity “will be balanced only throughout the next weeks”, so queue time can be worse than the runtimes above suggest, and queue time already dominates this project’s CI. That risk was weighed against fleet homogeneity and lost: keeping the release binaries on their own GA images meant maintaining a second Linux pair purely to hedge a queue, and every extra image is one more to track, pin and migrate. The Linux Nuitka builds therefore run on the same axes as the suite. A project that would rather wait for GA can pin the old images back with one line: test-matrix.replace.os = { "ubuntu-26.04-arm" = "ubuntu-24.04-arm" }.

The same reasoning is what keeps 3.15 flagged unstable while these runners are not: a prerelease Python can still change before its final release, so its cells are an early-warning signal rather than a verdict. A runner image that passes the suite today is simply passing the suite.

Speed tendencies

Relative speed is workload-dependent, so the only authoritative numbers are your own. The tendencies below come from repomatic’s own full test suite, taken as the median across the five most recent successful runs on all six runners. Two numbers matter and can disagree: job wall-clock (the startedAt/completedAt delta, what you pay in CI minutes) and compute (just the test-execution steps, with checkout and environment setup stripped out). When they diverge, a non-compute step is the cause.

• Linux: ARM is much faster. ARM Linux ran the suite two to three times faster than the lean ubuntu-slim that used to hold the x86 axis (median 2.9x on job wall-clock, at every Python version), and the gap holds on compute alone. That lean image was the slowest tier overall for a heavy suite: its free-threaded 3.14t cell was the single slowest cell in the matrix at ~250s. That is why the flavor smoke test moved to ARM Linux (see § Smoke-test released build flavors on one runner), and it was the first sign of a gap later measured across the whole fleet (§ The lean-image question, settled).

• macOS: Apple silicon beats Intel by roughly 1.8-2x (about 1.8x on job wall-clock, about 2x on compute), not a single-digit margin. macos-26 is in fact one of the fastest runners overall; macos-26-intel is the slow one. macOS as a tier does not gate the matrix; the slowest x86 Linux cell does.

• Windows: compute is a tie. On test-execution time the two images sit within ~6% (ARM is marginally ahead on the prerelease Python). The two used to diverge on per-job wall-clock, but that gap came from a coverage-upload step no job runs any more. windows-2025 stays the PR-set Windows pick.

Caution

These figures are one project’s, and they drift. Runner images are re-provisioned, new images appear and old ones are retired, and an outlier can be a transient stall rather than a property of the image. Some gaps are systematic, though: the 2-3x ARM-versus-x86 Linux ratio above shows up in every run. Per-job wall-clock also folds in checkout and setup, so isolate the test steps before attributing a gap to the image’s compute. Treat all of this as a starting hypothesis, not a constant, and re-confirm against your own timings.

Architecture speed is workload-dependent

The ratios above are the test suite’s, and they do not generalize to every job. The suite runs pytest --numprocesses=auto, so it parallelizes across cores and leans on Python startup and subprocess spawns: exactly where ARM pulls ahead. repomatic’s light mechanical jobs (the linters and formatters that run on every push) behave differently, and a controlled A/B shows why.

Three Linux runners ran the real tool commands on the same commit, which separates two effects the headline “2.9x” had conflated:

• Leanness: ubuntu-slim (lean x86) versus ubuntu-24.04 (full x86).

• Architecture: ubuntu-24.04 (full x86) versus ubuntu-24.04-arm (full ARM).

Only one mechanical job is compute-bound enough to matter: mdformat (the autofix Format Markdown job, which spawns one mdformat process per file).

Step	Runner	mdformat
baseline	ubuntu-slim (lean x86)	110s
remove leanness	ubuntu-24.04 (full x86)	97s (1.13x)
remove x86	ubuntu-24.04-arm (full ARM)	77s (1.26x)

Of the 1.43x end-to-end gain, most is architecture (1.26x) and a little is leanness (1.13x). Every other tool (ruff, mypy, gitleaks, actionlint, zizmor, typos, yamllint) finished in 1-4s on all three runners, within noise: those jobs are dominated by checkout and uv install (~15-20s), which a faster CPU barely touches, and ARM setup was if anything marginally slower. Those linters all ran on ARM Linux with no missing binaries, but mdformat is the exception that matters (see the decision below).

The decisions that follow:

• Test PR slot uses ubuntu-26.04-arm. The heavy parallel suite genuinely runs ~2-3x faster on ARM, so PR feedback is quicker; x86 Linux stays covered in the full matrix.

• Format Markdown stays on x86. mdformat-config pulls taplo, which ships no linux-aarch64 wheel and has a broken 0.9.3 sdist, so a fresh ARM install fails to build it. That constraint is the job’s alone, and it is the reason the fleet’s x86 axis is worth keeping rather than going ARM-only.

Caution

The conclusion this section originally drew, that the light jobs should stay on a lean image, did not survive being measured end to end. See § The lean-image question, settled. The 1.13x/1.26x decomposition above remains a fair reading of tool execution on one commit; it was simply the wrong quantity to decide a runner on. Always include a full-x86 runner in an architecture A/B, and time whole jobs rather than the tool pass.

The lean-image question, settled

ubuntu-slim held every light mechanical job for a long time, on the reasoning above: those jobs are setup-bound, so a faster CPU buys nothing, and a smaller image ought to provision quicker. The A/B decomposition supported the first half and nobody tested the second.

Measuring it settled the question in one pass. Every runs-on: ubuntu-slim moved to ubuntu-26.04, and whole-job wall-clock was compared against the preceding runs:

Workflow	ubuntu-slim	ubuntu-26.04
Lint	146s	106s	27% faster
Autofix	477s	325s	32% faster

Twenty of twenty-two jobs improved, by 20-56%. One tied and one was 5% slower, both inside the noise. Format Markdown, the only compute-bound job, went from 151s to 101s, far past the 1.13x that timing the tool pass alone had predicted.

The lean image was never faster; it was slower almost everywhere, and most of the gap sits in exactly the setup phase the earlier measurement could not see. So ubuntu-slim is retired, and lint-repo now rejects it like any other untracked image.

Caution

The ubuntu-26.04 column is a single run against a seven-to-nine run baseline, so treat the magnitude as provisional. What makes the direction trustworthy is that twenty of twenty-two independent jobs moved the same way at once, which noise does not usually do. Re-confirm against your own timings before copying the conclusion: a project whose light jobs are dominated by something else may still find the lean image wins.

Measuring your own

$ repomatic job-timings --workflow tests.yaml --limit 5

That reports the median whole-job wall-clock per runner image across the most recent successful runs, attributing each job to the image its name carries. Only successful runs are sampled: a failed run’s jobs stop early and time where the failure landed rather than what the image costs. The median across several runs is what turns a queue stall into noise rather than a verdict.

Whole-job is the figure that matters and the one this reads, because the jobs API reports a start and an end timestamp and nothing finer. That is deliberate: timing the tool pass alone is exactly the measurement that kept the lean image in place for years (see § The lean-image question, settled), and it is not expressible through this command.

Pass --output to write the table as Markdown, which is how the inventory above is refreshed. It is regenerated by hand rather than by a job: these numbers move on every run, so a workflow rewriting them would open a pull request forever and never converge.

To isolate one variable, compare cells that differ only in os at the same Python and dependency versions. --sort-by reorders the table, and the durations are zero-padded so that ordering is chronological rather than alphabetical.

Worked example: widening a dependency’s supported range

Suppose a project lowers its floor on a core dependency acme from >= 5 to >= 4.2 to install in more environments. It carries small shims for APIs that changed in acme 5.0, and one of those shims works around a regression that existed only in acme 5.0 (fixed in 5.0.1). The matrix should verify the whole >= 4.2 range without ballooning, and keep the speculative jobs fast.

[tool.repomatic]
# Drop the slower-architecture runner of each OS, keeping the faster twin
# (measured here: Intel macOS and ARM Windows finish each job slower).
test-matrix.remove.os = ["macos-26-intel", "windows-11-arm"]

# Add the floor (4.2), the regression release (5.0), and the development
# branch alongside whatever the lockfile resolves to.
test-matrix.variations.acme-version = ["4.2", "5.0", "released", "main"]

# Pin the floor, the regression release, and the dev branch to the single
# fastest runner; the shipped config (released acme) keeps the full spread.
# After the remove above, the non-pinned runners are ubuntu-26.04, macos-26,
# and windows-2025.
test-matrix.exclude = [
  { "os" = "ubuntu-26.04", "acme-version" = "4.2" },
  { "os" = "macos-26", "acme-version" = "4.2" },
  { "os" = "windows-2025", "acme-version" = "4.2" },
  { "os" = "ubuntu-26.04", "acme-version" = "5.0" },
  { "os" = "macos-26", "acme-version" = "5.0" },
  { "os" = "windows-2025", "acme-version" = "5.0" },
  { "os" = "ubuntu-26.04", "acme-version" = "main" },
  { "os" = "macos-26", "acme-version" = "main" },
  { "os" = "windows-2025", "acme-version" = "main" },
]

# The unreleased acme branch is an early-warning probe: never fail the build on it.
test-matrix.unstable = [{ "acme-version" = "main" }]

On top of the built-in 3.14t flavor smoke test (stable, on ubuntu-26.04-arm with released acme), the acme config resolves to three slices:

Slice	Runs on	continue-on-error
released acme (the shipped config)	all four retained OSes × every base Python	no
4.2 floor and 5.0 regression	ubuntu-26.04-arm × every base Python	no
main acme (dev-branch early warning)	ubuntu-26.04-arm × every base Python	yes

The shipped configuration is exercised everywhere a regression would reach a user; the floor and the one regression-prone release are verified cheaply on the fastest runner; and the development branch gives a heads-up without the power to redden the build. The PR matrix stays the curated reduced set for fast feedback, since variations and unstable apply to the full matrix only. The same shape extends to a prerelease Python (add it as a python-version variation, pin it to one runner with exclude, and mark it unstable) or to a released free-threaded flavor (the same, but stable: leave it out of unstable, as § Smoke-test released build flavors on one runner explains).

repomatic.matrix_axes API

Test matrix constants for CI workflows.

Defines the GitHub-hosted runner images and Python versions used to build test matrices. Separating these from repomatic.metadata makes the CI matrix configuration self-contained and easier to update when runner images or Python releases change.

repomatic.matrix_axes.TEST_RUNNERS_FULL = ('ubuntu-26.04-arm', 'ubuntu-26.04', 'macos-26', 'macos-26-intel', 'windows-11-arm', 'windows-2025')

GitHub-hosted runners for the full test matrix.

Two variants per platform (one per architecture). See available images.

Note

Preview images are adopted on measurement, not on GitHub’s label

GitHub still marks the Ubuntu 26.04 pair preview, which gates their eligibility to sit behind the -latest aliases. This project never uses those aliases (a floating alias re-points with no commit to review, which check_runner_images() rejects outright), so that distinction does not reach it. An image is treated as stable here once it has been validated against this suite, not once a vendor relabels it. Measured over consecutive runs before the swap, ubuntu-26.04-arm beat ubuntu-24.04-arm by 16% on Python 3.10 and 28% on 3.14, tied on 3.15, and failed nothing.

The residual risk is capacity rather than correctness: GitHub warns a preview image’s capacity “will be balanced only throughout the next weeks”, so queue time may be worse than the runtimes above suggest. Release binaries are built on GA images for that reason, see NUITKA_BUILD_TARGETS.

Note

Architecture speed is not uniform across platforms

When reducing to one runner per OS, choose by measured speed, not architecture (see Test matrix). Tendencies from repomatic’s own full test suite: ARM Linux runs two to three times as fast as the lean x86 ubuntu-slim that preceded ubuntu-26.04 on this axis; Apple-silicon macos-26 beats macos-26-intel by ~2x; the two Windows images tie on compute (windows-2025 is the PR pick). Per-job wall-clock folds in setup and upload, so isolate the test steps before blaming the image. These figures drift as images are re-provisioned, so re-confirm against your own job timings.

repomatic.matrix_axes.TEST_RUNNERS_PR = ('ubuntu-26.04-arm', 'macos-26', 'windows-2025')

Reduced runner set for pull request test matrices.

One runner per platform: ARM Linux (ubuntu-26.04-arm) and Apple-silicon macOS (macos-26) are the fastest of their platform on the test workload, plus x86 Windows (windows-2025, where the two Windows images tie on compute). x86 Linux stays covered by the full matrix (TEST_RUNNERS_FULL).

Note

Why ARM Linux for the PR slot

The suite runs pytest --numprocesses=auto, so it scales with cores and favors ARM, by two to three times over the x86 image, for quicker PR feedback. See Test matrix for the measurements.

repomatic.matrix_axes.TEST_PYTHON_FULL = ('3.10', '3.14', '3.15')

Python versions tested across every runner in the full matrix.

Spans the supported range: the floor (3.10), the latest stable release (3.14), and the in-development version (3.15, flagged continue-on-error via UNSTABLE_PYTHON_VERSIONS). Intermediate releases (3.11, 3.12, 3.13) are skipped to reduce CI load. Released build flavors (free-threaded) are not full-spread; they get a single-runner smoke test instead, see SINGLE_RUNNER_PYTHON_VERSIONS.

repomatic.matrix_axes.TEST_PYTHON_PR = ('3.10', '3.14')

Reduced Python version set for pull request test matrices.

Just the floor and the latest stable release, for fast PR feedback. The in-development version and released build flavors (free-threaded) are left to the full matrix.

repomatic.matrix_axes.UNSTABLE_PYTHON_VERSIONS: Final[frozenset[str]] = frozenset({'3.15'})

Python versions still in development.

Jobs using these versions run with continue-on-error in CI. Contrast with SINGLE_RUNNER_PYTHON_VERSIONS, which are released and run stable.

repomatic.matrix_axes.PRERELEASE_LABEL_SUFFIX: Final[str] = '-dev'

Suffix marking an unreleased Python in a CI job name.

Appended to each UNSTABLE_PYTHON_VERSIONS member to form the python-label matrix key, so a continue-on-error cell states why it may fail: ⁉️ ubuntu-26.04 / py3.15-dev rather than a bare py3.15 indistinguishable from a released one. Being a plain suffix append, it composes with the free-threaded flavor the way both tools below spell it: 3.15t reads 3.15t-dev.

The spelling is borrowed, not invented. pyenv ships version definitions named 3.15-dev and 3.15t-dev that build from the CPython branch tip, and actions/setup-python documents an x.y-dev syntax resolving to “the latest patch version of Python, alpha, beta and rc (release candidate) releases included”. Anyone reading a GitHub Actions job name has met it in one of the two.

Warning

A label, never a uv request

uv does not implement the syntax. uv python find 3.15 parses as a version request (“No interpreter found for Python 3.15”), while uv python find 3.15-dev falls through to the executable-name branch (“No interpreter found for executable name 3.15-dev”). The workflow hands python-version straight to uv venv --python, so the axis value stays the bare version and this suffix reaches the job name: alone. Writing it into a [tool.repomatic.test-matrix] directive matches no cell.

repomatic.matrix_axes.SINGLE_RUNNER_PYTHON_VERSIONS: Final[dict[str, str]] = {'3.14t': 'ubuntu-26.04-arm'}

Released Python build flavors smoke-tested on a single runner, mapped to it.

A free-threaded build (the t suffix, made officially supported in 3.14 by PEP 779) runs the same released interpreter as its base version, just without the GIL. The base version already gets the full cross-platform spread (TEST_PYTHON_FULL), so the library logic is covered everywhere; the flavor only needs one runner to catch a free-threading-specific break. These run stable (expected to pass), unlike the unreleased UNSTABLE_PYTHON_VERSIONS. The runner is ubuntu-26.04-arm, the default single-runner pick: the fastest measured on compute-bound parallel work and the cheapest tier, and free-threading targets server workloads where Linux/ARM is the norm (see Test matrix).

repomatic.matrix_axes.python_version_sort_key(version)

Sort key ordering python-version axis values by release.

Compares on the numeric release components, then places a build flavor (the free-threaded t suffix of SINGLE_RUNNER_PYTHON_VERSIONS) directly after its base version rather than after every later release: 3.14 sorts before 3.14t, which sorts before 3.15. Non-numeric components are dropped, so an axis value like pypy3.10 falls back to the digits it carries.

Parameters:

version (str) – A python-version axis value, like 3.14 or 3.14t.

Return type:

tuple[tuple[int, ...], int]

Returns:

A key tuple suitable for sorted().

repomatic.metadata API

        classDiagram
  JSONEncoder <|-- JSONMetadata
  StrEnum <|-- Dialect
    

Extract metadata from repository and Python projects to be used by GitHub workflows.

This module solves a fundamental limitation of GitHub Actions: a workflow run is triggered by a singular event, which might encapsulate multiple commits. GitHub only exposes github.event.head_commit (the most recent commit), but workflows often need to process all commits in the push event.

This is critical for releases, where two commits are pushed together:

1. [changelog] Release vX.Y.Z — the release commit to be tagged and published

2. [changelog] Post-release bump vX.Y.Z → vX.Y.Z — bumps version for the next dev cycle

Since github.event.head_commit only sees the post-release bump, this module extracts the full commit range from the push event and identifies release commits that need special handling (tagging, PyPI publishing, GitHub release creation).

Output shapes

Every key is printed to the environment file as one key=value line. Values take three shapes:

is_python_project=true
doc_files="changelog.md" "readme.md" "docs/license.md"
new_commits_matrix={"commit": ["346ce66…", "6f27db4…"], "include": [{"commit": "346ce66…", "short_sha": "346ce66"}]}

A scalar prints bare. A list prints as space-joined, individually quoted items, not a JSON array: workflow if: conditions test membership with a padded contains() against that string. A matrix prints as inlined JSON for fromJSON() to parse into a job matrix. See Metadata.format_github_value() for the encoding, and Dialect for the other output formats.

The full key inventory is generated from this module rather than listed here, so it cannot go stale: run repomatic metadata --list-keys, or read the rendered table in the workflows documentation.

repomatic.metadata.HEREDOC_FIELDS: Final[frozenset[str]] = frozenset({'release_notes', 'release_notes_with_admonition'})

Metadata fields that should always use heredoc format in GitHub Actions output.

Some fields may contain special characters (brackets, parentheses, emojis, or potential newlines) that can break GitHub Actions parsing when using simple key=value format. These fields will use the heredoc delimiter format regardless of whether they currently contain multiple lines.

class repomatic.metadata.Dialect(*values)

Bases: StrEnum

Output dialect for metadata serialization.

github = 'github'

github_json = 'github-json'

json = 'json'

serialize(metadata)

Render metadata in this dialect.

Parameters:

metadata (dict[str, Any]) – Raw key-to-value mapping from Metadata.dump().

Return type:

str

Returns:

The serialized payload.

repomatic.metadata.METADATA_KEYS_HEADER_DEFS: tuple[tuple[str, str], ...] = (('Key', 'key'), ('Description', 'description'))

Column definitions for the metadata keys reference table.

repomatic.metadata.metadata_keys_reference()

Build the metadata keys reference as table rows.

Returns a list of (key, description) tuples for all keys produced by Metadata.dump(), including [tool.repomatic] config fields that are exposed as metadata outputs. Rows are unsorted: sorting is handled by the CLI’s SortByOption.

Return type:

list[tuple[str, str]]

repomatic.metadata.all_metadata_keys()

Returns the set of all valid metadata key names.

Return type:

frozenset[str]

repomatic.metadata.METADATA_VALUE_OPTIONS: frozenset[str] = frozenset({'--format', '--output', '--sort-by', '-o'})

Options on the metadata command consuming the token that follows them.

Needed by repomatic.lint_repo.check_metadata_keys() to tell a positional key from an option’s value while reading a workflow’s run: line. The command itself is not importable from there: repomatic.cli reads sys.stdout.name at import time, so importing it under a test that has replaced stdout raises.

Listed here rather than derived, and pinned against the real command by repomatic’s own test suite, so an option added later cannot quietly turn its value into a token the lint reports as an unknown key.

repomatic.metadata.is_version_bump_allowed(part)

Check if a version bump of the specified part is allowed.

This prevents double version increments within a development cycle. A bump is blocked if the version has already been bumped (but not released) since the last tagged release.

For example: - Last release: v5.0.1, current: 5.0.2 → minor bump allowed - Last release: v5.0.1, current: 5.1.0 → minor bump NOT allowed (bumped) - Last release: v5.0.1, current: 6.0.0 → major bump NOT allowed (bumped)

Note

When tags are not available (e.g., due to race conditions between workflows), this function falls back to parsing version from recent commit messages.

Parameters:

part (Literal['minor', 'major']) – The version part to check (minor or major).

Return type:

bool

Returns:

True if the bump should proceed, False if it should be skipped.

class repomatic.metadata.JSONMetadata(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Bases: JSONEncoder

Custom JSON encoder for metadata serialization.

Constructor for JSONEncoder, with sensible defaults.

If skipkeys is false, then it is a TypeError to attempt encoding of keys that are not str, int, float, bool or None. If skipkeys is True, such items are simply skipped.

If ensure_ascii is true, the output is guaranteed to be str objects with all incoming non-ASCII and non-printable characters escaped. If ensure_ascii is false, the output can contain non-ASCII and non-printable characters.

If check_circular is true, then lists, dicts, and custom encoded objects will be checked for circular references during encoding to prevent an infinite recursion (which would cause an RecursionError). Otherwise, no such check takes place.

If allow_nan is true, then NaN, Infinity, and -Infinity will be encoded as such. This behavior is not JSON specification compliant, but is consistent with most JavaScript based encoders and decoders. Otherwise, it will be a ValueError to encode such floats.

If sort_keys is true, then the output of dictionaries will be sorted by key; this is useful for regression tests to ensure that JSON serializations can be compared on a day-to-day basis.

If indent is a non-negative integer, then JSON array elements and object members will be pretty-printed with that indent level. An indent level of 0 will only insert newlines. None is the most compact representation.

If specified, separators should be an (item_separator, key_separator) tuple. The default is (’, ‘, ‘: ‘) if indent is None and (‘,’, ‘: ‘) otherwise. To get the most compact JSON representation, you should specify (‘,’, ‘:’) to eliminate whitespace.

If specified, default is a function that gets called for objects that can’t otherwise be serialized. It should return a JSON encodable version of the object or raise a TypeError.

default(o)

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return super().default(o)

Return type:

Any

class repomatic.metadata.Metadata

Bases: object

Metadata class.

Implemented as a singleton: every Metadata() call returns the same instance within a process. This is safe because env vars and project files do not change during a single CLI invocation. Use reset() in test teardown to discard the cached instance between tests.

classmethod reset()

Discard the singleton so the next call creates a fresh instance.

Intended for test teardown only. Production code should never call this.

Return type:

None

pyproject_path = PosixPath('pyproject.toml')

sphinx_conf_path = PosixPath('docs/conf.py')

property github_event: dict[str, Any]

Load the GitHub event payload from GITHUB_EVENT_PATH.

GitHub Actions automatically sets GITHUB_EVENT_PATH to a JSON file containing the complete webhook event payload.

git_stash_count()

Returns the number of stashes.

Return type:

int

git_deepen(commit_hash, max_attempts=10, deepen_increment=50)

Deepen a shallow clone until the provided commit_hash is found.

Progressively fetches more commits from the current repository until the specified commit is found or max attempts is reached.

Returns True if the commit was found, False otherwise.

Return type:

bool

commit_matrix(commits)

Pre-compute a matrix of commits.

Danger

This method temporarily modify the state of the repository to compute version metadata from the past.

To prevent any loss of uncommitted data, it stashes and unstash the local changes between checkouts.

The list of commits is augmented with long and short SHA values, as well as current version. Most recent commit is first, oldest is last.

Returns a ready-to-use matrix structure:

{
    "commit": [
        "346ce664f055fbd042a25ee0b7e96702e95",
        "6f27db47612aaee06fdf08744b09a9f5f6c2",
    ],
    "include": [
        {
            "commit": "346ce664f055fbd042a25ee0b7e96702e95",
            "short_sha": "346ce66",
            "current_version": "2.0.1",
        },
        {
            "commit": "6f27db47612aaee06fdf08744b09a9f5f6c2",
            "short_sha": "6f27db4",
            "current_version": "2.0.0",
        },
    ],
}

Return type:

Matrix | None

property event_type: WorkflowEvent | None

Returns the type of event that triggered the workflow run.

Maps event_name (the GITHUB_EVENT_NAME variable, set by GitHub Actions on every run) onto its WorkflowEvent member, so schedule and workflow_dispatch runs resolve to their own event instead of falling in a None hole that nulls every commit matrix.

Caution

When GITHUB_EVENT_NAME is absent or unrecognized, falls back on the historical heuristic: a non-empty GITHUB_BASE_REF means a pull request (only set for pull request events), a present-but-empty one means a push.

property event_actor: str | None

Returns the GitHub login of the user that triggered the workflow run.

property event_sender_type: str | None

Returns the type of the user that triggered the workflow run.

property is_bot: bool

Returns True if the workflow was triggered by a bot or automated process.

This is useful to only run some jobs on human-triggered events. Or skip jobs triggered by bots to avoid infinite loops.

The sender type covers every GitHub App, which is how Dependabot and Renovate author their pull requests today. The explicit login list is kept as a second signal for downstream repositories: sender.type is absent from the event payload outside push and pull_request (and empty when the payload cannot be read at all), and the login is then the only thing left to match on.

The test is deliberately not sender.type != "User", which would also classify an Organization sender as a bot.

property head_branch: str | None

Returns the head branch name for pull request events.

For pull request events, this is the source branch name (e.g., update-mailmap). For push events, returns None since there’s no head branch concept.

The branch name is extracted from the GITHUB_HEAD_REF environment variable, which is only set for pull request events.

property event_name: str | None

Returns the name of the event that triggered the workflow.

Reads GITHUB_EVENT_NAME. This is the raw event name ("push", "pull_request", "workflow_run"), which event_type resolves to a WorkflowEvent member.

property job_name: str | None

Returns the ID of the current job in the workflow.

Reads GITHUB_JOB.

property ref_name: str | None

Returns the short ref name of the branch or tag.

Reads GITHUB_REF_NAME.

property repo_name: str | None

Returns the repository name without owner prefix.

Derived from repo_slug by splitting on /.

property is_awesome: bool

Whether this is an awesome-list repository.

Detected by the awesome- prefix on the repository name.

property repo_owner: str | None

Returns the repository owner.

Reads GITHUB_REPOSITORY_OWNER, falling back to the owner component of repo_slug.

property repo_slug: str | None

Returns the owner/name slug for the current repository.

Resolution order: GITHUB_REPOSITORY env var (CI), gh repo view (authenticated local), git remote URL parsing (offline fallback).

property repo_url: str | None

Returns the full URL to the repository.

Derived from server_url and repo_slug.

property run_attempt: str | None

Returns the run attempt number.

Reads GITHUB_RUN_ATTEMPT.

property run_id: str | None

Returns the unique ID of the current workflow run.

Reads GITHUB_RUN_ID.

property run_number: str | None

Returns the run number for the current workflow.

Reads GITHUB_RUN_NUMBER.

property server_url: str

Returns the GitHub server URL.

Reads GITHUB_SERVER_URL, defaulting to https://github.com.

property sha: str | None

Returns the commit SHA that triggered the workflow.

Reads GITHUB_SHA.

property triggering_actor: str | None

Returns the login of the user that initiated the workflow run.

Reads GITHUB_TRIGGERING_ACTOR. This differs from event_actor (GITHUB_ACTOR) when a workflow is re-run by a different user.

property workflow_ref: str | None

Returns the full workflow reference.

Reads GITHUB_WORKFLOW_REF. The format is owner/repo/.github/workflows/name.yaml@refs/heads/branch.

property changed_files: tuple[str, ...] | None

Returns the list of files changed in the current event’s commit range.

Uses git diff --name-only between the start and end of the commit range. Returns None if no commit range is available (e.g., outside CI).

property binary_affecting_paths: tuple[str, ...]

Path prefixes that affect compiled binaries for this project.

Combines the static BINARY_AFFECTING_PATHS (common files like pyproject.toml, uv.lock, tests/) with project-specific source directories derived from [project.scripts] in pyproject.toml.

For example, a project with mpm = "meta_package_manager.__main__:main" adds meta_package_manager/ as an affecting path. This makes the check reusable across downstream repositories without hardcoding source directories.

property head_commit_message: str

Returns github.event.head_commit.message from the event payload.

Set for push events. Empty string for events that do not carry a head commit (pull_request, schedule, workflow_dispatch).

property yaml_changed: bool

Returns True when the current event’s commit range touches at least one YAML file.

Lets per-job lint gates short-circuit on pushes / PRs that don’t touch YAML. Falls back to “repo contains any YAML file” when the commit range is unavailable (workflow_dispatch), preserving the existing behavior of those manual runs.

property zsh_changed: bool

Returns True when the current event’s commit range touches at least one Zsh file.

Falls back to “repo contains any Zsh file” when the commit range is unavailable.

property workflows_changed: bool

Returns True when the current event’s commit range touches at least one GitHub workflow file.

Falls back to “repo contains any workflow file” when the commit range is unavailable.

property skip_binary_build: bool

Returns True if binary builds should be skipped for this event.

Binary builds are expensive and time-consuming. This property identifies contexts where the changes cannot possibly affect compiled binaries, allowing workflows to skip Nuitka compilation jobs.

Three mechanisms are checked:

1. Branch name — PRs from known non-code branches (documentation, .mailmap, .gitignore, etc.) are skipped.

2. Version-bump commit — Push events whose head commit is a user-initiated version bump (Bump (major|minor) version to) are skipped: the bump merge changes only version strings and uv.lock, so the new binary differs from the previous one only in the baked-in version string. The [changelog] Post-release bump prefix is deliberately not checked here: the prepare-release merge bundles the release commit with the post-release-bump commit, and the release commit must still produce its binary.

3. Changed files — Push events where all changed files fall outside binary_affecting_paths are skipped. This avoids ~2h of Nuitka builds for documentation-only commits to main.

property commit_range: tuple[str | None, str] | None

Range of commits bundled within the triggering event.

A workflow run is triggered by a singular event, which might encapsulate one or more commits. This means the workflow will only run once on the last commit, even if multiple new commits were pushed.

This is critical for releases where two commits are pushed together:

1. [changelog] Release vX.Y.Z — the release commit

2. [changelog] Post-release bump vX.Y.Z → vX.Y.Z — the post-release bump

Without extracting the full commit range, the release commit would be missed since github.event.head_commit only exposes the post-release bump.

This property also enables processing each commit individually when we want to keep a carefully constructed commit history. The typical example is a pull request that is merged upstream but we’d like to produce artifacts (builds, packages, etc.) for each individual commit.

The default GITHUB_SHA environment variable is not enough as it only points to the last commit. We need to inspect the commit history to find all new ones. New commits need to be fetched differently in push and pull_request events.

See also

• https://stackoverflow.com/a/67204539

• https://stackoverflow.com/a/62953566

• https://stackoverflow.com/a/61861763

See also

Pull request events on GitHub are a bit complex, see: The Many SHAs of a GitHub Pull Request.

property current_commit: Commit

Returns the current Commit object.

Raises if HEAD cannot be resolved (an empty repository), mirroring the previous behavior where traversing an empty history raised too.

property current_commit_matrix: Matrix | None

Pre-computed matrix with long and short SHA values of the current commit.

property new_commits: tuple[Commit, ...] | None

Returns list of all Commit objects bundled within the triggering event.

This extracts all commits from the push event, not just head_commit. For releases, this typically includes both the release commit and the post-release bump commit, allowing downstream jobs to process each one.

Commits are returned in chronological order (oldest first, most recent last).

property new_commits_matrix: Matrix | None

Pre-computed matrix with long and short SHA values of new commits.

property new_commits_hash: tuple[str, ...] | None

List all hashes of new commits.

property release_commits: tuple[Commit, ...] | None

Returns list of Commit objects to be tagged within the triggering event.

This filters new_commits to find release commits that need special handling: tagging, PyPI publishing, and GitHub release creation.

This is essential because when a release is pushed, github.event.head_commit only exposes the post-release bump commit, not the release commit. By extracting all commits from the event (via new_commits) and filtering for release commits here, we ensure the release workflow can properly identify and process the [changelog] Release vX.Y.Z commit.

We cannot identify a release commit based on the presence of a vX.Y.Z tag alone. That’s because the tag is not present in the prepare-release pull request produced by the changelog.yaml workflow. The tag is created later by the release.yaml workflow, when the pull request is merged to main.

Our best option is to identify a release based on the full commit message, using the template from the changelog.yaml workflow.

property release_commits_matrix: Matrix | None

Pre-computed matrix with long and short SHA values of release commits.

property release_commits_hash: tuple[str, ...] | None

List all hashes of release commits.

property mailmap_exists: bool

property files: FileInventory

What this repository holds on disk, .gitignore applied.

The inventory is its own concern (repomatic.file_inventory): answering “which Markdown files are there” needs no CI context, no git history and no pyproject.toml. The groups below forward to it so every existing caller, and every metadata output key, keeps its name.

glob_files(*patterns)

Files matching patterns, per FileInventory.glob_files().

Return type:

list[Path]

gitignore_match(file_path)

Whether .gitignore excludes file_path.

Return type:

bool

property gitignore_exists: bool

Whether a .gitignore file is present.

property python_files: list[Path]

Python sources, notebooks included.

property json_files: list[Path]

JSON files Biome can format.

property yaml_files: list[Path]

YAML files.

property pyproject_files: list[Path]

Every pyproject.toml in the tree.

property workflow_files: list[Path]

GitHub workflow definitions.

property doc_files: list[Path]

Documentation sources.

property markdown_files: list[Path]

Markdown files.

property image_files: list[Path]

Images the optimizer can losslessly shrink.

property shfmt_files: list[Path]

Shell scripts shfmt formats.

property zsh_files: list[Path]

Zsh scripts, by extension or shebang.

property is_python_project: bool

Returns True if repository is a Python project.

Presence of a pyproject.toml file that respects the standards is enough to consider the project as a Python one. Delegates to repomatic.pyproject.is_python_project() so the detection rule has a single source of truth.

property is_python_package: bool

Returns True if the repository builds a distributable package.

Strictly narrower than is_python_project: a uv virtual project declares a [project] table to carry its dependencies, then opts out of being built with [tool.uv] package = false. Delegates to repomatic.pyproject.is_python_package(), the same predicate PACKAGE_ONLY resolves against, so the release lane and the checks that police it agree on who publishes.

Prefer this over the truthiness of package_name when gating anything about publishing. package_name only reports what [project] name says, which a virtual project still declares.

property pyproject_toml: dict[str, Any]

Returns the raw parsed content of pyproject.toml.

Returns an empty dict if the file does not exist.

property pyproject: StandardMetadata | None

Returns metadata stored in the pyproject.toml file.

Returns None if the pyproject.toml does not exists or does not respects the PEP standards.

Warning

Some third-party apps have their configuration saved into pyproject.toml file, but that does not means the project is a Python one. For that, the pyproject.toml needs to respect the PEPs.

property config: Config

Returns the [tool.repomatic] section from pyproject.toml.

Merges user configuration with defaults from Config.

property nuitka_entry_points: list[str]

Entry points selected for Nuitka binary compilation.

Reads [tool.repomatic].nuitka.entry-points from pyproject.toml. When empty (the default), deduplicates by callable target: keeps the first entry point for each unique module:callable pair, so alias entry points (like both mpm and meta-package-manager pointing to the same function) don’t produce duplicate binaries. Unrecognized CLI IDs are logged as warnings and discarded.

property dev_targets: set[str]

Nuitka build targets compiled on ordinary (non-release) pushes.

Reads [tool.repomatic].nuitka.dev-targets from pyproject.toml. An empty list disables dev builds entirely. See nuitka_dev_targets for the default and the canary rationale.

Unrecognized target names are logged as warnings and discarded.

property unstable_targets: set[str]

Nuitka build targets allowed to fail without blocking the release.

Reads [tool.repomatic].nuitka.unstable-targets from pyproject.toml. Defaults to an empty set.

Unrecognized target names are logged as warnings and discarded.

property package_name: str | None

Returns package name as published on PyPI.

property project_description: str | None

Returns project description from pyproject.toml.

property script_entries: list[tuple[str, str, str]]

Returns a list of tuples containing the script name, its module and callable.

Results are derived from the script entries of pyproject.toml. So that:

[project.scripts]
mdedup = "mail_deduplicate.cli:mdedup"
mpm = "meta_package_manager.__main__:main"

Will yields the following list:

(
    ("mdedup", "mail_deduplicate.cli", "mdedup"),
    ("mpm", "meta_package_manager.__main__", "main"),
    ...,
)

Each entry is validated against PEP 621 and PyPI conventions:

• The script name (the dict key) must be non-empty, contain at least one non-dot character, and match [A-Za-z0-9._-]+. This mirrors the rule PyPI enforces on uploaded wheels and the check uv-build performs; rejecting names like ../escape, nested/script or . here keeps them from flowing into the binary file path template {{cli_id}}-{{current_version}}-{{target}}.{{extension}} and from there into shell-quoted artifact names, chmod, and attestation commands in the release workflow.

• The script value must split on : into exactly two non-empty parts (module:object). Malformed values raise a descriptive ValueError instead of crashing with an unpacking error.

property mypy_params: list[str] | None

Generates mypy parameters.

Mypy needs to be fed with this parameter: --python-version 3.x.

Extracts the minimum Python version from the project’s requires-python specifier. Only takes major.minor into account.

static get_current_version()

Returns the current version as managed by bump-my-version.

Same as calling the CLI:

$ bump-my-version show current_version

Reads current_version from the first TOML file found in the current working directory: .bumpversion.toml (top-level table) or pyproject.toml ([tool.bumpversion]).

Return type:

str | None

property current_version: str | None

Returns the current version.

Current version is fetched from the bump-my-version configuration file.

During a release, two commits are bundled into a single push event:

1. [changelog] Release vX.Y.Z — freezes the version to the release number

2. [changelog] Post-release bump vX.Y.Z → vX.Y.Z — bumps to the next dev version

In this situation, the current version returned is the one from the most recent commit (the post-release bump), which represents the next development version. Use released_version to get the version from the release commit.

property released_version: str | None

Returns the version of the release commit.

During a release push event, this extracts the version from the [changelog] Release vX.Y.Z commit, which is distinct from current_version (the post-release bump version). This is used for tagging, PyPI publishing, and GitHub release creation.

Returns None if no release commit is found in the current event.

property is_sphinx: bool

Returns True if the Sphinx config file is present.

property minor_bump_allowed: bool

Check if a minor version bump is allowed.

This prevents double version increments within a development cycle.

property major_bump_allowed: bool

Check if a major version bump is allowed.

This prevents double version increments within a development cycle.

property active_autodoc: bool

Returns True if Sphinx autodoc is active.

property uses_myst: bool

Returns True if MyST-Parser is active in Sphinx.

property nuitka_matrix: Matrix | None

Pre-compute a matrix for Nuitka compilation workflows.

Crosses three axes:

• one commit per release commit (during a release) or per new commit (otherwise)

• every [project.scripts] entry point

• every build target of NUITKA_BUILD_TARGETS (runner, platform, architecture, binary extension, and the glibc floor or minimum-OS version that target enforces), narrowed to the [tool.repomatic] nuitka.dev-targets canary subset on an ordinary push (see dev_targets); release commits, schedule and workflow_dispatch runs keep the full roster

Each axis contributes an include entry carrying the extra parameters the compile job needs, keyed on the axis value that selects it: the target’s runner and floors, the entry point’s module and callable, and the commit’s short SHA and version. A final pass adds one include entry per (os, entry_point, commit) triple naming the bin_name the compiled artifact takes, since that name depends on all three at once.

The matrix closes with {"state": "stable"}, which the release workflow reads to decide whether a failing job blocks the release.

Note

Every value comes from NUITKA_BUILD_TARGETS and the project’s own pyproject.toml, so no literal is repeated here: run repomatic metadata nuitka_matrix against a project to see the matrix it computes, or repomatic show-test-matrix for the test one.

property test_matrix: Matrix

Full test matrix for non-PR events.

Combines all runner OS images and Python versions, excluding known incompatible combinations. Marks development Python versions as unstable so CI can use continue-on-error, and adds released build flavors (free-threaded) as stable single-runner smoke tests. Per-project config from [tool.repomatic.test-matrix] is applied last.

When [tool.repomatic.test-matrix] full-include rows are configured, the matrix is emitted as a flat job list ({"include": [...]}) so each row is a standalone combination GitHub runs verbatim, rather than one that augments a base combo sharing its os and python-version.

property test_matrix_pr: Matrix

Reduced test matrix for pull requests.

Skips experimental Python versions and redundant architecture variants to reduce CI load on PRs. Per-project config excludes and includes from [tool.repomatic.test-matrix] are applied, but variations are not (to keep the PR matrix small).

property stale_test_matrix_excludes: list[dict[str, str]]

User test-matrix.exclude entries matching no full-matrix axis value.

An exclude naming a value absent from every axis (like a renamed runner) can never match a combination, so Matrix.prune() drops it silently and its exclusion intent is lost. This drift is common after an upstream runner rename (such as macos-15-intel becoming macos-26-intel). The lint-repo check surfaces these so the drift fails loudly instead of silently.

Returns:

The offending exclude entries, in config order.

property release_notes: str | None

Generate notes to be attached to the GitHub release.

Renders the github-releases template with changelog content for the version. The template is the single place that defines the release body layout.

property release_notes_with_admonition: str | None

Generate release notes with a pre-computed availability admonition.

Builds the same body as release_notes, but injects a > [!NOTE] admonition linking to PyPI and GitHub even before fix-changelog has a chance to update changelog.md.

The engine’s create-release job bakes this body into the GitHub release at draft-creation time, so the admonition is present from the start. Doing it there (rather than editing the release from the caller’s fast publish-pypi lane) removes the cross-lane race where the edit ran before create-release had created the release, and so silently dropped the admonition under continue-on-error. The bake is optimistic: it assumes the parallel PyPI upload succeeds, which it does on the normal path; a failed upload surfaces as a red publish-pypi job, not as a wrong admonition the user must catch.

Returns None when the project is not on PyPI, has no changelog, or has no version to release, in which case create-release falls back to the plain release_notes.

static format_github_value(value)

Transform Python value to GitHub-friendly, JSON-like, console string.

Renders:

• str as-is

• None into empty string

• bool into lower-cased string

• Matrix into JSON string

• Iterable of mixed strings and Path into a serialized space-separated string, where Path items are double-quoted

• other Iterable into a JSON string

Return type:

str

dump_factories()

Lazy value factories for every metadata key, in output order.

Each value is computed only when its key is included, so keys=("is_python_project",) skips nuitka_matrix and the git history walk it pulls in.

Split out of dump() so the key inventory is inspectable without computing anything: tests/test_metadata.py asserts these names match _METADATA_KEY_DESCRIPTIONS plus _metadata_config_fields(), which is what keeps --list-keys, all_metadata_keys() and the emitted output from drifting apart.

Derived from _METADATA_KEY_DESCRIPTIONS rather than re-listing every key: most keys read the attribute of the same name, so only the handful whose value is not a plain attribute carry an explicit factory.

Return type:

dict[str, Callable[[], Any]]

Returns:

Key name to a zero-argument callable producing its value.

dump(dialect=Dialect.github, keys=())

Returns metadata in the specified format.

Defaults to GitHub dialect. When keys is non-empty, only the requested keys are computed and included in the output. Filtered-out keys are never accessed, so callers requesting a small subset avoid triggering expensive dependent computations (git history walks, file system scans, build matrix expansion). See dump_factories().

Return type:

str