Skip to content
You're viewing an older version of this GitHub Action. Do you want to see the latest version instead?
check

GitHub Action

Vale Linter

v1.5.0

Vale Linter

check

Vale Linter

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

Installation

Copy and paste the following snippet into your .yml file.

              

- name: Vale Linter

uses: errata-ai/[email protected]

Learn more about this action in errata-ai/vale-action

Choose a version

GitHub Actions + Vale

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

A demo screenshot.

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}}