gh-automations

August 1, 2026 · View on GitHub

Reusable GitHub Actions workflows and Python scripts for the OpenVoiceOS ecosystem.

Used by 209 repos across the OVOS project. See docs/repos.md for the full list.

Reusable Workflows

All workflows live in .github/workflows/ and are called from other repos via:

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

Workflow	Purpose	Docs
`publish-alpha.yml`	Bump version, publish alpha to PyPI, open release PR	reference
`publish-stable.yml`	Remove alpha flag, publish stable to PyPI, tag release	reference
`build-tests.yml`	Build/install/test matrix across Python versions; channel compatibility	reference
`channel-compat.yml`	Run a repo's tests against an OVOS distro release channel (stable/testing constraints)	reference
`opm-check.yml`	OPM plugin detection, interface validation, import timing	reference
`coverage.yml`	Run pytest with coverage; post diff report to PR comment	reference
`coverage-pages.yml`	Run tests with coverage; deploy HTML report to GitHub Pages	reference
`license-check.yml`	Check all dependency licenses for copyleft violations	reference
`pip-audit.yml`	Scan dependencies for known CVEs; optional SARIF upload	reference
`release-preview.yml`	Predict next version from PR labels/title	reference
`repo-health.yml`	Required files check, version block validation, first-time contributor greeting	reference
`skill-check.yml`	Locale coverage and skill.json validity	reference
`spec-lint.yml`	Validate `locale/` against OVOS-INTENT-1/-2 via `ovos-spec-lint`	reference
`locale-check.yml`	Verify locale folder is included in package build (pyproject.toml + SOURCES.txt)	reference
`ovoscope.yml`	End-to-end skill tests with auto-install of pipeline plugins	reference
`downstream-check.yml`	Report which packages depend on a given package	reference
`python-support.yml`	Install matrix (regular + editable) per Python version (legacy — REMOVE AFTER 2027-01-01)	reference
`notify-matrix.yml`	Send a message to the OVOS Matrix channel	reference
`type-check.yml`	Run mypy; post 🔎 Type Check section to PR comment	reference
`docs-check.yml`	Verify required docs files exist; optional markdownlint	reference

Quick Start

See docs/repo-setup.md for the complete guide to setting up a new OVOS repo.

The minimum required files for a new package:

.github/workflows/
  conventional-label.yaml   # auto-label PRs by commit type
  release_workflow.yml       # alpha release on PR merge to dev
  publish_stable.yml         # stable release on PR merge to master
  license_tests.yml          # license compliance check
  build_tests.yml            # build/install/test matrix (build-tests.yml)
  repo_health.yml            # required-files check + contributor greeting
  release_preview.yml        # next-version prediction on every PR

For OVOS plugin repos, also add:

.github/workflows/
  opm_check.yml              # OPM plugin detection + interface validation

For OVOS skill repos, also add:

.github/workflows/
  skill_check.yml            # locale coverage + skill.json validity

Release Flow

See docs/release-flow.md for the full lifecycle diagram.

PR merged to dev
    └─► publish-alpha.yml
            ├─ Bump version in version.py
            ├─ Publish alpha to PyPI
            └─ Open release PR to master

PR merged to master (after human review)
    └─► publish-stable.yml
            ├─ Remove alpha suffix
            ├─ Tag GitHub release
            └─ Sync master → dev

Python Scripts

Scripts in scripts/ are checked out by the reusable workflows at run time:

Script	Purpose
`_version_utils.py`	Shared parsing: `read_version`, `format_version`, `write_version_block`
`update_version.py`	Bump version in `version.py` (major/minor/build/alpha)
`remove_alpha.py`	Set `VERSION_ALPHA = 0` (declare stable)
`get_version.py`	Read and print version string from `version.py`
`check_downstream.py`	Report downstream dependents via pipdeptree
`update_pr_comment.py`	Manage the shared OVOS PR Checks comment (find-or-create, section replace)
`check_skill.py`	Analyse skill locale structure, skill.json, and translation coverage
`check_locale_build.py`	Verify locale folder is included in package build (pyproject.toml + SOURCES.txt)
`check_release.py`	Predict next version from PR labels/title using conventional commit rules
`check_opm.py`	Detect OVOS plugins via OPM, validate interface, measure import time

Note: The reusable workflows check out this repo at runtime pinned to ref: dev.

Bot Safety

All workflows include guards against accidental bot-triggered runs:

publish-alpha.yml — bump_version job only runs when github.event.pull_request.merged == true or workflow_dispatch
publish-stable.yml — bump_version job skips when github.actor == 'github-actions[bot]' (prevents infinite loop when the version commit triggers another push event)
release_workflow.yml (per-repo) — supports workflow_dispatch for manual reruns

Documentation

File	Contents
docs/index.md	High-level overview and navigation
docs/release-flow.md	Full release lifecycle, versioning rules, channel overview
docs/workflow-reference.md	All inputs, outputs, and jobs for each reusable workflow
docs/repo-setup.md	Step-by-step setup guide for new repos
docs/repos.md	All repos currently using these automations
docs/maintenance.md	Open technical debt and opportunistic rollouts

New Maintainer Checklist

If you have just inherited or taken ownership of this repo, complete these steps:

Day 1 — Get oriented

Read docs/index.md — workflow overview, scripts reference, and cross-references.
Read docs/maintenance.md — open technical debt and opportunistic rollouts.

Run the test suite to confirm nothing is broken:

cd gh-automations
pip install pytest pyyaml
pytest test/ -v

Check docs/repos.md — many repos depend on this library. Understand the caller blast radius before any change.

Before making changes

Check dev vs master semantics: dev is active development; master is the frozen v1 stable baseline. All PRs target dev.
Test locally before pushing: the test suite covers every Python script. Add tests for any new scripts.
Never force-push master — caller repos use @master or @dev refs; a rewrite would break them.
Do not commit root-level *.md files. Planning, audit, FAQ, and session-log files belong in docs/ or in chat — not at the repo root. README.md is the only allowed root-level Markdown file.

After making changes

Run pytest test/ -v — must be green before committing.
Review docs/workflow-reference.md — if inputs/outputs changed, update the reference.

Deprecated workflows

Two workflows are deprecated and scheduled for removal on 2027-01-01:

coverage-pages.yml → migrate callers to coverage.yml with deploy_pages: true
python-support.yml → migrate callers to build-tests.yml

Before removing either, check docs/repos.md for active callers.

Credits

Developed by TigreGótico for OpenVoiceOS.

This project was funded through the NGI0 Commons Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement No 101135429.