Reusable Workflow Reference: Build Checks

In a nutshell

This page documents the shared workflows that verify a package builds, installs, and still runs where it has to: build-tests.yml across Python versions, channel-compat.yml against an OVOS distro release channel, and the deprecated python-support.yml. For OVOS-plugin (OPM) detection, license, and repo-health checks, see Plugin, License, and Repo Checks. For skill and locale packaging checks, see Skill and Locale Checks. For end-to-end skill test execution, see Skill Test Workflows. Start with the gh-automations overview for the big picture, or the full Workflow Reference index.

All reusable workflows are in .github/workflows/ and are called via:

uses: OpenVoiceOS/gh-automations/.github/workflows/<name>.yml@dev

Ref: Always use @dev.

Workflows on this page:

• build-tests.yml
• channel-compat.yml
• python-support.yml (deprecated)

---

build-tests.yml

Runs build, install, and optionally tests across a configurable matrix of Python versions. Posts a 🔨 Build Tests section to the PR comment. To run those tests against a release channel instead of current dev, see channel-compat.yml below.

Source: .github/workflows/build-tests.yml

Inputs

Input	Type	Default	Description
uv_prerelease	string	allow	uv prerelease resolution mode (allow | if-necessary | explicit | disallow). Defaults to "allow": the OVOS ecosystem ships pre-1.0 alphas and relies on prerelease floor-pins resolving the way pip did.
runner	string	ubuntu-latest	Runner label
python_versions	string	["3.10", "3.11", "3.12", "3.13", "3.14"]	JSON array of Python versions to test against
system_deps	string	""	Extra apt packages to install before building (space-separated)
install_extras	string	""	Extra dependencies applied when installing the built wheel. Accepts a bare extras name ('test'), a bracketed list ('[dev,test]'), a full target ('.[test]'), or raw pip arguments ('-r requirements/test.txt').
pre_install_pip	string	""	Optional space-separated pip requirement specs to install BEFORE the package build/install step. Use this to override transitive deps with git URLs (e.g. for testing against an unreleased version of a sibling package). Each whitespace-separated item is passed as a single argument to pip install, so quoted git URLs are supported.
test_path	string	""	If set, run pytest against this path after installing the package. Leave empty to skip test execution (build/install verification only).
pytest_args	string	""	Extra arguments appended to the pytest invocation, e.g. '--capture=tee-sys' to keep a crashing test's output visible when pytest's default fd-level capture would otherwise swallow it (native crashes, SIGABRT). Same name and meaning as on channel-compat.yml. Empty by default: no change to the command line.
test_env	string	""	Extra environment variables for the test step, as newline-separated KEY=value pairs, e.g. 'PYTHONFAULTHANDLER=1\nRUST_BACKTRACE=full' to get a traceback/panic message out of a native crash instead of just "Fatal Python error: Aborted". Appended to $GITHUB_ENV before the Run Tests step. Empty by default: no vars are added.
pr_comment	boolean	true	Post a '🔨 Build Tests' section in the OVOS PR Checks comment. Only runs on pull_request events.

Jobs

Job	Description
build_tests	Matrix job. Runs uv build, installs the resulting wheel (with extras if specified), optionally runs pytest. Saves per-version result as an artifact.
post_build_report	Runs after the matrix, only on PR events with pr_comment: true. Downloads all result artifacts, formats and posts the section:build PR comment.

Typical usage

name: Run Build Tests
on:
  push:
    branches: [master]
  pull_request:
    branches: [dev]
  workflow_dispatch:

jobs:
  build_tests:
    uses: OpenVoiceOS/gh-automations/.github/workflows/build-tests.yml@dev
    secrets: inherit
    with:
      python_versions: '["3.10", "3.11", "3.12"]'
      install_extras: 'test'
      test_path: 'test/'

Notes

• OPM (plugin detection) inputs were removed from this workflow. Use opm-check.yml for OPM validation.

• The matrix uses fail-fast: false so all versions are tested even if one fails.

---

channel-compat.yml

Runs the repo's test suite against an OVOS distro release channel: every dependency is installed at the version that channel pins, and only the repo under test comes from the checkout. Posts a 📡 Channel Compat section (one per channel) to the PR comment.

Source: .github/workflows/channel-compat.yml

Inputs

Input	Type	Default	Description
channel_url	string	(required)	Raw URL of the OVOS distro constraints file for the channel under test, e.g. https://raw.githubusercontent.com/OpenVoiceOS/OpenVoiceOS/main/constraints-stable.txt
channel_name	string	""	Short label for the channel, used in job output and artifact names. Defaults to the constraints filename with the 'constraints-' prefix and '.txt' suffix removed (so 'stable' or 'testing').
runner	string	ubuntu-latest	Runner label
test_path	string	test/	Path passed to pytest.
python_version	string	3.11	Python version to use.
system_deps	string	""	Extra apt packages to install before testing (space-separated). Extra apt packages, if the tested tree needs any.
pre_install_pip	string	""	Optional space-separated pip requirement specs installed BEFORE the repo under test, under the channel constraints. Use for test-only siblings the channel does not name. Named to match the same input on build-tests.yml and ovoscope.yml.
install_extras	string	test	Extra dependencies used when installing the repo under test. Accepts a bare extras name ('test'), a bracketed list ('[dev,test]'), a full target ('.[test]'), or raw pip arguments ('-r requirements/test.txt'). Set to '' to install the package with no extras.
pytest_args	string	-v --tb=short -rxX	Extra arguments appended to the pytest invocation.
pr_comment	boolean	true	Post a '📡 Channel Compat' section (one per channel) in the OVOS PR Checks comment. Only runs on pull_request events.
soft_fail	boolean	false	Report the run but do not fail the job when tests fail. GitHub does not allow continue-on-error on a job that calls a reusable workflow, so callers that want an advisory gate set this instead. Use it while a repo's channel baseline is still being established, then turn it off.
timeout_minutes	number	45	Job timeout.

The one rule

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

Expect red on the first run

A repo's first channel run usually fails a pile of tests. That is the finding, not a broken job. Call it with soft_fail: true until the baseline is understood, then turn it off. soft_fail exists because GitHub does not allow continue-on-error on a job that calls a reusable workflow.

An install that cannot resolve at all is also a finding: it means the repo's own dependency floors have outgrown the channel. The job reports that as a warning in the step summary rather than a test failure.

ovos-test-harness carries the worked example, including checked-in per-channel known-gap files (test/channel_gaps/) that keep known failures green while new breakage stays red. Suites that keep such a baseline read the channel name from the OVOS_CHANNEL environment variable, which the workflow sets.

Usage

name: Channel Compat
on:
  pull_request:
    branches: [dev]

jobs:
  stable:
    uses: OpenVoiceOS/gh-automations/.github/workflows/channel-compat.yml@dev
    with:
      channel_url: https://raw.githubusercontent.com/OpenVoiceOS/OpenVoiceOS/main/constraints-stable.txt
      soft_fail: true
  testing:
    uses: OpenVoiceOS/gh-automations/.github/workflows/channel-compat.yml@dev
    with:
      channel_url: https://raw.githubusercontent.com/OpenVoiceOS/OpenVoiceOS/main/constraints-testing.txt

Call it once per channel. channel_name defaults to the constraints filename with the constraints- prefix and .txt suffix removed, so the two jobs above label themselves stable and testing on their own.

---

python-support.yml (deprecated)

Deprecated, use build-tests.yml instead (and opm-check.yml for OPM detection). Kept for backward compatibility. Scheduled for removal after 2027-01-01. New repos should not adopt it.

Runs an install matrix across Python versions and install modes (regular + editable). Optionally checks OPM detection using a legacy entry_point ID. Posts a 🐍 Python Support section to the PR comment.

Source: .github/workflows/python-support.yml

Inputs

Input	Type	Default	Description
uv_prerelease	string	allow	uv prerelease resolution mode (allow | if-necessary | explicit | disallow). Defaults to "allow": the OVOS ecosystem ships pre-1.0 alphas and relies on prerelease floor-pins resolving the way pip did.
runner	string	ubuntu-latest	Runner label
package_name	string	""	Package name (for OPM verification). If empty, attempt to read from setup.py/pyproject.toml.
python_versions	string	["3.10", "3.11", "3.12", "3.13", "3.14"]	JSON array of Python versions to check
version_file	string	""	Path to version.py (relative to repo root). If empty, auto-detects.
install_modes	string	["regular", "editable"]	JSON array of install modes ('regular', 'editable')
install_extras	string	""	Extra dependencies to install. Accepts a bare extras name ('dev'), a bracketed list ('[dev,rl]'), a full target ('.[dev]'), or raw pip arguments ('-r requirements/test.txt').
system_deps	string	""	Extra apt packages beyond python3-dev and libssl-dev
entry_point	string	""	The expected skill entry point ID to verify with OPM
pr_comment	boolean	true	Post/update the '🐍 Python Support' section in the PR comment

---

Read next: Plugin, License, and Repo Checks Related: gh-automations Overview · Skill and Locale Checks · Skill Test Workflows · Workflow Reference