GitHub Actions + Vale

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

Usage

Add the following (or similar, but you need the actions/checkout@master step) to one of your .github/workflows files:

name: Linting
on: [push]

jobs:
  prose:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@master

    - name: Vale
      uses: errata-ai/vale-action@v1
      with:
        # Optional
        styles: |
          https://github.com/errata-ai/Microsoft/releases/latest/download/Microsoft.zip
          https://github.com/errata-ai/write-good/releases/latest/download/write-good.zip

        # Optional
        config: https://raw.githubusercontent.com/errata-ai/vale/master/.vale.ini

        # Optional
        files: path/to/lint
      env:
        # Required, set by GitHub actions automatically:
        # https://docs.github.com/en/actions/security-guides/automatic-token-authentication#about-the-github_token-secret
        GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

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.

styles

styles is a space-delimited list of external styles to install into your repository's local StylesPath. Each link needs to point to a single .zip file containing the style:

with:
  styles: |
    https://github.com/errata-ai/Microsoft/releases/latest/download/Microsoft.zip
    https://github.com/errata-ai/write-good/releases/latest/download/write-good.zip

See errata-ai/styles for more information.

config

config is a single, remotely-hosted Vale configuration file:

with:
  config: https://raw.githubusercontent.com/errata-ai/vale/master/.vale.ini

This configuration file can be hosted in another repo (as shown above), a GitHub Gist, or another source altogether. If you also have a .vale.ini file in the local repo, the two files will be combined according to the following rules:

1. Any multi-value entry in the local .vale.ini file (e.g., BasedOnStyles) will be combined with the remote entry.
2. Any single-value entry in the local .vale.ini file (e.g., MinAlertLevel) will override the remote entry altogether.

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 three ways:

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

• files: __onlyModified: Lint only files that have been modified within a PR.

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

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

onlyAnnotateModifiedLines (default: false)

In case you want the action to only annotate lines that have been modified within a PR. This is helpful in case you're introducing vale to a repository that (still) has a lot of lints and don't want to overwhelm everyone.

with:
  onlyAnnotateModifiedLines: true

Limitations

Due to the current token permissions, this Action CAN NOT post annotations to PRs from forked repositories.

This will likely be fixed by toolkit/issues/186.

A workaround is to run this action as a follow-up workflow. For example, pull_request workflow generates source artifact and post-workflow scan artifact with vale and then annotate the commit. Use OVERRIDE_GITHUB_SHA environment variable to override the commit SHA to annotate if matching a Pull Request.

on:
  workflow_run:
    workflows: ["PR check"]
    types:
      - completed

jobs:
  vale:
    runs-on: ubuntu-20.04
    steps:
      ...
      - name: Grab pull request sha1
        run: |
          ....
          echo "PR_SHA=$pr_sha" >> $GITHUB_ENV
      - name: Vale Linter
        uses: errata-ai/[email protected]
        with:
          ...
        env:
          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
          OVERRIDE_GITHUB_SHA: ${{env.PR_SHA}}