gh-automations

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
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
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
sync-translations.yml	Sync gitlocalize-app[bot] translation commits	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
  sync_translations.yml      # gitlocalize translation sync

---

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
FAQ.md	Common questions and answers
QUICK_FACTS.md	Machine-readable facts for RAG retrieval
AUDIT.md	Known issues, technical debt, security risks
SUGGESTIONS.md	Proposed improvements

---

New Maintainer Checklist

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

Day 1 — Get oriented

1. Read docs/index.md — 20-workflow overview, scripts reference, and cross-references.
2. Read QUICK_FACTS.md — Machine-readable summary: all scripts with line citations, all PR comment section IDs, required secrets.
3. Read AUDIT.md — Known issues and technical debt with severity labels. Resolve any High items first.
4. Run the test suite to confirm nothing is broken:

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

5. Check docs/repos.md — 209 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.
• Check SUGGESTIONS.md for prior proposals — do not re-invent solutions already evaluated.
• Test locally before pushing: the test suite covers all 13 Python scripts. Add tests for any new scripts.
• Never force-push master — 209 repos use @master or @dev refs; a rewrite would break them.

After making changes

1. Update FAQ.md first — highest priority per AGENTS.md.
2. Update MAINTENANCE_REPORT.md with the session log and AI model used.
3. Update AUDIT.md and SUGGESTIONS.md if issues were found or resolved.
4. Run pytest test/ -v — must be green before committing.
5. 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.