Integrating Vale into your Git workflow by using a GitHub Action

Integrate Vale into your GitHub content development workflow by creating a GitHub Action that uses the GitHub Action for Vale.

By creating a GitHub Action workflow for Vale, you can configure how Vale runs: you can set Vale flags and specify which Git workflow events trigger Vale jobs. For example, you can decide to:

Run Vale when a contributor creates a pull request.
Run Vale on only the changes.
Allow the merging of pull requests if the report has errors.
Block the merging of pull requests if the report has errors.

For a full list of supported configuration options, see Vale GitHub Action.

Prerequisites

Your content repository is on GitHub. For GitLab repos, see * Define a Vale CI onboarding strategy for your project. WARNING: Because of GitHub token permissions, the Vale GitHub Action cannot post annotations to pull requests from a forked repository.
You have defined a Using Vale with a continuous integration service for your project.
You have reviewed and bookmarked the official vale-action information at errata.ai.

Procedure

Copy .vale.ini from vale-at-red-hat into the root of your GitHub repository and configure your style preferences.
In the .github/workflows/ folder of your project repository, create a YAML file called vale.yml.
- Tip: You can also click Actions and use the GitHub Actions wizard to initialize the vale.yml file and validate your configuration.

Add the following configuration to the .github/workflows/lint-with-vale.yml file:

---
name: Linting with Vale on pull request
on: [pull_request]

jobs:
  vale:
    name: Linting with Vale
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Asciidoctor
        run: sudo apt-get install -y asciidoctor
      - uses: errata-ai/vale-action@reviewdog
        with:
          filter_mode: diff_context
          vale_flags: "--no-exit --minAlertLevel=error"
          reporter: github-pr-review
          fail_on_error: true
        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}}
          REVIEWDOG_GITHUB_API_TOKEN: ${{secrets.GITHUB_TOKEN}}

Optional: Change the default configuration to suit the requirements of your project. For example, if you want to block PR merges when Vale errors exist, set fail_on_error to true.
Commit and push the GitHub Action to the main branch of your GitHub repository and rebase your other branches.

Verification

To test your GitHub Action, change or add some content files and submit a pull request to the main docs branch. Vale will run and report an expandable status summary in the PR.