✨ Lint Action

• Shows linting errors on GitHub commits and PRs
• Allows auto-fixing issues
• Supports many linters and formatters

Note: The behavior of actions like this one is currently limited in the context of forks. See Limitations.

Screenshots

• Checks on pull requests:

  

• Commit annotations:

  

Supported tools

• CSS:
  • stylelint
• Go:
  • gofmt
  • golint
• JavaScript:
  • ESLint
  • Prettier
  • XO
• PHP:
  • PHP_CodeSniffer
• Python:
  • Black
  • Flake8
  • Mypy
• Ruby:
  • RuboCop
• Swift:
  • swift-format (official)
  • SwiftFormat (by Nick Lockwood)
  • SwiftLint

Usage

Create a new GitHub Actions workflow in your project, e.g. at .github/workflows/lint.yml. The content of the file should be in the following format:

name: Lint

on: push

jobs:
  run-linters:
    name: Run linters
    runs-on: ubuntu-latest

    steps:
      - name: Check out Git repository
        uses: actions/[email protected]

      # Install your linters here

      - name: Run linters
        uses: wearerequired/[email protected]
        with:
          # Enable your linters here

Examples

All linters are disabled by default. To enable a linter, simply set the option with its name to true, e.g. eslint: true.

The action doesn't install the linters for you; you are responsible for installing them in your CI environment.

JavaScript example (ESLint and Prettier)

name: Lint

on: push

jobs:
  run-linters:
    name: Run linters
    runs-on: ubuntu-latest

    steps:
      - name: Check out Git repository
        uses: actions/[email protected]

      - name: Set up Node.js
        uses: actions/[email protected]
        with:
          node-version: 12

      # ESLint and Prettier must be in `package.json`
      - name: Install Node.js dependencies
        run: npm ci

      - name: Run linters
        uses: wearerequired/[email protected]
        with:
          eslint: true
          prettier: true

Important: Make sure to exclude the .github directory in your ESLint and Prettier configs as the default GITHUB_TOKEN cannot be used to update workflow files due to the missing workflow permission. See Limitations.

PHP example (PHP_CodeSniffer)

name: Lint

on: push

jobs:
  run-linters:
    name: Run linters
    runs-on: ubuntu-latest

    steps:
      - name: Check out Git repository
        uses: actions/[email protected]

      - name: Set up PHP
        uses: shivammathur/[email protected]
        with:
          php-version: "7.4"
          coverage: none
          tools: phpcs

      - name: Run linters
        uses: wearerequired/[email protected]
        with:
          php_codesniffer: true
          # Optional: Ignore warnings
          php_codesniffer_args: "-n"

If you prefer to use Composer you can also use this:

name: Lint

on: push

jobs:
  run-linters:
    name: Run linters
    runs-on: ubuntu-latest

    steps:
      - name: Check out Git repository
        uses: actions/[email protected]

      - name: Set up PHP
        uses: shivammathur/[email protected]
        with:
          php-version: "7.4"
          coverage: none
          tools: composer

      - name: Install PHP dependencies
        run: |
          composer install --prefer-dist --no-suggest --no-progress --no-ansi --no-interaction
          echo "${PWD}/vendor/bin" >> $GITHUB_PATH

      - name: Run linters
        uses: wearerequired/[email protected]
        with:
          php_codesniffer: true

Python example (Flake8 and Black)

name: Lint

on: push

jobs:
  run-linters:
    name: Run linters
    runs-on: ubuntu-latest

    steps:
      - name: Check out Git repository
        uses: actions/[email protected]

      - name: Set up Python
        uses: actions/[email protected]
        with:
          python-version: 3.8

      - name: Install Python dependencies
        run: pip install black flake8

      - name: Run linters
        uses: wearerequired/[email protected]
        with:
          black: true
          flake8: true

Configuration

Linter-specific options

[linter] can be one of black, eslint, flake8, gofmt, golint, mypy, php_codesniffer, prettier, rubocop, stylelint, swift_format_official, swift_format_lockwood, swiftlint and xo:

• [linter]: Enables the linter in your repository. Default: false
• [linter]_args: Additional arguments to pass to the linter. Example: eslint_args: "--max-warnings 0" if ESLint checks should fail even if there are no errors and only warnings. Default: ""
• [linter]_dir: Directory where the linting command should be run. Example: eslint_dir: server/ if ESLint is installed in the server subdirectory. Default: Repository root
• [linter]_extensions: Extensions of files to check with the linter. Example: eslint_extensions: js,ts to lint JavaScript and TypeScript files with ESLint. Default: Varies by linter, see action.yml
• [linter]_command_prefix: Command prefix to be run before the linter command. Default: "".

General options

• github_token: The GITHUB_TOKEN to authenticate on behalf of GitHub Actions. Defaults to the GitHub token.

• continue_on_error: Whether the workflow run should also fail when linter failures are detected. Default: true

• auto_fix: Whether linters should try to fix code style issues automatically. If some issues can be fixed, the action will commit and push the changes to the corresponding branch. Default: false

  

• git_name: Username for auto-fix commits. Default: "Lint Action"

• git_email: Email address for auto-fix commits. Default: "[email protected]"

• commit_message: Template for auto-fix commit messages. The ${linter} variable can be used to insert the name of the linter. Default: "Fix code style issues with ${linter}"

• check_name: Template for the name of the check run. Use this to ensure unique names when the action is used more than once in a workflow. The ${linter} and ${dir} variables can be used to insert the name and directory of the linter. Default: "${linter}"

Linter support

Some options are not be available for specific linters:

Limitations

Pull requests

There are currently some limitations as to how this action (or any other action) can be used in the context of pull_request events from forks:

• The action doesn't have permission to push auto-fix changes to the fork. This is because the pull_request event runs on the upstream repo, where the github_token is lacking permissions for the fork. Source
• The action doesn't have permission to create annotations for commits on forks and can therefore not display linting errors. Source 1, source 2

For details and comments, please refer to #13.

Auto-fixing workflow files

If auto_fix is enabled and the default GITHUB_TOKEN is used, none of the linters should be allowed to change files in .github/workflows as the token doesn't have the necessary workflow permission. This can be achieved by adding the directory to the ignore config of the used linter. Source

For details and comments, please refer to #65 and #74.