Reusable Workflow Reference: Coverage and Security Workflows¶

In a nutshell

This page documents the shared workflows for test coverage and dependency security: coverage.yml, the deprecated coverage-pages.yml, pip-audit.yml, and downstream-check.yml. For lint, type-checking, docs presence, and Matrix notifications, see Lint and Docs Workflows. For the PR-comment aggregation pattern and the shared Python scripts, see PR Comment Pattern and Scripts. 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:

coverage.yml
coverage-pages.yml (deprecated)
pip-audit.yml
downstream-check.yml

`coverage.yml`¶

Runs pytest --cov, generates a coverage report, and posts it to the job summary. Uploads the XML as an artifact, and (on pull requests) posts a Coverage section in the shared OVOS PR Checks comment. Set deploy_pages: true to also push the HTML report to a gh-pages branch. This replaces the deprecated coverage-pages.yml.

Source: .github/workflows/coverage.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.11`
`system_deps`	string	`""`	Extra apt packages to install before testing (space-separated)
`test_extras`	string	`dev`	Name of the pyproject.toml extras key that declares the package's test dependencies (e.g. 'dev' or 'test'). Tried first via 'pip install -e .[]'. Override per repo if the package uses a different convention.
`test_extras_fallback`	string	`test`	Extras key tried if `test_extras` is not declared. Default 'test'. Set to empty to skip the fallback.
`install_extras`	string	`""`	Extra dependencies to install before tests. Accepts a bare extras name ('dev'), a bracketed list ('[dev,rl]'), a full target ('.[dev]'), or raw pip arguments ('-r requirements/test.txt'). If empty, the package itself is installed via 'pip install -e .[dev]' (falling back to bare install).
`pre_install_pip`	string	`""`	Optional space-separated pip requirement specs to install BEFORE the package install step. Use this to override transitive deps with git URLs (e.g. for testing against an unreleased version of a sibling package).
`test_path`	string	`test/`	Path passed to pytest (file, directory, or glob)
`coverage_source`	string	`.`	Value of --cov= passed to pytest. Set to your package directory (e.g. 'ovos_core') to measure only your own code rather than the full repo.
`pytest_args`	string	`""`	Extra arguments appended to the pytest invocation, e.g. '-n auto' to run tests in parallel via pytest-xdist. Same name and meaning as on build-tests.yml. Empty by default: no change to the command line.
`deploy_pages`	boolean	`false`	Push the HTML coverage report to the gh-pages branch for GitHub Pages serving. Replaces the separate coverage-pages.yml workflow.
`gh_pages_branch`	string	`gh-pages`	Branch to push the HTML coverage report to (when deploy_pages: true).
`min_coverage`	number	`0`	Minimum total coverage percentage (0 = disabled). The job fails if coverage falls below this threshold.
`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. Shows total coverage, threshold status, and files below 80% coverage.
`artifact_name`	string	`coverage-report`	Name of the uploaded coverage artifact
`artifact_retention_days`	number	`14`	Days to retain the coverage XML artifact

Jobs¶

Job step	Description
Checkout + scripts checkout	Checks out the calling repo and (on PR events) the gh-automations scripts
Setup Python + Install Dependencies	Installs `pytest`, `pytest-cov`, `coverage[toml]`, `ovoscope`, and the package itself
Run Tests with Coverage	`pytest --cov --cov-report=xml --cov-report=json --cov-report=html --cov-report=term-missing`. `continue-on-error: true` so the PR comment posts even when tests fail.
Extract Coverage Percentage	Reads `coverage.json` for `totals.percent_covered`

Job step	Description
Write Job Summary	Coverage table written to `$GITHUB_STEP_SUMMARY`
Format coverage section	Generates the PR comment content from `coverage.json`
Post coverage section to PR comment	Calls `scripts/update_pr_comment.py` to find-or-create-and-update the OVOS PR Checks comment
Upload Coverage XML Artifact	Uploads `coverage.xml` as a workflow artifact

Job step	Description
Enforce Minimum Coverage Threshold	Fails if `min_coverage > 0` and total is below threshold
Fail job if tests failed	Re-raises test failure after the PR comment has been posted

Typical usage¶

name: Coverage
on:
  pull_request:
    branches: [dev]
  workflow_dispatch:

permissions:
  pull-requests: write
  contents: read

jobs:
  coverage:
    uses: OpenVoiceOS/gh-automations/.github/workflows/coverage.yml@dev
    secrets: inherit
    with:
      coverage_source: 'my_package'
      min_coverage: 80

Behavior notes¶

pr_comment only fires on pull_request events, job summary is written for all events.
If all tests are skipped and coverage.xml is never generated, the PR comment will note that coverage data is unavailable rather than failing.

`coverage-pages.yml` (deprecated)¶

Deprecated, use coverage.yml with deploy_pages: true instead. Kept for backward compatibility with existing callers. Scheduled for removal after 2027-01-01. New repos should not adopt it.

Runs pytest --cov and deploys the HTML coverage report to GitHub Pages.

Source: .github/workflows/coverage-pages.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.11`
`system_deps`	string	`""`	Extra apt packages to install before testing (space-separated)
`install_extras`	string	`""`	Extra dependencies to install before tests. Accepts a bare extras name ('dev'), a bracketed list ('[dev,rl]'), a full target ('.[dev]'), or raw pip arguments ('-r requirements/test.txt'). If empty, the package itself is installed via 'pip install -e .[dev]' (falling back to bare install).
`test_path`	string	`test/`	Path passed to pytest (file, directory, or glob)
`coverage_source`	string	`.`	Value of --cov= passed to pytest. Set to your package directory (e.g. 'ovos_core') to measure only your own code rather than the full repo.
`gh_pages_branch`	string	`gh-pages`	Branch to push the HTML coverage report to.

Jobs¶

Job step	Description
Checkout	Checks out the calling repo
Setup Python + Install Dependencies	Installs `pytest`, `pytest-cov`, `coverage[toml]`, `ovoscope`, and the package itself
Run Tests with Coverage	`pytest --cov --cov-report=html:htmlcov`. `continue-on-error: true` so deployment proceeds even with test failures.
Publish report	Checks out (or orphans) the `gh_pages_branch`, copies the generated `htmlcov/` onto it, and `git push`es the branch.

Typical usage¶

name: Coverage Pages
on:
  push:
    branches: [dev]
  workflow_dispatch:

permissions:
  contents: write   # needed to push the gh-pages branch

jobs:
  coverage_pages:
    uses: OpenVoiceOS/gh-automations/.github/workflows/coverage-pages.yml@dev
    secrets: inherit
    with:
      coverage_source: 'my_package'

Prerequisites¶

Grant contents: write in the calling workflow (to push the branch).
In repo settings, set GitHub Pages → Source to the gh-pages branch (the report is pushed there, not deployed via the Pages-Actions pipeline).

`pip-audit.yml`¶

Scans installed dependencies for known CVEs using pypa/gh-action-pip-audit. Optionally uploads a SARIF report to GitHub's Security tab.

Source: .github/workflows/pip-audit.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`	Python version to use for the audit
`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
`ignore_vulns`	string	`GHSA-r9hx-vwmv-q579`	Newline-separated list of GHSA vulnerability IDs to ignore. Default ignores GHSA-r9hx-vwmv-q579 (setuptools path traversal — dev-only, not exploitable in OVOS runtime context).
`warn_only`	boolean	`false`	When true, report vulnerabilities in the PR comment but do NOT fail the job. Useful for repos that want visibility without blocking merges.
`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.
`upload_sarif`	boolean	`true`	Upload a SARIF report to GitHub's Security tab (Code scanning alerts). Requires the repo to have GitHub Advanced Security enabled, or be public.

Typical usage¶

name: Pip Audit
on:
  push:
    branches: [dev, master]
  workflow_dispatch:

jobs:
  pip_audit:
    uses: OpenVoiceOS/gh-automations/.github/workflows/pip-audit.yml@dev
    with:
      install_extras: '[all]'

`downstream-check.yml`¶

Reports which packages in the ovos-releases alpha constraints depend on a given package. Uses pipdeptree and uploads the sorted report as a workflow artifact — the report is no longer committed to the repo (the commit_branch input below is deprecated and ignored).

Source: .github/workflows/downstream-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.
`package_name`	string	(required)	PyPI package name to track dependents of
`runner`	string	`ubuntu-latest`
`python_version`	string	`3.11`
`constraints_url`	string	`https://raw.githubusercontent.com/OpenVoiceOS/ovos-releases/refs/heads/main/constraints-alpha.txt`	URL of the ovos-releases constraints file to install against
`system_deps`	string	`""`	Extra apt packages to install (space-separated) in addition to the standard OVOS build deps
`output_file`	string	`downstream_report.txt`	Local filename for the generated report (also used as artifact name)
`pr_comment`	boolean	`true`	Post the report as a section in the OVOS PR Checks comment (only on pull_request events)
`commit_branch`	string	`dev`	Deprecated — ignored. Report is now uploaded as an artifact instead of committed.

Typical usage¶

name: Track Downstream Dependencies
on:
  push:
    branches: [dev]
  schedule:

    - cron: "0 0 * * *"
  workflow_dispatch:

jobs:
  check_downstream:
    uses: OpenVoiceOS/gh-automations/.github/workflows/downstream-check.yml@dev
    secrets: inherit
    with:
      package_name: 'ovos-utils'

Reusable Workflow Reference: Coverage and Security Workflows¶

coverage.yml¶

Inputs¶

Jobs¶

Typical usage¶

Behavior notes¶

coverage-pages.yml (deprecated)¶

Inputs¶

Jobs¶

Typical usage¶

Prerequisites¶

pip-audit.yml¶

Inputs¶

Typical usage¶

downstream-check.yml¶

Inputs¶

Typical usage¶

`coverage.yml`¶

`coverage-pages.yml` (deprecated)¶

`pip-audit.yml`¶

`downstream-check.yml`¶