✨ 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
  • oitnb
• 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

name: Lint

on:
Trigger the workflow on push or pull request,
but only for the main branch
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
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

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:
Trigger the workflow on push or pull request,
but only for the main branch
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
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

GITHUB_TOKEN

workflow

PHP example (PHP_CodeSniffer)

name: Lint

on:
Trigger the workflow on push or pull request,
but only for the main branch
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
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:
Trigger the workflow on push or pull request,
but only for the main branch
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
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-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:
Trigger the workflow on push or pull request,
but only for the main branch
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
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]

black

eslint

flake8

gofmt

golint

mypy

oitnb

php_codesniffer

prettier

rubocop

stylelint

swift_format_official

swift_format_lockwood

swiftlint

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]"

• git_no_verify

  : Bypass the pre-commit and pre-push git hooks. Default:

  false

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

• neutral_check_on_warning

  : Whether the check run should conclude with a neutral status instead of success when the linter finds only warnings. Default:

  false

Linter support

Some options are not be available for specific linters:

| Linter | auto-fixing | extensions | | --------------------- | :---------: | :--------: | | black | ✅ | ✅ | | eslint | ✅ | ✅ | | flake8 | ❌ | ✅ | | gofmt | ✅ | ❌ (go) | | golint | ❌ | ❌ (go) | | mypy | ✅ | ✅ | | oitnb | ✅ | ✅ | | phpcodesniffer | ❌ | ✅ | | prettier | ✅ | ✅ | | rubocop | ✅ | ❌ (rb) | | stylelint | ✅ | ✅ | | swiftformatofficial | ✅ | ✅ | | swiftformat_lockwood | ✅ | ❌ (swift) | | swiftlint | ✅ | ❌ (swift) | | xo | ✅ | ✅ |

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

• 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

GITHUB_TOKEN

.github/workflows

workflow

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