Skip to content

Reusable Workflow Reference: Lint, Docs, and Notification Workflows

In a nutshell

This page documents the shared workflows for lint, type-checking, docs presence, and Matrix chat notifications: lint.yml, type-check.yml, docs-check.yml, and notify-matrix.yml. For coverage and dependency security scans, see Coverage and Security 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:

lint.yml

Runs ruff and/or pre-commit and posts results to the OVOS PR Checks comment.

Source: .github/workflows/lint.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
ruff boolean true Run ruff check
ruff_args string . --exclude _gh_automations Arguments passed to ruff check (e.g. '. --select E,F'). Default excludes _gh_automations/, which is where other reusable workflows in this repo check themselves out as a sibling for PR comment scripts. Without this exclude, consumers see ruff errors from this repo's own scripts in their skill PRs.
pre_commit boolean false Run pre-commit run --all-files (requires .pre-commit-config.yaml)
pr_comment boolean true Post a section in the OVOS PR Checks comment on pull_request events

type-check.yml

Runs mypy and posts a Type Check section. Informational only, never blocks merges unless fail_on_errors: true.

Source: .github/workflows/type-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.11
mypy_args string . Arguments passed to mypy (e.g. 'my_package' or '. --ignore-missing-imports'). Default checks the entire repository.
test_extras string dev Name of the pyproject.toml extras key that declares the package's test/typing dependencies. Tried first via 'pip install -e .[]'.
test_extras_fallback string test Extras key tried if test_extras is not declared. Empty to skip.
install_extras string "" Extra dependencies to install after the package install. Accepts a bare extras name ('dev'), a bracketed list ('[dev,rl]'), a full target ('.[dev]'), or raw pip arguments ('-r requirements/typing.txt').
system_deps string "" Extra apt packages to install before type-checking (space-separated)
fail_on_errors boolean false When true, the job fails if mypy reports any errors. Default is false — type check is informational.
pr_comment boolean true Post a 🔎 Type Check section in the shared OVOS PR Checks comment. Only runs when the workflow is triggered by a pull_request event.

docs-check.yml

Verifies required documentation files exist and optionally lints Markdown. Posts a Docs section. Informational only, never blocks merges unless fail_on_missing: true.

Source: .github/workflows/docs-check.yml

Inputs

Input Type Default Description
runner string ubuntu-latest
required_files string README.md Comma-separated list of files that must exist at the repo root. Checked with a simple exists() test — no content validation.
markdownlint boolean false Run markdownlint-cli2 on *.md files. Requires Node.js (available on ubuntu-latest runners). Results are reported in the PR comment but never block merges regardless of fail_on_missing.
markdownlint_config string "" Path to a markdownlint config file (e.g. '.markdownlint.json'). If empty, markdownlint-cli2 uses its built-in defaults.
fail_on_missing boolean false When true, the job fails if any required file is absent. Default is false — docs check is informational.
pr_comment boolean true Post a 📚 Docs section in the shared OVOS PR Checks comment. Only runs when the workflow is triggered by a pull_request event.

notify-matrix.yml

Sends a message to the OVOS Matrix channel via a raw curl -X PUT to the Matrix client-server API (/_matrix/client/v3/rooms/.../send/m.room.message/...).

Source: .github/workflows/notify-matrix.yml

Inputs

Input Type Default Description
message string (required) Message to send to the Matrix channel
homeserver string matrix.org Matrix homeserver URL
channel string !WjxEKjjINpyBRPFgxl:krbel.duckdns.org Matrix room ID
runner string ubuntu-latest

Secrets

Secret Required Description
MATRIX_TOKEN no (used via secrets: inherit; not formally declared as a workflow_call secret)

Typical usage

  notify:
    if: github.event.pull_request.merged == true
    needs: publish_alpha
    uses: OpenVoiceOS/gh-automations/.github/workflows/notify-matrix.yml@dev
    secrets: inherit
    with:
      message: "new ${{ github.event.repository.name }} PR merged! https://github.com/${{ github.repository }}/pull/${{ github.event.number }}"

Read next: gh-automations Quality Workflows Related: gh-automations Overview · Coverage and Security Workflows · PR Comment Pattern and Scripts · Workflow Reference