GitHub

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

Screenshots

  • Checks on pull requests:

    Screenshot of check runs

  • Commit annotations:

    Screenshot of ESLint annotations

Supported tools

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:
  # Trigger the workflow on push or pull request,
  # but only for the main branch
  push:
    branches:
      - main
  # Replace pull_request with pull_request_target if you
  # plan to use this action with forks, see the Limitations section
  pull_request:
    branches:
      - main
# Down scope as necessary via https://docs.github.com/en/actions/security-guides/automatic-token-authentication#modifying-the-permissions-for-the-github_token
permissions:
  checks: write
  contents: write
jobs:
  run-linters:
    name: Run linters
    runs-on: ubuntu-latest
    steps:
      - name: Check out Git repository
        uses: actions/checkout@v7
      # Install your linters here
      - name: Run linters
        uses: wearerequired/lint-action@v3
        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:
  # 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/checkout@v7
      - name: Set up Node.js
        uses: actions/setup-node@v7
        with:
          node-version: 24
      # ESLint and Prettier must be in `package.json`
      - name: Install Node.js dependencies
        run: npm ci
      - name: Run linters
        uses: wearerequired/lint-action@v3
        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:
  # 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/checkout@v7
      - name: Set up PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: "7.4"
          coverage: none
          tools: phpcs
      - name: Run linters
        uses: wearerequired/lint-action@v3
        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/checkout@v7
      - name: Set up PHP
        uses: shivammathur/setup-php@v2
        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/lint-action@v3
        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/checkout@v7
      - name: Set up Python
        uses: actions/setup-python@v1
        with:
          python-version: 3.8
      - name: Install Python dependencies
        run: pip install black flake8
      - name: Run linters
        uses: wearerequired/lint-action@v3
        with:
          black: true
          flake8: true

C, C++, Objective-C and Objective-C++ example (clang_format)

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/checkout@v7
      - name: Install ClangFormat
        run: sudo apt-get install -y clang-format
      - name: Run linters
        uses: wearerequired/lint-action@v3
        with:
          clang_format: true

C# and VB.NET example (dotnet_format)

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/checkout@v7
      - name: Set up .NET
        uses: actions/setup-dotnet@v1
        with:
          dotnet-version: "6.0.x"
      - name: Run linters
        uses: wearerequired/lint-action@v3
        with:
          dotnet_format: true

AutoFix example

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/checkout@v7
      - name: Set up Python
        uses: actions/setup-python@v1
        with:
          python-version: 3.8
      - name: Install Python dependencies
        run: pip install black flake8
      - name: Run linters
        uses: wearerequired/lint-action@v3
        with:
          auto_fix: true
          black: true
          black_auto_fix: true
          flake8: true
          flake8_auto_fix: false

With auto_fix set to true, by default the action will try and fix code issues automatically and commit and push them automatically. Here however, flake8 linter does not support auto-fixing, so setting flake8_auto_fix to false will prevent any unnecessary warnings.

Configuration

Linter-specific options

[linter] can be one of autopep8, black, clang_format, dotnet_format, erblint, eslint, flake8, gofmt, golint, isort, mypy, oitnb, php_codesniffer, prettier, pylint, rubocop, ruff, standardrb, staticcheck, 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: "".
  • [linter]_auto_fix: Whether the linter should try to fix code style issues automatically. This option is useful to commit and push changes only for specific linters and not all of them when auto_fix option is set. Default: true if linter supports auto-fixing, false if not.

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 apply the needed changes. Default: false

    Screenshot of auto-fix commit

  • commit: Whether to commit and push the changes made by auto_fix. Default: true

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

  • git_email: Email address for auto-fix commits. Default: "lint-action@samuelmeuli.com"

  • 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 available for specific linters:

Linter auto-fixing extensions
autopep8 ✅ ❌ (py)
black ✅ ✅
clang_format ✅ ✅
clippy ✅ ❌ (rs)
dotnet_format ✅ ❌ (cs)
erblint ❌ ❌ (erb)
eslint ✅ ✅
flake8 ❌ ✅
gofmt ✅ ❌ (go)
golint ❌ ❌ (go)
isort ✅ ❌ (py)
mypy ❌ ❌ (py)
oitnb ✅ ✅
php_codesniffer ❌ ✅
prettier ✅ ✅
pylint ❌ ❌ (py)
rubocop ✅ ❌ (rb)
ruff ✅ ❌ (py)
rustfmt ✅ ❌ (rs)
standardrb ✅ ❌ (rb)
staticcheck ❌ ❌ (go)
stylelint ✅ ✅
swift_format_official ✅ ✅
swift_format_lockwood ✅ ❌ (swift)
swiftlint ✅ ❌ (swift)
tsc ❌ ❌ (ts)
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 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 unless you use the pull_request_target event. You can modify the default permissions granted to the GITHUB_TOKEN by using the permissions key and set the checks scope to write. See GitHub documentation for more.

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.

a required open source product - let's get in touch

Read the original on github.com ↗