- 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.
-
Checks on pull requests:
-
Commit annotations:
- C:
- C++:
- C#:
- CSS:
- Go:
- JavaScript:
- Objective-C:
- Objective-C++:
- PHP:
- Python:
- Ruby:
- Swift:
- swift-format (official)
- SwiftFormat (by Nick Lockwood)
- SwiftLint
- VB.NET:
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@v2
# Install your linters here
- name: Run linters
uses: wearerequired/lint-action@v2
with:
# Enable your linters hereAll 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.
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@v2
- name: Set up Node.js
uses: actions/setup-node@v1
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/lint-action@v2
with:
eslint: true
prettier: trueImportant: 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.
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@v2
- 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@v2
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@v2
- 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@v2
with:
php_codesniffer: truename: 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@v2
- 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@v2
with:
black: true
flake8: truename: 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@v2
- name: Install ClangFormat
run: sudo apt-get install -y clang-format
- name: Run linters
uses: wearerequired/lint-action@v2
with:
clang_format: truename: 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@v2
- name: Set up .NET
uses: actions/setup-dotnet@v1
with:
dotnet-version: "6.0.x"
- name: Run linters
uses: wearerequired/lint-action@v2
with:
dotnet_format: truename: 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@v2
- 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@v2
with:
auto_fix: true
black: true
black_auto_fix: true
flake8: true
flake8_auto_fix: falseWith 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.
[linter] can be one of autopep8, black, clang_format, dotnet_format, erblint, eslint, flake8, gofmt, golint, mypy, oitnb, php_codesniffer, prettier, pylint, 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 theserversubdirectory. Default: Repository root[linter]_extensions: Extensions of files to check with the linter. Example:eslint_extensions: js,tsto lint JavaScript and TypeScript files with ESLint. Default: Varies by linter, seeaction.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 whenauto_fixoption is set. Default:trueif linter supports auto-fixing,falseif not.
-
github_token: TheGITHUB_TOKENto 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
-
commit: Whether to commit and push the changes made byauto_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
Some options are not available for specific linters:
| Linter | auto-fixing | extensions |
|---|---|---|
| autopep8 | ✅ | ❌ (py) |
| black | ✅ | ✅ |
| clang_format | ✅ | ✅ |
| dotnet_format | ✅ | ❌ (cs) |
| erblint | ❌ | ❌ (erb) |
| eslint | ✅ | ✅ |
| flake8 | ❌ | ✅ |
| gofmt | ✅ | ❌ (go) |
| golint | ❌ | ❌ (go) |
| mypy | ❌ | ❌ (py) |
| oitnb | ✅ | ✅ |
| php_codesniffer | ❌ | ✅ |
| prettier | ✅ | ✅ |
| pylint | ❌ | ❌ (py) |
| rubocop | ✅ | ❌ (rb) |
| stylelint | ✅ | ✅ |
| swift_format_official | ✅ | ✅ |
| swift_format_lockwood | ✅ | ❌ (swift) |
| swiftlint | ✅ | ❌ (swift) |
| xo | ✅ | ✅ |
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_requestevent runs on the upstream repo, where thegithub_tokenis 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_targetevent. You can modify the default permissions granted to theGITHUB_TOKENby using thepermissionskey and set thechecksscope towrite. See GitHub documentation for more.
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.