CI Integration¶

Add docvet to your CI pipeline to enforce docstring quality on every push and pull request. This page covers GitHub Actions, pre-commit hooks, and how configuration controls exit codes.

GitHub Action¶

The Alberto-Codes/docvet action installs docvet and runs it in a single step.

Inputs¶

Input	Required	Default	Description
`version`	No	`latest`	docvet version to install
`args`	No	`check`	Arguments passed to the `docvet` CLI

Usage¶

BasicVersion-pinnedWith griffe

jobs:
  docvet:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: Alberto-Codes/docvet@v1
        with:
          args: 'check --all'

jobs:
  docvet:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: Alberto-Codes/docvet@v1
        with:
          version: '1.2.0'
          args: 'check --all'

Install griffe before running docvet to enable rendering compatibility checks:

jobs:
  docvet:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install griffe
      - uses: Alberto-Codes/docvet@v1
        with:
          args: 'check --all'

Freshness checks need git history

The freshness check uses git blame to detect stale docstrings. If your checkout step uses a shallow clone (the default), add fetch-depth: 0 for full blame support:

- uses: actions/checkout@v6
  with:
    fetch-depth: 0

Pre-commit¶

docvet ships a pre-commit hook that checks staged files before each commit.

BasicWith griffe

repos:
  - repo: https://github.com/Alberto-Codes/docvet
    rev: v1.2.0
    hooks:
      - id: docvet

repos:
  - repo: https://github.com/Alberto-Codes/docvet
    rev: v1.2.0
    hooks:
      - id: docvet
        additional_dependencies: [griffe]

The hook runs docvet check --staged, which checks only the files you are about to commit. It runs on Python files only and discovers files through git — no filenames are passed by pre-commit.

Pin rev to a release tag

Replace v1.2.0 with the latest release tag. Pre-commit caches the hook environment per rev, so pinning to a tag avoids unnecessary reinstalls.

Exit Codes and CI Behavior¶

docvet uses fail-on and warn-on to control whether findings cause a non-zero exit code:

Exit Code	Meaning
0	No findings in `fail-on` checks — CI passes
1	One or more findings in a `fail-on` check — CI fails
2	Usage error (invalid arguments or configuration)

How `fail-on` works¶

Checks listed in fail-on cause exit code 1 when they produce findings. Checks in warn-on are reported but never affect the exit code.

[tool.docvet]
fail-on = ["enrichment", "freshness"]  # findings here → exit 1
warn-on = ["griffe", "coverage"]       # findings here → reported only

Without a [tool.docvet] section, fail-on defaults to [] — meaning docvet always exits 0 regardless of findings. To use docvet as a CI gate, you must add at least one check to fail-on.

Default warn-on overlap

The default warn-on list includes all four checks. If you add a check to fail-on, docvet silently removes it from the default warn-on — no warnings, no findings lost. Warnings only appear when you explicitly set both fail-on and warn-on with overlapping checks.

Suppress summary output in scripts

Use -q (quiet mode) when you only need the exit code and don't want summary or timing output:

- uses: Alberto-Codes/docvet@v1
  with:
    args: 'check --all -q'

See Configuration for the full list of options including freshness thresholds, enrichment toggles, and exclusion patterns.