Awesome Open Source
Awesome Open Source

Mega-Linter

GitHub release Docker Pulls Downloads/week GitHub stars Mega-Linter codecov Secured with Trivy GitHub contributors GitHub Sponsors PRs Welcome Tweet

Mega-Linter is an 100% Open-Source tool for CI/CD workflows that analyzes consistency and quality of 45 languages, 22 formats, 17 tooling formats , abusive copy-pastes and spelling mistakes in your repository sources, generates various reports, and can even apply formatting and auto-fixes, to ensure all your projects sources are clean, whatever IDE/toolbox are used by their developers.

Ready to use out of the box as a GitHub Action or any CI system, highly configurable and free for all uses

See Online Documentation Web Site which has a much easier user navigation than this README

Screenshot Screenshot

Table of Contents

Why Mega-Linter

Projects need to contain clean code, in order to avoid technical debt, that makes evolutive maintenance harder and time consuming.

By using code formatters and code linters, you ensure that your code base is easier to read and respects best practices, from the kick-off to each step of the project lifecycle

Not all developers have the good habit to use linters in their IDEs, making code reviews harder and longer to process

By using Mega-Linter, you'll enjoy the following benefits for you and your team:

  • At each pull request it will automatically analyze all updated code in all languages
  • Reading error logs, developers learn best practices of the language they are using
  • Mega-Linter documentation provides the list of IDE plugins integrating each linter, so developers know which linter and plugins to install
  • Mega-Linter is ready out of the box after a quick setup
  • Formatting and fixes can be automatically applied on the git branch or provided in reports
  • This tool is 100% open-source and free for all uses (personal, professional, public and private repositories)
  • Mega-Linter can run on any CI tool and be run locally: no need to authorize an external application, and your code base never leaves your tooling ecosystem

Quick Start

  • Run npx mega-linter-runner --install to generate configuration files
  • Commit, push, and create a pull request
  • Watch !

Runner Install

Notes:

Supported Linters

All linters are integrated in the Mega-Linter docker image, which is frequently upgraded with their latest versions

Languages

Language Linter Configuration key Format/Fix
BASH bash-exec BASH_EXEC
shellcheck BASH_SHELLCHECK
shfmt BASH_SHFMT ✔️
C cpplint C_CPPLINT
CLOJURE clj-kondo CLOJURE_CLJ_KONDO
COFFEE coffeelint COFFEE_COFFEELINT
C++ (CPP) cpplint CPP_CPPLINT
C# (CSHARP) dotnet-format CSHARP_DOTNET_FORMAT ✔️
DART dartanalyzer DART_DARTANALYZER
GO golangci-lint GO_GOLANGCI_LINT
revive GO_REVIVE
GROOVY npm-groovy-lint GROOVY_NPM_GROOVY_LINT ✔️
JAVA checkstyle JAVA_CHECKSTYLE
JAVASCRIPT eslint JAVASCRIPT_ES ✔️
standard JAVASCRIPT_STANDARD ✔️
prettier JAVASCRIPT_PRETTIER ✔️
JSX eslint JSX_ESLINT ✔️
KOTLIN ktlint KOTLIN_KTLINT ✔️
LUA luacheck LUA_LUACHECK
PERL perlcritic PERL_PERLCRITIC
PHP php PHP_BUILTIN
phpcs PHP_PHPCS
phpstan PHP_PHPSTAN
psalm PHP_PSALM
POWERSHELL powershell POWERSHELL_POWERSHELL
PYTHON pylint PYTHON_PYLINT
black PYTHON_BLACK ✔️
flake8 PYTHON_FLAKE8
isort PYTHON_ISORT ✔️
R lintr R_LINTR
RAKU raku RAKU_RAKU
RUBY rubocop RUBY_RUBOCOP ✔️
RUST clippy RUST_CLIPPY
SALESFORCE sfdx-scanner-apex SALESFORCE_SFDX_SCANNER_APEX
sfdx-scanner-aura SALESFORCE_SFDX_SCANNER_AURA
sfdx-scanner-lwc SALESFORCE_SFDX_SCANNER_LWC
SCALA scalafix SCALA_SCALAFIX
SQL sql-lint SQL_SQL_LINT
sqlfluff SQL_SQLFLUFF
SWIFT swiftlint SWIFT_SWIFTLINT ✔️
TSX eslint TSX_ESLINT ✔️
TYPESCRIPT eslint TYPESCRIPT_ES ✔️
standard TYPESCRIPT_STANDARD ✔️
prettier TYPESCRIPT_PRETTIER ✔️
Visual Basic .NET (VBDOTNET) dotnet-format VBDOTNET_DOTNET_FORMAT ✔️

Formats

Format Linter Configuration key Format/Fix
CSS stylelint CSS_STYLELINT ✔️
scss-lint CSS_SCSS_LINT
ENV dotenv-linter ENV_DOTENV_LINTER ✔️
GRAPHQL graphql-schema-linter GRAPHQL_GRAPHQL_SCHEMA_LINTER
HTML htmlhint HTML_HTMLHINT
JSON jsonlint JSON_JSONLINT
eslint-plugin-jsonc JSON_ESLINT_PLUGIN_JSONC ✔️
v8r JSON_V8R
prettier JSON_PRETTIER ✔️
LATEX chktex LATEX_CHKTEX
MARKDOWN markdownlint MARKDOWN_MARKDOWNLINT ✔️
remark-lint MARKDOWN_REMARK_LINT ✔️
markdown-link-check MARKDOWN_MARKDOWN_LINK_CHECK
markdown-table-formatter MARKDOWN_MARKDOWN_TABLE_FORMATTER ✔️
PROTOBUF protolint PROTOBUF_PROTOLINT ✔️
RST rst-lint RST_RST_LINT
rstcheck RST_RSTCHECK
rstfmt RST_RSTFMT ✔️
XML xmllint XML_XMLLINT
YAML prettier YAML_PRETTIER ✔️
yamllint YAML_YAMLLINT
v8r YAML_V8R

Tooling formats

Tooling format Linter Configuration key Format/Fix
ANSIBLE ansible-lint ANSIBLE_ANSIBLE_LINT
ARM arm-ttk ARM_ARM_TTK
CLOUDFORMATION cfn-lint CLOUDFORMATION_CFN_LINT
DOCKERFILE dockerfilelint DOCKERFILE_DOCKERFILELINT
hadolint DOCKERFILE_HADOLINT
EDITORCONFIG editorconfig-checker EDITORCONFIG_EDITORCONFIG_CHECKER
GHERKIN gherkin-lint GHERKIN_GHERKIN_LINT
KUBERNETES kubeval KUBERNETES_KUBEVAL
OPENAPI spectral OPENAPI_SPECTRAL
PUPPET puppet-lint PUPPET_PUPPET_LINT ✔️
SNAKEMAKE snakemake SNAKEMAKE_LINT
snakefmt SNAKEMAKE_SNAKEFMT ✔️
TEKTON tekton-lint TEKTON_TEKTON_LINT
TERRAFORM tflint TERRAFORM_TFLINT
terrascan TERRAFORM_TERRASCAN
terragrunt TERRAFORM_TERRAGRUNT
terraform-fmt TERRAFORM_TERRAFORM_FMT ✔️

Other

Code quality checker Linter Configuration key Format/Fix
COPYPASTE jscpd COPYPASTE_JSCPD
GIT git_diff GIT_GIT_DIFF
SPELL misspell SPELL_MISSPELL ✔️
cspell SPELL_CSPELL

Installation

Assisted installation

Just run npx mega-linter-runner --install at the root of your repository and answer questions, it will generate ready to use configuration files for Mega-Linter :)

Runner Install

Manual installation

The following instructions examples are using to latest Mega-Linter stable version (V4 , always corresponding to the latest release)

You can also use insiders version (beta release, corresponding to the content of master branch)

GitHub Action

  1. Create a new file in your repository called .github/workflows/mega-linter.yml
  2. Copy the example workflow from below into that new file, no extra configuration required
  3. Commit that file to a new branch
  4. Open up a pull request and observe the action working
  5. Enjoy your more stable, and cleaner code base

NOTES:

  • If you pass the Environment variable GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} in your workflow, then the GitHub Mega-Linter will mark the status of each individual linter run in the Checks section of a pull request. Without this you will only see the overall status of the full run. There is no need to set the GitHub Secret as it is automatically set by GitHub, it only needs to be passed to the action.
  • You can also use it outside of GitHub Actions (CircleCI, Azure Pipelines, Jenkins, GitLab, or even locally with a docker run)

In your repository you should have a .github/workflows folder with GitHub Action similar to below:

  • .github/workflows/mega-linter.yml
This file should have this code
---
# Mega-Linter GitHub Action configuration file
# More info at https://nvuillam.github.io/mega-linter
name: Mega-Linter

on:
  # Trigger mega-linter at every push. Action will also be visible from Pull Requests to master
  push: # Comment this line to trigger action only on pull-requests (not recommended if you don't pay for GH Actions)
  pull_request:
    branches: [master, main]

env: # Comment env block if you do not want to apply fixes
  # Apply linter fixes configuration
  APPLY_FIXES: all # When active, APPLY_FIXES must also be defined as environment variable (in github/workflows/mega-linter.yml or other CI tool)
  APPLY_FIXES_EVENT: pull_request # Decide which event triggers application of fixes in a commit or a PR (pull_request, push, all)
  APPLY_FIXES_MODE: commit # If APPLY_FIXES is used, defines if the fixes are directly committed (commit) or posted in a PR (pull_request)

jobs:
  # Cancel duplicate jobs: https://github.com/fkirc/skip-duplicate-actions#option-3-cancellation-only
  cancel_duplicates:
    name: Cancel duplicate jobs
    runs-on: ubuntu-latest
    steps:
      - uses: fkirc/[email protected]
        with:
          github_token: ${{ secrets.PAT || secrets.GITHUB_TOKEN }}

  build:
    name: Mega-Linter
    runs-on: ubuntu-latest
    steps:
      # Git Checkout
      - name: Checkout Code
        uses: actions/[email protected]
        with:
          token: ${{ secrets.PAT || secrets.GITHUB_TOKEN }}
          fetch-depth: 0

      # Mega-Linter
      - name: Mega-Linter
        id: ml
        # You can override Mega-Linter flavor used to have faster performances
        # More info at https://nvuillam.github.io/mega-linter/flavors/
        uses: nvuillam/[email protected]
        env:
          # All available variables are described in documentation
          # https://nvuillam.github.io/mega-linter/configuration/
          VALIDATE_ALL_CODEBASE: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }} # Validates all source when push on master, else just the git diff with master. Override with true if you always want to lint all sources
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          # ADD YOUR CUSTOM ENV VARIABLES HERE OR DEFINE THEM IN A FILE .mega-linter.yml AT THE ROOT OF YOUR REPOSITORY
          # DISABLE: COPYPASTE,SPELL # Uncomment to disable copy-paste and spell checks

      # Upload Mega-Linter artifacts
      - name: Archive production artifacts
        if: ${{ success() }} || ${{ failure() }}
        uses: actions/[email protected]
        with:
          name: Mega-Linter reports
          path: |
            report
            mega-linter.log

      # Create pull request if applicable (for now works only on PR from same repository, not from forks)
      - name: Create Pull Request with applied fixes
        id: cpr
        if: steps.ml.outputs.has_updated_sources == 1 && (env.APPLY_FIXES_EVENT == 'all' || env.APPLY_FIXES_EVENT == github.event_name) && env.APPLY_FIXES_MODE == 'pull_request' && (github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository) && !contains(github.event.head_commit.message, 'skip fix')
        uses: peter-evans/[email protected]
        with:
          token: ${{ secrets.PAT || secrets.GITHUB_TOKEN }}
          commit-message: "[Mega-Linter] Apply linters automatic fixes"
          title: "[Mega-Linter] Apply linters automatic fixes"
          labels: bot
      - name: Create PR output
        if: steps.ml.outputs.has_updated_sources == 1 && (env.APPLY_FIXES_EVENT == 'all' || env.APPLY_FIXES_EVENT == github.event_name) && env.APPLY_FIXES_MODE == 'pull_request' && (github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository) && !contains(github.event.head_commit.message, 'skip fix')
        run: |
          echo "Pull Request Number - ${{ steps.cpr.outputs.pull-request-number }}"
          echo "Pull Request URL - ${{ steps.cpr.outputs.pull-request-url }}"

      # Push new commit if applicable (for now works only on PR from same repository, not from forks)
      - name: Prepare commit
        if: steps.ml.outputs.has_updated_sources == 1 && (env.APPLY_FIXES_EVENT == 'all' || env.APPLY_FIXES_EVENT == github.event_name) && env.APPLY_FIXES_MODE == 'commit' && github.ref != 'refs/heads/master' && (github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository) && !contains(github.event.head_commit.message, 'skip fix')
        run: sudo chown -Rc $UID .git/
      - name: Commit and push applied linter fixes
        if: steps.ml.outputs.has_updated_sources == 1 && (env.APPLY_FIXES_EVENT == 'all' || env.APPLY_FIXES_EVENT == github.event_name) && env.APPLY_FIXES_MODE == 'commit' && github.ref != 'refs/heads/master' && (github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository) && !contains(github.event.head_commit.message, 'skip fix')
        uses: stefanzweifel/[email protected]
        with:
          branch: ${{ github.event.pull_request.head.ref || github.head_ref || github.ref }}
          commit_message: "[Mega-Linter] Apply linters fixes"

Azure

Use the following Azure workflow template

You may activate File.io reporter or E-mail reporter to access detailed logs and fixed source

  - job: megalinter
    displayName: Mega-Linter
    pool:
      vmImage: ubuntu-latest
    steps:
    - script: |
        docker pull nvuillam/mega-linter:v4
        docker run -v $(System.DefaultWorkingDirectory):/tmp/lint nvuillam/mega-linter
      displayName: 'Code Scan using Mega-Linter'

Jenkins

Add the following stage in your Jenkinsfile

You may activate File.io reporter or E-mail reporter to access detailed logs and fixed source

// Lint with Mega-Linter: https://nvuillam.github.io/mega-linter/
stage('Mega-Linter') {
    agent {
        docker {
            image 'nvuillam/mega-linter:v4'
            args "-e VALIDATE_ALL_CODEBASE=true -v ${WORKSPACE}:/tmp/lint --entrypoint=''"
            reuseNode true
        }
    }
    steps {
        sh '/entrypoint.sh'
    }
}

GitLab

Create or update .gitlab-ci.yml file at the root of your repository

# Mega-Linter GitLab CI job configuration file
# More info at https://nvuillam.github.io/mega-linter

mega-linter:
  stage: test
  # You can override Mega-Linter flavor used to have faster performances
  # More info at https://nvuillam.github.io/mega-linter/flavors/
  image: nvuillam/mega-linter-python:v4
  script: [ "true" ]
  variables:
    # All available variables are described in documentation
    # https://nvuillam.github.io/mega-linter/configuration/
    DEFAULT_WORKSPACE: $CI_PROJECT_DIR
    DEFAULT_BRANCH: master
    # ADD YOUR CUSTOM ENV VARIABLES HERE TO OVERRIDE VALUES OF .mega-linter.yml AT THE ROOT OF YOUR REPOSITORY
  artifacts:
    when: always
    paths:
      - report
    expire_in: 1 week

Screenshot

Concourse

Pipeline step

Use the following job.step in your pipeline template

Note: make sure you have job.plan.get step which gets repo containing your repository as shown in example

---

  - name: linting
    plan:
      - get: repo
      - task: linting
        config:
          platform: linux
          image_resource:
            type: docker-image
            source:
              repository: nvuillam/mega-linter
              tag: v4
          inputs:
            - name: repo
          run:
            path: bash
            args:
            - -cxe
            - |
              cd repo
              export DEFAULT_WORKSPACE=$(pwd)
              bash -ex /entrypoint.sh
              ## doing this because concourse does not work as other CI systems
          # params:
            # PARALLEL: true
            # DISABLE: SPELL
            # APPLY_FIXES: all
            # DISABLE_ERRORS: true
            # VALIDATE_ALL_CODEBASE: true
            # DEFAULT_BRANCH: master

OR

Use it as reusable task

Create reusable concourse task which can be used with multiple pipelines

  1. Create task file task-linting.yaml
---
platform: linux
image_resource:
  type: docker-image
  source:
    repository: nvuillam/mega-linter
    tag: v4

inputs:
- name: repo

## uncomment this if you want reports as task output
# output:
# - name: reports
#   path: repo/report

run:
  path: bash
  args:
  - -cxe
  - |
    cd repo
    export DEFAULT_WORKSPACE=$(pwd)
    bash -ex /entrypoint.sh
  1. Use that task-linting.yaml task in pipeline

Note:

  1. make sure task-linting.yaml is available in that repo input at root

  2. task output is not shown here

resources:

  - name: linting
    plan:
      - get: repo
      - task: linting
        file: repo/task-linting.yaml
        # params:
        #   PARALLEL: true
        #   DISABLE: SPELL
        #   APPLY_FIXES: all
        #   DISABLE_ERRORS: true
        #   VALIDATE_ALL_CODEBASE: true
        #   DEFAULT_BRANCH: master

Run Mega-Linter locally

Version Downloads/week Downloads/total

You can use mega-linter-runner to locally run Mega-Linter with the same configuration defined in .mega-linter.yml file

See mega-linter-runner installation instructions

Example

npx mega-linter-runner --flavor salesforce -e 'ENABLE=,DOCKERFILE,MARKDOWN,YAML' -e 'SHOW_ELAPSED_TIME=true'

Note: You can also use such command line from your custom CI/CD pipelines

Configuration

Mega-Linter configuration variables can be defined in a .mega-linter.yml file at the root of the repository or with environment variables. You can see an example config file in this repo: .mega-linter.yml

Configuration is assisted with auto-completion and validation in most commonly used IDEs, thanks to JSON schema stored on schemastore.org

Assisted configuration

Common variables

ENV VAR Default Value Notes
ADDITIONAL_EXCLUDED_DIRECTORIES [] List of additional excluded directory basenames. They are excluded at any nested level.
APPLY_FIXES none Activates formatting and auto-fixing (more info)
DEFAULT_BRANCH master The name of the repository default branch. Warning: In new github repositories, master branch is named main, so you need to override this value with main
DEFAULT_WORKSPACE /tmp/lint The location containing files to lint if you are running locally.
DISABLE_ERRORS false Flag to have the linter complete with exit code 0 even if errors were detected.
DISABLE List of disabled descriptors keys (more info)
DISABLE_LINTERS List of disabled linters keys (more info)
ENABLE List of enabled descriptors keys (more info)
ENABLE_LINTERS List of enabled linters keys (more info)
EXCLUDED_DIRECTORIES [...many values...] List of excluded directory basenames. They are excluded at any nested level.
EXTENDS Base mega-linter.yml config file(s) to extend local configuration from. Can be a single URL or a list of .mega-linter.yml config files URLs
FAIL_IF_MISSING_LINTER_IN_FLAVOR false If set to true, Mega-Linter fails if a linter is missing in the selected flavor
FILTER_REGEX_EXCLUDE none Regular expression defining which files will be excluded from linting (more info) .ex: .*src/test.*)
FILTER_REGEX_INCLUDE all Regular expression defining which files will be processed by linters (more info) .ex: .*src/.*)
FLAVOR_SUGGESTIONS true Provides suggestions about different Mega-Linter flavors to use to improve runtime performances
FORMATTERS_DISABLE_ERRORS true Formatter errors will be reported as errors (and not warnings) if this variable is set to false
GITHUB_WORKSPACE `` Base directory for REPORT_OUTPUT_FOLDER, for user-defined linter rules location, for location of linted files if DEFAULT_WORKSPACE is not set
JAVASCRIPT_DEFAULT_STYLE standard Javascript default style to check/apply. standard,prettier
LINTER_RULES_PATH .github/linters Directory for all linter configuration rules.
Can be a local folder or a remote URL (ex: https://raw.githubusercontent.com/some_org/some_repo/mega-linter-rules )
LOG_FILE mega-linter.log The file name for outputting logs. All output is sent to the log file regardless of LOG_LEVEL.
LOG_LEVEL INFO How much output the script will generate to the console. One of INFO, DEBUG, WARNING or ERROR.
MARKDOWN_DEFAULT_STYLE markdownlint Markdown default style to check/apply. markdownlint,remark-lint
MEGALINTER_CONFIG .mega-linter.yml Name of Mega-Linter configuration file. Can be defined remotely, in that case set this environment variable with the remote URL of .mega-linter.yml config file
PARALLEL true Process linters in parallel to improve overall Mega-Linter performance. If true, linters of same language or formats are grouped in the same parallel process to avoid lock issues if fixing the same files
PLUGINS [] List of plugin urls to install and run during Mega-Linter run
POST_COMMANDS [] Custom bash commands to run after linters
PRE_COMMANDS [] Custom bash commands to run before linters
PRINT_ALPACA true Enable printing alpaca image to console
REPORT_OUTPUT_FOLDER ${GITHUB_WORKSPACE}/report Directory for generating report files
SHOW_ELAPSED_TIME false Displays elapsed time in reports
SHOW_SKIPPED_LINTERS true Displays all disabled linters mega-linter could have run
TYPESCRIPT_DEFAULT_STYLE standard Typescript default style to check/apply. standard,prettier
VALIDATE_ALL_CODEBASE true Will parse the entire repository and find all files to validate across all types. NOTE: When set to false, only new or edited files will be parsed for validation.

Activation and deactivation

Mega-Linter have all linters enabled by default, but allows to enable only some, or disable only some

  • If ENABLE is not set, all descriptors are activated by default. If set, all linters of listed descriptors will be activated by default
  • If ENABLE_LINTERS is set, only listed linters will be processed
  • If DISABLE is set, the linters in the listed descriptors will be skipped
  • If DISABLE_LINTERS is set, the listed linters will be skipped

Examples:

  • Run all javascript and groovy linters except STANDARD javascript linter
ENABLE: JAVASCRIPT,GROOVY
DISABLE_LINTERS: JAVASCRIPT_STANDARD
  • Run all linters except PHP linters (PHP_BUILTIN, PHP_PCPCS, PHP_STAN, PHP_PSALM)
DISABLE: PHP
  • Run all linters except PHP_STAN and PHP_PSALM linters
DISABLE_LINTERS: PHP_STAN,PHP_PSALM

Filter linted files

If you need to lint only a folder or exclude some files from linting, you can use optional environment parameters FILTER_REGEX_INCLUDE and FILTER_REGEX_EXCLUDE You can apply filters to a single linter by defining variable <LINTER_KEY>_FILTER_REGEX_INCLUDE and <LINTER_KEY>_FILTER_REGEX_EXCLUDE

Examples:

  • Lint only src folder: FILTER_REGEX_INCLUDE: (src/)
  • Do not lint files inside test and example folders: FILTER_REGEX_EXCLUDE: (test/|examples/)
  • Do not lint javascript files inside test folder: FILTER_REGEX_EXCLUDE: (test/.*\.js)

Apply fixes

Mega-linter is able to apply fixes provided by linters. To use this capability, you need 3 env variables defined at top level

  • APPLY_FIXES: all to apply fixes of all linters, or a list of linter keys (ex: JAVASCRIPT_ES,MARKDOWN_MARKDOWNLINT)

Only for GitHub Action Workflow file if you use it:

  • APPLY_FIXES_EVENT: all, push, pull_request, none (use none in case of use of Updated sources reporter)
  • APPLY_FIXES_MODE: commit to create a new commit and push it on the same branch, or pull_request to create a new PR targeting the branch.

Notes:

  • You can use Updated sources reporter if you do not want fixes to be automatically applied on git branch, but download them in a zipped file and manually extract them in your project

  • If used, APPLY_FIXES_EVENT and APPLY_FIXES_MODE can not be defined in .mega-linter.ymlconfig file, they must be set as environment variables

  • If you use APPLY_FIXES, add the following line in your .gitignore file

report/

Linter specific variables

See variables related to a single linter behavior in linters documentations

Pre-commands

Mega-Linter can run custom commands before running linters (for example, installing an plugin required by one of the linters you use)

Example in .mega-linter.yml config file

PRE_COMMANDS:
  - command: npm install eslint-plugin-whatever
    cwd: "root"        # Will be run at the root of Mega-Linter docker image
  - command: echo "pre-test command has been called"
    cwd: "workspace"   # Will be run at the root of the workspace (usually your repository root)

Post-commands

Mega-Linter can run custom commands after running linters (for example, running additional tests)

Example in .mega-linter.yml config file

POST_COMMANDS:
  - command: npm run test
    cwd: "workspace"   # Will be run at the root of the workspace (usually your repository root)

Reporters

Mega-Linter can generate various reports that you can activate / deactivate and customize

Reporter Description Default
Text files Generates One log file by linter + suggestions for fixes that can not be automated Active
Pull Request comments Mega-Linter posts a comment on the PR with a summary of lint results, and links to detailed logs Active if GitHub Action
Updated sources Zip containing all formatted and auto-fixed sources so you can extract them in your repository Active
GitHub Status One GitHub status by linter on the PR, with links to detailed logs Active if GitHub Action
File.io Send reports on file.io so you can access them with a simple hyperlink provided at the end of console log Inactive
Email Receive all reports on your e-mail, if you can not use artifacts Active
TAP files One file by linter following Test Anything Protocol format Active
Console Execution logs visible in console with summary table and links to other reports at the end Active

Flavors

To improve run performances, we generate Flavored Mega-Linter images containing only the list of linters related to a project type

  • When using default Mega-Linter, if a Mega-Linter Flavor would cover all your project requirements, a message is added in the logs
  • If your project uses a Mega-Linter Flavor not covering linter requirements, an error message will be thrown with instructions about how to solve the issue
Flavor Description Embedded linters Info
all Default Mega-Linter Flavor 88 Docker Image Size (tag) Docker Pulls
ci_light Optimized for CI items (Dockerfile, Jenkinsfile, JSON/YAML schemas,XML 13 Docker Image Size (tag) Docker Pulls
dart Optimized for DART based projects 39 Docker Image Size (tag) Docker Pulls
documentation Mega-Linter for documentation projects 38 Docker Image Size (tag) Docker Pulls
dotnet Optimized for C, C++, C# or VB based projects 44 Docker Image Size (tag) Docker Pulls
go Optimized for GO based projects 40 Docker Image Size (tag) Docker Pulls
java Optimized for JAVA based projects 39 Docker Image Size (tag) Docker Pulls
javascript Optimized for JAVASCRIPT or TYPESCRIPT based projects 47 Docker Image Size (tag) Docker Pulls
php Optimized for PHP based projects 42 Docker Image Size (tag) Docker Pulls
python Optimized for PYTHON based projects 45 Docker Image Size (tag) Docker Pulls
ruby Optimized for RUBY based projects 39 Docker Image Size (tag) Docker Pulls
rust Optimized for RUST based projects 39 Docker Image Size (tag) Docker Pulls
salesforce Optimized for Salesforce based projects 41 Docker Image Size (tag) Docker Pulls
scala Optimized for SCALA based projects 39 Docker Image Size (tag) Docker Pulls
swift Optimized for SWIFT based projects 39 Docker Image Size (tag) Docker Pulls
terraform Optimized for TERRAFORM based projects 42 Docker Image Size (tag) Docker Pulls

If you need a new flavor, post an issue 😉

Badge

You can show Mega-Linter status with a badge in your repository README

Mega-Linter

If your main branch is main , replace master by main in URLs

Markdown

  • Format
[![Mega-Linter](https://github.com/<OWNER>/<REPOSITORY>/workflows/Mega-Linter/badge.svg?branch=master)](https://github.com/<OWNER>/<REPOSITORY>/actions?query=workflow%3AMega-Linter+branch%3Amaster)
  • Example
[![Mega-Linter](https://github.com/nvuillam/npm-groovy-lint/workflows/Mega-Linter/badge.svg?branch=master)](https://github.com/nvuillam/npm-groovy-lint/actions?query=workflow%3AMega-Linter+branch%3Amaster)

reStructuredText

  • Format
.. |Mega-Linter yes| image:: https://github.com/<OWNER>/<REPOSITORY>/workflows/Mega-Linter/badge.svg?branch=master
   :target: https://github.com/<OWNER>/<REPOSITORY>/actions?query=workflow%3AMega-Linter+branch%3Amaster
  • Example
.. |Mega-Linter yes| image:: https://github.com/nvuillam/npm-groovy-lint/workflows/Mega-Linter/badge.svg?branch=master
   :target: https://github.com/nvuillam/npm-groovy-lint/actions?query=workflow%3AMega-Linter+branch%3Amaster

Note: IF you did not use Mega-Linter as GitHub Action name, please read GitHub Actions Badges documentation{target=_blank}

Plugins

Use plugins

Just add plugin URLs in PLUGINS property of .mega-linter.yml

Example

PLUGINS:
  - https://raw.githubusercontent.com/nvuillam/mega-linter/master/.automation/test/mega-linter-plugin-test/test.megalinter-descriptor.yml
  - https://raw.githubusercontent.com/cookiejar/mega-linter-plugin-cookietemple/master/cookietemple.megalinter-descriptor.yml

Create plugins

You can implement your own descriptors and load them as plugins during Mega-Linter runtime

Limitations

  • For now, the only install attributes managed are dockerfile instructions starting by RUN

Frequently Asked Questions

My repo CI already have linters and they are perfectly working, so why do I need Mega-Linter ?

You can perfectly continue using your installed linters and deactivate them in .mega-linter.yml. For example, in a javascript project using eslint, you can configure Mega-Linter with DISABLE: JAVASCRIPT. That way, you will benefit from both your installed linters but also from other Mega-Linter linters checking JSON, YAML, Markdown, Dockerfile, Bash, spelling mistakes, dead URLs...

Ok but... how does it work ?

Mega-Linter is based on Docker images containing either all linters, or just a selection of linters if you are using a Mega-Linter flavor for a project using a specific language / format

The core architecture does the following:

  • Initialization
    • List all project files:
      • except files in ignored folders (node_modules, etc...)
      • except files not matching FILTER_REGEX_INCLUDE (if defined by user)
      • except files matching FILTER_REGEX_EXCLUDE (if defined by user)
    • Collect files for each activated linter, matching their own filtering criteria:
      • file extensions
      • file names
      • file content
      • <descriptor_or_linter_key>_FILTER_REGEX_INCLUDE (if defined by user)
      • <descriptor_or_linter_key>_FILTER_REGEX_EXCLUDE (if defined by user)
  • Linting
    • Parallelly, for each linter with matching files:
      • Call the linter on matching files (or the whole project for some linters like copy-paste detector)
      • Call activated linter-level reporters (GitHub Status Reporter...)
  • Finalization
    • Call activated global level reporters (GitHub Pull Request Comment Reporter, File.io Reporter, Email Reporter...)
    • Manage return code:
      • 0 if no error (or only non blocking errors if user defined DISABLE_ERRORS or <descriptor_or_linter_key>_DISABLE_ERRORS)
      • 1 if errors

How to contribute

Contributions to Mega-Linter are very welcome, the more we are, the stronger Mega-Linter is ! Please follow Contributing Guide

To help, you can also:

Special thanks

Contributors

Sites referring to Mega-Linter

Global

Articles

Linters

Open-source teams

Mega-Linter obviously would not exist without its linters and libraries, so many thanks to all the dedicated Open-Source teams maintaining all these awesome linters !

Super-Linter team

Mega-Linter has been built on the ashes of a rejected Pull Request{target=_blank} on GitHub Super-Linter{target=_blank}.

Even if I disagree with their decision to remain in bash, the core team has always been nice and supporting during the time I was a Super-Linter contributor{target=_blank} :)

License

Mega-Linter vs Super-Linter

The hard-fork of Super-Linter to be rewritten in Python is not just a language switch: use of python flexibility and libraries allowed to define lots of additional functions described below

Performances

  • Mega-Linter Flavors allow to use smaller docker images, so the pull time is reduced
  • Thanks to python multiprocessing capabilities, linters are run in parallel, which is way faster than Super-Linter bash script who runs all linters in sequence
  • When the linter allows it, call it 1 time with N files, instead of calling N times with one file

More languages and formats linted

  • C, C++, Copy-Paste detection, GraphQL, JSON & YAML with JSON schemas, Markdown tables formatting, Puppet, reStructuredText, Rust, Scala, Spell checker, Swift, Visual Basic .NET ...

Automatically apply formatting and fixes

Mega-Linter can automatically apply fixes performed by linters, and push them to the same branch, or create a Pull Request that you can validate

This is pretty handy, especially for linter errors related to formatting (in that case, you don't have any manual update to perform)

Run locally

Mega-Linter can be run locally thanks to mega-linter-runner

Reports

Capabilities

  • Accuracy: Count the total number of errors and not only the number of files in error
  • Show linter version and applied filters for each linter processed
  • Reports stored as artefacts on GitHub Action run or other remote files
    • General log
    • One report file by linter

Additional Reporters

Screenshot

Screenshot

Enhanced Configuration

  • Assisted installation and configuration using a yeoman generator and JSON schemas for configuration file

Runner Install

Assisted configuration

  • Configure include and exclude regexes for a single language or linter: ex: JAVASCRIPT_FILTER_REGEX_INCLUDE (src)
  • Configure additional CLI arguments for a linter: ex: JAVASCRIPT_ES_ARGUMENTS "--debug --env-info"
  • Configure non blocking errors for a single language or linter: ex: JAVASCRIPT_DISABLE_ERRORS
  • Simplify languages and linters variables
    • ENABLE = list of languages and formats to apply lint on codebase (default: all)
    • ENABLE_LINTERS = list of linters to apply lint on codebase (default: all)
    • DISABLE = list of languages and formats to skip (default: none)
    • DISABLE_LINTERS = list of linters to skip (default: none)
    • Variables VALIDATE_XXX are still taken in account (but should not be used in association with ENABLE and DISABLE variables)

Enhanced Documentation

HTML doc home

  • One page per linter documentation :
    • All variables that can be used with this linter
    • List of file extensions, names and filters applied by the linter
    • Link to Mega-Linter default linter configuration
    • Link to linter Web-Site
    • Link to official page explaining how to customize the linter rules
    • Link to official page explaining how to disable rules from source comments
    • Examples of linter command line calls behind the hood
    • Help command text
    • Installation commands

HTML doc linter

  • Installation links for related IDEs

HTML doc IDE

  • README
    • Separate languages, formats and tooling formats in the linters table
    • Add logos for each descriptor

Plugins management

For linters less commonly used, Mega-Linters offers a plugins architecture so anyone can publish plugins

Simplify architecture and evolutive maintenance

  • Refactoring runtime in Python, for easier handling than bash thanks to classes and python modules
  • Everything related to each linter in a single descriptor YML file
    • easier evolutive maintenance
    • less conflicts to manage between PRs.
    • Few special cases require a python linter class)
  • Default behaviours for all linters, with possibility to override part of them for special cases
  • Hierarchical architecture: Apply fixes and new behaviours to all linters with a single code update
  • Documentation as code
    • Generate linters tables (ordered by type: language, format & tooling format) and include it in README. (see result)
    • Generate one markdown file per Linter, containing all configuration variables, infos and examples (See examples)
  • Automatic generation of Dockerfile using YML descriptors, always using the linter latest version
    • Dockerfile commands (FROM, ARG, ENV, COPY, RUN )
    • APK packages (linux)
    • NPM packages (node)
    • PIP packages (python)
    • GEM packages (ruby)
    • Phive packages (PHP)
  • Have a centralized exclude list (node_modules,.rbenv, etc...)

Improve robustness & stability

  • Test classes for each capability
  • Test classes for each linter: Automatic generation of test classes using .automation/build.py
  • Setup code coverage codecov
  • Development CD / CI
    • Validate multi-status on PR inside each PR (posted from step "Run against all code base")
    • Run test classes and code coverage with pytest during validation GitHub Action
    • Validate descriptor YML files with json schema during build
    • Automated job to upgrade linters to their latest stable version

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
python (54,453) 
java (31,533) 
rust (4,726) 
golang (3,881) 
kotlin (3,666) 
scala (2,624) 
markdown (869) 
groovy (651) 
terraform (402) 
github-actions (248) 
linter (243) 
ci (241) 
jenkins (177) 
code-quality (86) 
formatting (34) 
linters (16)