feat: channel-compat reusable workflow — run a repo's tests on the OVOS distro release channels

[JarbasAl]

Adds channel-compat.yml, a workflow_call reusable workflow that runs a repo's test suite against the package versions one OVOS distro release channel pins.

Why

Every gate we have looks at the dev edge. None of them looks at what the fleet runs.

The distro publishes one constraints file per channel, and today they are a long way behind dev:

Channel	ovos-workshop	ovos-core	ovos-bus-client	ovos-padatious
stable	>=3.4.0,<3.5.0	>=1.3.1,<1.4.0	>=1.3.4,<1.4.0	>=1.4.2,<1.5.0
testing	>=7.0.6,<8.0.0	>=2.1.1,<3.0.0	>=1.3.7,<2.0.0	>=1.4.3,<2.0.0

A change can be green on dev and still break every device on stable. Nothing catches that today.

This is one of three layers, and each is useless alone:

Layer	Question
Boundary pins	Where did the behavior change? The exact release either side of one break, so a red cell names the commit range.
Channels (this workflow)	What does the fleet run today? Pins come from the distro, fetched live, so the gate moves when the distro moves.
Dev edge	Where is the stack going?

Together they qualify a breakage: which clause, which versions, how many devices.

The one rule

The channel wins for every package it names, except the repo under test. The PR is the thing being judged, so its own version comes from the checkout. pip has no "constrain everything except X", so the workflow reads the repo's distribution name (pyproject.toml, falling back to setup.py --name) and strips that line out of the fetched constraints file before installing.

The constraints file is fetched live, never vendored, and uploaded as an artifact next to a pip freeze. A run that goes red weeks later cannot be reproduced from the URL, because the URL will have moved on.

Not the same as the existing check

build-tests.yml already has a step called the "channel compatibility check". That one reads ovos-releases metadata and asks whether the package's current version is listed in a channel file. This workflow installs and runs code. The docs note the distinction.

Inputs

channel_url (required), channel_name, runner, test_path, python_version, system_deps, pre_install_pip, install_extras, pytest_args, soft_fail, timeout_minutes.

pre_install_pip rather than pre_install, to match the identical input on build-tests.yml and ovoscope.yml — the inputs on this repo's workflows are read across files and a near-miss name is worse than a long one.

One channel per call; the caller matrixes. setuptools<81 is installed unconditionally: channel-age ovos-plugin-manager still imports pkg_resources.

Expect red at first

A channel is behind dev by construction, so a first run usually fails a pile of tests. That is the finding, not a broken workflow. Callers should start with soft_fail: true and turn it off once the baseline is understood. continue-on-error is not an option: GitHub rejects it on a job that calls a reusable workflow, which is why the advisory mode is an input here.

ovos-test-harness#16 is the fully worked version: checked-in per-channel known-gap files under test/channel_gaps/, consumed through the OVOS_CHANNEL env var this workflow sets, that strict-xfail exactly the known failures. Known gaps stay visible and green, new breakage is red, and a gap the channel has since closed is red too, as the cue to delete the line. Seeded from real runs there: stable ends at 154 passed, 209 xfailed, testing at 181 passed, 110 xfailed.

Also in this PR

• README.md workflow table entry.
• docs/workflow-reference.md — full section with inputs, steps, and a caller example.
• test/test_workflow_inputs.py passes on the new file (the two pre-existing failures on _selftest-uv.yml and tts-intelligibility.yml are untouched).

Callers: ovos-core#838, ovos-workshop#504. Part of the compat train alongside ovos-bus-client#271.

---

Implemented by Claude (opus), orchestrated by Claude Fable.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added a reusable workflow for testing projects against live OVOS release-channel constraints.
  • Supports configurable channels, Python versions, dependency installation, test paths, pytest options, timeouts, and soft-fail behavior.
  • Preserves dependency constraints and installed-package details as workflow artifacts.
  • Identifies the selected OVOS channel during test runs.

• Documentation

  • Added workflow usage instructions, configuration details, expected baseline failures, and example caller matrices.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: c5161b5a-9eba-4561-89bf-682a1b98204a

📥 Commits

Reviewing files that changed from the base of the PR and between 82252c3 and f0cabe6.

📒 Files selected for processing (3)

• .github/workflows/channel-compat.yml
• README.md
• docs/workflow-reference.md

---

📝 Walkthrough

Walkthrough

Changes

Channel compatibility testing

Layer / File(s)	Summary
Workflow contract and environment setup .github/workflows/channel-compat.yml	The reusable workflow accepts channel, runner, Python, dependency, pytest, timeout, and failure-handling inputs. It prepares the runner and fetches live channel constraints.
Constraint filtering and package installation .github/workflows/channel-compat.yml	The workflow detects the repository package, removes its constraint, and installs the repository and test dependencies under the selected channel constraints.
Test execution, artifacts, and usage documentation .github/workflows/channel-compat.yml, README.md, docs/workflow-reference.md	The workflow records constraints and the installed stack, uploads artifacts, sets OVOS_CHANNEL, and runs pytest. The documentation describes configuration and matrix usage.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant channel-compat.yml
  participant OVOSChannel
  participant PythonEnvironment
  participant Pytest
  Caller->>channel-compat.yml: Invoke workflow with channel inputs
  channel-compat.yml->>OVOSChannel: Fetch live constraints
  OVOSChannel-->>channel-compat.yml: Return constraints and channel name
  channel-compat.yml->>PythonEnvironment: Remove repository constraint and install packages
  PythonEnvironment-->>channel-compat.yml: Return installed stack
  channel-compat.yml->>Pytest: Run tests with OVOS_CHANNEL
  Pytest-->>Caller: Return test result

Loading

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ci/channel-compat

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}