Reusable Workflow Reference: Plugin, License, and Repo Checks¶

In a nutshell

This page documents the shared workflows that verify a package is a valid OVOS plugin and keeps its repo in good order: opm-check.yml, license-check.yml, and repo-health.yml. For the build-matrix checks, see Build 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:

opm-check.yml
license-check.yml
repo-health.yml

`opm-check.yml`¶

Runs OPM (OVOS Plugin Manager) plugin detection and validation on a single Python version. Verifies the plugin is discoverable after wheel install, and optionally after editable install (to catch entry-point registration issues). Posts a 🔌 Plugin Detection section to the PR comment.

Source: .github/workflows/opm-check.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_version`	string	`3.11`	Python version to use for OPM checks
`system_deps`	string	`""`	Extra apt packages to install before building (space-separated)
`install_extras`	string	`""`	Extra dependencies to install. Accepts a bare extras name ('dev'), a bracketed list ('[dev,test]'), a full target ('.[dev]'), or raw pip arguments ('-r requirements/test.txt').
`plugin_type`	string	`auto`	Plugin type (auto, skill, tts, stt, wake_word, vad, phal, pipeline, utterance_transformer, tts_transformer)
`entry_point`	string	`""`	Legacy: a single entry point ID to verify. For packages that ship multiple OPM plugins from one wheel, prefer `entry_points` (plural) or leave both empty — auto-detection enumerates every `opm.*` entry point declared in pyproject.toml.
`entry_points`	string	`""`	JSON array of entry point IDs to verify, e.g. '["foo", "bar"]'. When set, runs the OPM check once per entry point and aggregates results into the PR comment. Takes precedence over `entry_point`.
`opm_require_found`	boolean	`true`	Fail if OPM cannot discover the plugin
`opm_validate_interface`	boolean	`true`	Check that plugin class inherits from the correct abstract base
`opm_test_import`	boolean	`true`	Test that the plugin class is importable, measure import time
`opm_perf_threshold_ms`	number	`500`	Import time above this (ms) is treated as an error
`pr_comment`	boolean	`true`	Post a '🔌 Plugin Detection' section in the OVOS PR Checks comment. Only runs on pull_request events.
`opm_min_version`	string	`""`	Minimum ovos-plugin-manager version to install, e.g. '2.2.3a1'. Leave empty for latest stable.
`opm_max_version`	string	`""`	Maximum ovos-plugin-manager version (exclusive upper bound), e.g. '3.0.0'. Leave empty for no upper bound.

Jobs¶

Job Description

opm_check Installs ovos-plugin-manager, builds the wheel, installs it, then runs check_opm.py with --validate-interface/--test-import flags as configured. If the package is confirmed as an OVOS plugin, it re-installs in editable mode and runs a detection-only check (no interface validation, no import test). This catches entry-point registration differences. Uploads opm_result.json and opm_result_editable.json as artifacts.

post_opm_report Downloads the JSON artifacts and formats a PR comment section with status, plugin metadata, system deps, and detected types. The section includes a validation table (wheel vs editable, import time, interface, config docs) and an issues list. It also calls check_downstream.py to count dependents and appends the downstream impact note if count > 0.

PR comment content¶

The report is split into two tables:

OPM Detection, one row per plugin type (e.g. skill, tts):

✅ Plugin Status: PASS

Plugin Info:

- Name: ovos-tts-plugin-example


- Version: 1.2.3a4


- Description: Example TTS plugin for OVOS


- Requires Python: >=3.10

OPM Detection:

| Type | Wheel OPM | Editable OPM | Requires Python |
|------|-----------|--------------|-----------------|
| tts  | ✅        | ✅           | ✅ >=3.10       |

Entry Point Validation, one row per named entry point (supports packages that register multiple entry points per type, e.g. a multi-voice TTS):

Entry Point Validation:

| Entry Point | Import | Interface | Config Docs |
|-------------|--------|-----------|-------------|
| ovos-tts-plugin-example | ✅ 42ms | ✅ | ✅ |
| ovos-tts-plugin-example-neural | ✅ 38ms | ✅ | ✅ |

🔗 Downstream Impact: 3 package(s) depend on this plugin

Non-plugin repos: ℹ️ Not an OVOS plugin, OPM check skipped.

Typical usage¶

name: OPM Check
on:
  pull_request:
    branches: [dev]
  workflow_dispatch:

jobs:
  opm_check:
    uses: OpenVoiceOS/gh-automations/.github/workflows/opm-check.yml@dev
    secrets: inherit
    with:
      plugin_type: auto
      opm_require_found: true
      opm_perf_threshold_ms: 500

Notes¶

opm_require_found: true (default) means the job fails if OPM cannot find the plugin. Set opm_require_found: false for repos that may not be OVOS plugins (e.g. utility libraries) where the check should pass silently.
The editable OPM check runs only when the wheel check confirms is_ovos_plugin: true in the JSON output, avoiding unnecessary editable install for non-plugin repos.
plugin_type: auto reads [project.entry-points."opm.*"] sections from pyproject.toml (or equivalent in setup.py) to detect all plugin types the package declares.
Entry point validation is keyed by ep_name (the entry point identifier), not by short_type. A package registering two TTS voices under different entry point names gets both validated independently.
requires-python from pyproject.toml is checked against the running Python version. A mismatch is reported as an error in the issues list.

`license-check.yml`¶

Checks all installed dependencies for licenses incompatible with the OVOS universal donor policy (Apache 2.0). Uses pilosus/action-pip-license-checker@v3. Also runs pip-licenses to generate a full per-package breakdown shown in a collapsible table in the PR comment.

Source: .github/workflows/license-check.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`
`python_version`	string	`3.14`
`install_extras`	string	`""`	Extra dependencies to install. Accepts a bare extras name ('dev'), a bracketed list ('[dev,linux]'), a full target ('.[dev]'), or raw pip arguments ('-r requirements/test.txt').
`system_deps`	string	`""`	Extra apt packages beyond python3-dev and libssl-dev
`exclude_packages`	string	`""`	PCRE regex of repo-specific package names to exclude, unioned with the central whitelist (docs/license-whitelist.md) and the package under test (auto-derived from pyproject.toml/setup.py). Leave empty to use the central whitelist plus self-exclusion only. Example: '^my-internal-pkg$'.
`exclude_licenses`	string	`^Mozilla Public License.*`	PCRE regex of license identifiers to exclude. Default allows MPL (file-level copyleft, safe as library).
`fail_licenses`	string	`StrongCopyleft,NetworkCopyleft,WeakCopyleft,Other,Error`	Comma-separated license categories that cause the check to fail. Valid values: StrongCopyleft, NetworkCopyleft, WeakCopyleft, Copyleft (all three), Permissive, Other, Error. Default enforces the OVOS universal donor policy (Apache 2.0).
`warn_only`	boolean	`false`	When true, report license violations in the PR comment but do NOT fail the job. Useful for repos in transition or where a violation needs review before fixing.
`pr_comment`	boolean	`true`	Post a section in the shared 'OVOS PR Checks' comment on the PR. Only runs when the workflow is triggered by a pull_request event.

PR comment content¶

The comment includes:

Status header (pass/fail + package count)
Violations report (if any) in a code block
License distribution summary (e.g. 42× MIT, 18× Apache Software License, ...)
Full per-package breakdown in a collapsible <details> table with columns: Package, Version, License, URL. Packages with violations are flagged with a warning marker.
Policy footnote

Typical usage¶

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

jobs:
  license_tests:
    uses: OpenVoiceOS/gh-automations/.github/workflows/license-check.yml@dev
    with:
      install_extras: '[extras]'
      system_deps: ''
      exclude_packages: '^(tqdm|some-gpl-package).*'

`repo-health.yml`¶

Checks that a repo contains the required files (README, LICENSE, pyproject.toml/setup.py, version.py with valid block markers) and greets first-time contributors.

Source: .github/workflows/repo-health.yml

Inputs¶

Input	Type	Default	Description
`runner`	string	`ubuntu-latest`
`version_file`	string	`""`	Path to version.py (relative to repo root). If empty, auto-detects root or pkg/version.py.
`pr_comment`	boolean	`true`	Post sections in the shared 'OVOS PR Checks' comment. Only runs when triggered by a pull_request event.

PR comment content¶

Current version from version.py
Per-file status: yes for present, no for required and missing, partial for optional and missing
Version block marker validation (START/END_VERSION_BLOCK)
First-time contributor greeting (separate 👋 Welcome section posted in the same PR comment when author_association is FIRST_TIME_CONTRIBUTOR or FIRST_TIMER)

Typical usage¶

name: Repo Health
on:
  pull_request:
    branches: [dev]
  workflow_dispatch:

jobs:
  repo_health:
    uses: OpenVoiceOS/gh-automations/.github/workflows/repo-health.yml@dev
    secrets: inherit
    with:
      version_file: 'my_package/version.py'

Reusable Workflow Reference: Plugin, License, and Repo Checks¶

opm-check.yml¶

Inputs¶

Jobs¶

PR comment content¶

Typical usage¶

Notes¶

license-check.yml¶

Inputs¶

PR comment content¶

Typical usage¶

repo-health.yml¶

Inputs¶

PR comment content¶

Typical usage¶

`opm-check.yml`¶

`license-check.yml`¶

`repo-health.yml`¶