README.md

GitHub Actions + Vale

The official GitHub Action for Vale -- install, manage, and run Vale with ease.

Usage

Add the following (or similar) to one of your .github/workflows files:

name: reviewdog
on: [pull_request]

jobs:
  vale:
    name: runner / vale
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: errata-ai/[email protected]

Tip

If you're using a markup format other than Markdown, you may need to install an external parser before calling vale-action:

# For AsciiDoc users:
- name: Install Asciidoctor
  run: sudo apt-get install -y asciidoctor

# For reStructuredText users:
- name: Install docutils
  run: sudo apt-get install -y docutils

See the Vale documentation for more information.

Repository Structure

The recommended repository structure makes use of the existing .github directory to hold all of our Vale-related resources:

.github
├── styles
│   └── vocab.txt
└── workflows
    └── main.yml
.vale.ini
...

Where styles represents your StylesPath. The top-level .vale.ini file should reference this directory:

StylesPath = .github/styles
MinAlertLevel = suggestion

[*.md]
BasedOnStyles = Vale

Inputs

You can further customize the linting processing by providing one of the following optional inputs.

To add an input, edit your workflow file and add the with key to the uses block. For example:

- uses: errata-ai/[email protected]
  with:
    version: 2.17.0

version (default: latest)

NOTE: The provided version must be >= 2.16.0.

Specify the Vale CLI version to use.

with:
  version: 2.17.0

files (default: all)

files specifies where Vale will look for files to lint.

with:
  files: path/to/lint

You can supply this value one of four ways:

• files: all (default): The repo's root directory; equivalent to calling vale ..

• files: path/to/lint: A single file or directory; equivalent to calling vale path/to/lint.

• files: '["input1", "input2"]': A JSON-formatted list of file or directory arguments; equivalent to calling vale input1 input2.

• files: 'input1,input2': A character-delimited list of files. The character is determined by the input value separator:

  with:
    separator: ","

reporter (default: github-pr-check)

Set the reporter type.

with:
  # github-pr-check, github-pr-review, github-check
  reporter: github-pr-check

fail_on_error (default: false)

Warning

This input is deprecated. Use fail_level instead. If fail_level and fail_on_error are both set, fail_level takes precedence.

By default, reviewdog will return exit code 0 even if it finds errors. If fail_on_error is enabled, reviewdog exits with 1 when at least one error was reported.

with:
  fail_on_error: true

fail_level (default: none)

By default, reviewdog will return exit code 0. If fail_level is set to any, info, warning, or error, reviewdog exits with code 1 if it finds at least one issue with severity greater than or equal to the given setting.

with:
  fail_level: any

filter_mode (default: added)

Set the filter mode for reviewdog.

with:
  # added, diff_context, file, nofilter
  filter_mode: nofilter

vale_flags (default: "")

Space-delimited list of flags for the Vale CLI. To see a full list of available flags, run vale -h.

Note that flags should not include quotes. So while --glob='*.txt' works with Vale, it does not work with this action. Use the flag without quotes, as in the following example:

with:
  vale_flags: "--glob=*.txt"

token (default: secrets.GITHUB_TOKEN)

The GitHub token to use.

with:
  token: ${{secrets.VALE_GITHUB_TOKEN}}