gh-automations¶

In a nutshell

gh-automations is a shared toolbox of ready-made automation recipes that every OVOS code project can borrow, instead of each one writing its own. These recipes handle the repetitive chores around publishing software: running tests, checking licences, bumping version numbers, and pushing releases out. The recipe lives in one place, so fixing or improving it once updates every project that uses it. This is a developer/maintainer reference. See the Workflow Reference for the full list, or the Glossary.

gh-automations (hosted at OpenVoiceOS/gh-automations) is the shared GitHub Actions automation library for OpenVoiceOS repositories.

What it does, in plain terms¶

Instead of every OVOS repo copy-pasting its own CI/CD YAML, this repo holds a set of reusable workflows. Your repo's workflow file is just a few lines that call one of these. GitHub runs the shared definition with your inputs. Update the shared workflow once, and every repo that references it gets the change.

The workflows cover two jobs:

Release automation: bump the version on PR merge to dev, publish an alpha to PyPI, and open a release PR to master. On merge, declare the version stable and tag it. See Release Flow.
PR checks: build/install/test, plugin detection, license/CVE scanning, coverage, linting, version preview, and more. Most of these post their result as a section in a single shared OVOS PR Checks comment on the PR.

How to wire one into your repo¶

Add a workflow file under .github/workflows/ in your repo that calls the reusable one. The uses: ref is always @dev (never a pinned tag or SHA):

# .github/workflows/build_tests.yml
name: Run Build Tests
on:
  pull_request:
    branches: [dev]
  workflow_dispatch:

jobs:
  build_tests:
    uses: OpenVoiceOS/gh-automations/.github/workflows/build-tests.yml@dev
    secrets: inherit
    with:
      install_extras: 'test'
      test_path: 'test/'

secrets: inherit passes your repo's secrets (e.g. GITHUB_TOKEN, and PYPI_TOKEN/MATRIX_TOKEN for the publish workflows) through to the called workflow. See Workflow Reference for every input.

install_extras accepts any spelling

Every reusable workflow that takes install_extras accepts a bare extras name ('test'), a bracketed list ('[dev,test]'), a full install target ('.[dev]'), or raw pip arguments ('-r requirements/test.txt'), normalizing internally (OpenVoiceOS/gh-automations#88). Use whichever spelling reads clearest; the per-workflow input tables below and on the linked reference pages may still show one particular spelling in their example, but any of the four forms works.

Scripts checkout¶

Several reusable workflows check this repo out again at runtime to reach scripts/ (the PR-comment helper, version utilities, etc.), pinned to ref: dev. You do not write this yourself: it lives inside the reusable workflow.

What the reusable workflow does internally

- uses: actions/checkout@v7
  with:
    repository: OpenVoiceOS/gh-automations
    ref: dev
    path: _gh_automations/

Worked example: wiring build-tests + publish-alpha + publish-stable together¶

A typical repo runs build-tests.yml as a PR gate, publish-alpha.yml when a PR merges to dev, and publish-stable.yml when the resulting release PR merges to master:

Worked example: full workflow files

# .github/workflows/build_tests.yml - gate every PR into dev
name: Run Build Tests
on:
  pull_request:
    branches: [dev]
jobs:
  build_tests:
    uses: OpenVoiceOS/gh-automations/.github/workflows/build-tests.yml@dev
    secrets: inherit
    with:
      install_extras: 'test'
      test_path: 'test/'

# .github/workflows/publish_alpha.yml - bump + publish an alpha on merge to dev
name: Publish Alpha Build
on:
  pull_request:
    types: [closed]
    branches: [dev]
jobs:
  publish_alpha:
    if: github.event.pull_request.merged == true
    uses: OpenVoiceOS/gh-automations/.github/workflows/publish-alpha.yml@dev
    secrets: inherit
    with:
      publish_pypi: true
      update_changelog: true

# .github/workflows/publish_stable.yml - declare stable + publish on push to master
name: Publish Stable Build
on:
  push:
    branches: [master]
jobs:
  publish_stable:
    uses: OpenVoiceOS/gh-automations/.github/workflows/publish-stable.yml@dev
    secrets: inherit
    with:
      publish_pypi: true
      sync_dev: true

The three form a pipeline. build-tests must pass before a PR can merge to dev. publish-alpha then bumps the version, tags a pre-release, publishes it to PyPI, and opens the release PR to master.

Merging that PR triggers publish-stable, which drops the alpha suffix, tags the stable release, and publishes it. With sync_dev: true, it also pushes master back into dev so both branches stay aligned. secrets: inherit is required on every call so PYPI_TOKEN reaches the reusable workflow. See Release Flow for the full diagram of this same pipeline.

Reusable Workflows¶

Every reusable workflow lives in .github/workflows/ and is called as:

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

The filename below is the actual file in this repo (the <name>.yml). The name of the wrapper workflow in your own repo is up to you.

Each table below names the PR-comment section a workflow posts. The bot prefixes every section title with an emoji marker; the tables give the title text only.

Release¶

Workflow	Purpose
`publish-alpha.yml`	On PR merge to `dev`: bump version, optionally update changelog / tag pre-release / publish alpha to PyPI / notify Matrix, and open a release PR to `master`. PyPI publish and Matrix notify are jobs inside this workflow, gated by `publish_pypi` / `notify_matrix`.
`publish-stable.yml`	On push to `master`: remove the alpha suffix, tag the stable release, optionally publish to PyPI, notify Matrix, and sync `master` → `dev`.
`release-preview.yml`	Predict the next version from PR labels/title. Post a `Release Preview` section.

Build & test¶

Workflow	Purpose
`build-tests.yml`	Build/install/test matrix across Python versions. Posts `Build Tests`.
`channel-compat.yml`	Run the test suite at the versions an OVOS distro release channel pins, to catch what is green on `dev` but broken on the fleet. Posts `Channel Compat`.
`coverage.yml`	Run pytest with coverage. Post `Coverage`. Optionally deploy the HTML report to Pages (`deploy_pages: true`).
`ovoscope.yml`	Run ovoscope end-to-end skill tests. Post `Skill Tests (ovoscope)`.
`intent-case-tests.yml`	Run the file-based ovoscope intent-routing accuracy matrix (sharded by language). Post `Intent-Case Accuracy`.
`tts-intelligibility.yml`	Synthesise speech, transcribe it back with reference STT, and score WER/CER. Post `TTS Intelligibility`.
`opm-check.yml`	OPM (OVOS Plugin Manager) plugin detection, interface validation, and import timing. Post `Plugin Detection`.

Quality & policy¶

Workflow	Purpose
`license-check.yml`	Scan dependencies for copyleft/incompatible licenses (universal-donor policy). Post `License Check`.
`pip-audit.yml`	Scan installed dependencies for CVEs, with optional SARIF upload. Post `Security (pip-audit)`.
`lint.yml`	Run ruff and/or pre-commit. Post lint results.
`type-check.yml`	Run mypy. Post `Type Check` (informational unless `fail_on_errors: true`).
`docs-check.yml`	Verify required docs files exist, with optional markdownlint. Post `Docs`.
`repo-health.yml`	Check required files and the version block, and greet first-time contributors. Post `Repo Health`.

Skills¶

Workflow	Purpose
`skill-check.yml`	Locale structure, language coverage, `skill.json` validity. Post `Skill`.
`locale-check.yml`	Verify locale folders are correctly included in the package build.
`spec-lint.yml`	Run `ovos-spec-lint` against a skill's locale folder (OVOS-INTENT-1 / OVOS-INTENT-2). Also invoked automatically from `skill-check.yml` (input `spec_lint`, default `true`), which is how it reaches every `ovos-skill-*` repo without per-repo caller changes; set `spec_lint: false` there to opt a repo out.

Notifications & dependency tracking¶

Workflow	Purpose
`downstream-check.yml`	Report which packages in the alpha constraints depend on a given package.
`notify-matrix.yml`	Send a message to the OVOS Matrix channel (the publish workflows duplicate this logic inline rather than calling it).

Deprecated (kept for backward compatibility, remove after 2027-01-01)¶

Workflow	Replacement
`python-support.yml`	`build-tests.yml` (multi-version build/install/test).
`coverage-pages.yml`	`coverage.yml` with `deploy_pages: true`.

Full input/output/job reference: Workflow Reference

Python Scripts¶

Located in scripts/. Checked out by the reusable workflows at run time, not installed as a package.

Script	Key function	Purpose
`_version_utils.py`	`read_version` / `format_version` / `write_version_block`	Parse, format, and rewrite the `version.py` block. Shared by all version scripts
`update_version.py`	`update_version(part, version_file)`	Bump `VERSION_MAJOR/MINOR/BUILD/ALPHA` in `version.py`
`remove_alpha.py`	`update_alpha(version_file)`	Set `VERSION_ALPHA = 0` (declare stable)
`get_version.py`	`get_version(version_file)`	Read and print current version string
`check_downstream.py`	`get_downstream(package_name)`	Report reverse dependencies using `pipdeptree`
`update_pr_comment.py`	`find_ovos_comments` / `insert_or_replace_section`	Find-or-create and update sections of the shared OVOS PR Checks comment
`check_skill.py`	`run_checks(repo_root, ...)`	Skill locale / `skill.json` analysis
`check_release.py`	`run_checks(version_file, ...)`	Predict next version from PR labels/title
`check_opm.py`	`check_opm(plugin_type, entry_point, ...)`	OPM plugin detection, interface validation, import timing
`check_locale_build.py`	`find_locale_dirs(repo_root)`	Verify locale folders are included in the package build (backs `locale-check.yml`)
`check_repo_health.py`	`check_required_files(repo_root, ...)`	Repository health: required files, contributor status, breaking changes (backs `repo-health.yml`)
`format_tts_intel.py`	`_parse_marker` + report formatter	Format a TTS-intelligibility pytest json-report into a markdown table (backs `tts-intelligibility.yml`)
`check_release_channels.py`	`normalize_package_name` + channel check	Check a predicted version against the ovos-releases channel constraints (backs `release-preview.yml`)
`aggregate_python_results.py`	`main()`	Aggregate Python version compatibility results across matrix jobs (backs `python-support.yml`)

All version scripts share the version.py block format:

# START_VERSION_BLOCK
VERSION_MAJOR = 1
VERSION_MINOR = 2
VERSION_BUILD = 3
VERSION_ALPHA = 4   # 0 = stable

# END_VERSION_BLOCK

Documentation¶

Release Flow: full lifecycle from alpha to stable to release channels
Workflow Reference: every input, output, job, and bot guard for each reusable workflow

Repo	Role
ovos-releases	Holds `constraints-alpha/testing/stable.txt`, updated after stable releases. The channel-compatibility check and `downstream-check.yml` read these files.
raspOVOS	Uses a `constraints-*.txt` URL as the `CONSTRAINTS` env var during image builds.

Read next: Workflow Reference Related: Release Flow · PR Workflows · Quality Workflows · Release Workflows