GitHub Action
Vale Linter
The official GitHub Action for Vale -- install, manage, and run Vale with ease.
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}}
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
You can further customize the linting processing by providing one of the following optional inputs.
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
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:
- Any multi-value entry in the local
.vale.ini
file (e.g.,BasedOnStyles
) will be combined with the remote entry. - Any single-value entry in the local
.vale.ini
file (e.g.,MinAlertLevel
) will override the remote entry altogether.
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 callingvale .
. -
files: __onlyModified
: Lint only files that have been modified within a PR. -
files: path/to/lint
: A single file or directory; equivalent to callingvale path/to/lint
. -
files: '["input1", "input2"]'
: A list of file or directory arguments; equivalent to callingvale input1 input2
.
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
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}}