GitHub - jon-mccormack/megalinter: 🦙 Mega-Linter analyzes 48 languages, 22 formats, 19 tooling formats, excessive copy-pastes, spelling mistakes and security issues in your repository sources with a GitHub Action, other CI tools or locally.

MegaLinter

MegaLinter is an 100% Open-Source tool for CI/CD workflows that analyzes consistency and quality of 49 languages, 22 formats, 21 tooling formats , excessive 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

See Article on Medium

Process

Console reporter

Github PR reporter

Why MegaLinter

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 MegaLinter, 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
MegaLinter documentation provides the list of IDE plugins integrating each linter, so developers know which linter and plugins to install
MegaLinter 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)
MegaLinter 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 (you need node.js to be installed)
Commit, push, and create a pull request
Watch !

Notes:

This repo is a hard-fork of GitHub Super-Linter, rewritten in python to add lots of additional features
If you are a Super-Linter user, you can transparently switch to MegaLinter and keep the same configuration (just replace github/super-linter@v3 by megalinter/megalinter@v5 in your GitHub Action YML file, like on this PR)
If you want to use MegaLinter extra features (recommended), please take 5 minutes to use MegaLinter assisted installation
For a hand-holdy example of getting started with mega-linter check out this blog post by Alec Johnson

Supported Linters

All linters are integrated in the MegaLinter 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
	phplint	PHP_PHPLINT
POWERSHELL	powershell	POWERSHELL_POWERSHELL
PYTHON	pylint	PYTHON_PYLINT
	black	PYTHON_BLACK	✔️
	flake8	PYTHON_FLAKE8
	isort	PYTHON_ISORT	✔️
	bandit	PYTHON_BANDIT
	mypy	PYTHON_MYPY
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
	tsqllint	SQL_TSQLLINT
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
ACTION	actionlint	ACTION_ACTIONLINT
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
	kubeconform	KUBERNETES_KUBECONFORM
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	✔️
	checkov	TERRAFORM_CHECKOV
	kics	TERRAFORM_KICS

Other

Code quality checker	Linter	Configuration key	Format/Fix
COPYPASTE	jscpd	COPYPASTE_JSCPD
CREDENTIALS	secretlint	CREDENTIALS_SECRETLINT
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 MegaLinter :)

Upgrade from MegaLinter v4

Run npx mega-linter-runner --upgrade to automatically upgrade your configuration to v5 :)

Manual installation

The following instructions examples are using to latest MegaLinter stable version (v5 , always corresponding to the latest release)

GitHub Action: megalinter/megalinter@v5
Docker image: megalinter/megalinter:v5

You can also use beta version (corresponding to the content of main branch)

GitHub Action: megalinter/megalinter@beta
Docker image: megalinter/megalinter:beta

GitHub Action

Create a new file in your repository called .github/workflows/mega-linter.yml
Copy the example workflow from below into that new file, no extra configuration required
Commit that file to a new branch
Open up a pull request and observe the action working
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 MegaLinter 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) , and have status on Github Pull Request if GITHUB_TARGET_URL environment variable exists.

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

---
# MegaLinter GitHub Action configuration file
# More info at https://megalinter.github.io
name: MegaLinter

on:
  # Trigger mega-linter at every push. Action will also be visible from Pull Requests to main
  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)

concurrency:
  group: ${{ github.ref }}-${{ github.workflow }}
  cancel-in-progress: true

jobs:
  build:
    name: MegaLinter
    runs-on: ubuntu-latest
    steps:
      # Git Checkout
      - name: Checkout Code
        uses: actions/checkout@v2
        with:
          token: ${{ secrets.PAT || secrets.GITHUB_TOKEN }}
          fetch-depth: 0

      # MegaLinter
      - name: MegaLinter
        id: ml
        # You can override MegaLinter flavor used to have faster performances
        # More info at https://megalinter.github.io/flavors/
        uses: megalinter/megalinter@v5
        env:
          # All available variables are described in documentation
          # https://megalinter.github.io/configuration/
          VALIDATE_ALL_CODEBASE: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }} # Validates all source when push on main, else just the git diff with main. 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 MegaLinter artifacts
      - name: Archive production artifacts
        if: ${{ success() }} || ${{ failure() }}
        uses: actions/upload-artifact@v2
        with:
          name: MegaLinter 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/create-pull-request@v3
        with:
          token: ${{ secrets.PAT || secrets.GITHUB_TOKEN }}
          commit-message: "[MegaLinter] Apply linters automatic fixes"
          title: "[MegaLinter] 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/main' && (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/main' && (github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository) && !contains(github.event.head_commit.message, 'skip fix')
        uses: stefanzweifel/git-auto-commit-action@v4
        with:
          branch: ${{ github.event.pull_request.head.ref || github.head_ref || github.ref }}
          commit_message: "[MegaLinter] Apply linters fixes"

Azure Pipelines

Use the following Azure Pipelines YAML template

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

  # Run MegaLinter to detect linting and security issues
  - job: megalinter
    displayName: MegaLinter
    pool:
      vmImage: ubuntu-latest
    steps:
    - script: |
        docker pull megalinter/megalinter:v5
        docker run -v $(System.DefaultWorkingDirectory):/tmp/lint -e GIT_AUTHORIZATION_BEARER=$(System.AccessToken) megalinter/megalinter:v5
      displayName: 'MegaLinter analysis'

    # Publish the Anchore report as an artifact to Azure Pipelines
    - task: PublishBuildArtifacts@1
      displayName: 'Publish Artifact: MegaLinter Report'
      condition: succeededOrFailed()
      inputs:
        PathtoPublish: '$(System.DefaultWorkingDirectory)/report/'
        ArtifactName: MegaLinterReport

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 MegaLinter: https://megalinter.github.io/
stage('MegaLinter') {
    agent {
        docker {
            image 'megalinter/megalinter:v5'
            args "-u root -e VALIDATE_ALL_CODEBASE=true -v ${WORKSPACE}:/tmp/lint --entrypoint=''"
            reuseNode true
        }
    }
    steps {
        sh '/entrypoint.sh'
    }
    post {
        always {
            archiveArtifacts allowEmptyArchive: true, artifacts: 'mega-linter.log,report/**/*', defaultExcludes: false, followSymlinks: false  
        }
    }
}

GitLab

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

# MegaLinter GitLab CI job configuration file
# More info at https://megalinter.github.io/

mega-linter:
  stage: test
  # You can override MegaLinter flavor used to have faster performances
  # More info at https://megalinter.github.io/flavors/
  image: megalinter/megalinter:v5
  script: [ "true" ] # if script: ["true"] does not work, you may try ->  script: [ "/bin/bash /entrypoint.sh" ]
  variables:
    # All available variables are described in documentation
    # https://megalinter.github.io/configuration/
    DEFAULT_WORKSPACE: $CI_PROJECT_DIR
    # 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

Create a Gitlab access token and define it in a variable GITLAB_ACCESS_TOKEN_MEGALINTER in the project CI/CD masked variables

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: megalinter/megalinter
              tag: v5
          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

OR

Use it as reusable task

Create reusable concourse task which can be used with multiple pipelines

Create task file task-linting.yaml

---
platform: linux
image_resource:
  type: docker-image
  source:
    repository: megalinter/megalinter
    tag: v5

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

Use that task-linting.yaml task in pipeline

Note:

make sure task-linting.yaml is available in that repo input at root
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

Run MegaLinter locally

You can use mega-linter-runner to locally run MegaLinter 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

MegaLinter 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

VsCode: You need a VsCode extension like Red Hat YAML
IDEA family: Auto-completion natively supported

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	`HEAD`	Deprecated: The name of the repository's default branch.
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`, MegaLinter 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 MegaLinter 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
IGNORE_GENERATED_FILES	`false`	If set to `true`, MegaLinter will skip files containing `@generated` marker but without `@not-generated` marker (more info at https://generated.at)
IGNORE_GITIGNORED_FILES	`true`	If set to `true`, MegaLinter will skip files ignored by git using `.gitignore` file
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 MegaLinter 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 MegaLinter 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 MegaLinter 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
PRINT_ALL_FILES	`true`	Display only the number of files processed by a linter, not all file names
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

MegaLinter 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_PHPCS, PHP_PHPSTAN, PHP_PSALM)

DISABLE: PHP

Run all linters except PHP_PHPSTAN and PHP_PSALM linters

DISABLE_LINTERS: PHP_PHPSTAN,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/

You may see github permission errors, or workflows not run on the new commit. To solve these issues:
- Create Personal Access Token, then copy the PAT value
- Define secret variable named PAT on your repository, and paste the PAT value

Linter specific variables

See variables related to a single linter behavior in linters documentations

Pre-commands

MegaLinter 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 MegaLinter 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

MegaLinter 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

MegaLinter 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
GitHub Pull Request comments	MegaLinter posts a comment on the PR with a summary of lint results, and links to detailed logs	Active if GitHub Action
Gitlab Merge Request comments	Mega-Linter posts a comment on the MR with a summary of lint results, and links to detailed logs	Active if in Gitlab CI
Updated sources	Zip containing all formatted and auto-fixed sources so you can extract them in your repository	Active
IDE Configuration	Apply MegaLinter configuration in your local IDE with linter config files and IDE extensions	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
JSON	Generates a JSON output report file	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 MegaLinter images containing only the list of linters related to a project type

When using default MegaLinter, if a MegaLinter Flavor would cover all your project requirements, a message is added in the logs
If your project uses a MegaLinter Flavor not covering linter requirements, an error message will be thrown with instructions about how to solve the issue

The following table does not display docker pulls from MegaLinter v4 images.

Flavor	Description	Embedded linters
all	Default MegaLinter Flavor	97
ci_light	Optimized for CI items (Dockerfile, Jenkinsfile, JSON/YAML schemas,XML	16
dart	Optimized for DART based projects	42
documentation	MegaLinter for documentation projects	41
dotnet	Optimized for C, C++, C# or VB based projects	48
go	Optimized for GO based projects	43
java	Optimized for JAVA based projects	43
javascript	Optimized for JAVASCRIPT or TYPESCRIPT based projects	50
php	Optimized for PHP based projects	46
python	Optimized for PYTHON based projects	49
ruby	Optimized for RUBY based projects	42
rust	Optimized for RUST based projects	42
salesforce	Optimized for Salesforce based projects	44
scala	Optimized for SCALA based projects	42
swift	Optimized for SWIFT based projects	42
terraform	Optimized for TERRAFORM based projects	47

If you need a new flavor, post an issue 😉

Badge

You can show MegaLinter status with a badge in your repository README

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

Markdown

Format

[![MegaLinter](https://github.com/<OWNER>/<REPOSITORY>/workflows/MegaLinter/badge.svg?branch=main)](https://github.com/<OWNER>/<REPOSITORY>/actions?query=workflow%3AMegaLinter+branch%3Amain)

Example

[![MegaLinter](https://github.com/nvuillam/npm-groovy-lint/workflows/MegaLinter/badge.svg?branch=main)](https://github.com/nvuillam/npm-groovy-lint/actions?query=workflow%3AMegaLinter+branch%3Amain)

reStructuredText

Format

.. |MegaLinter yes| image:: https://github.com/<OWNER>/<REPOSITORY>/workflows/MegaLinter/badge.svg?branch=main
   :target: https://github.com/<OWNER>/<REPOSITORY>/actions?query=workflow%3AMegaLinter+branch%3Amain

Example

.. |MegaLinter yes| image:: https://github.com/nvuillam/npm-groovy-lint/workflows/MegaLinter/badge.svg?branch=main
   :target: https://github.com/nvuillam/npm-groovy-lint/actions?query=workflow%3AMegaLinter+branch%3Amain

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

Plugins

For security reasons, we try to embed in MegaLinter only linters that are widely adopted by open-source community.

But any linter can be callable within MegaLinter thanks to the plugin mechanism !

Use plugins

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

Example

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

Plugins Catalog

jupyfmt: The uncompromising Jupyter notebook formatter (usage)

Submit a PR if you want your plugin to appear here :)

Create plugins

You can implement your own descriptors and load them as plugins during MegaLinter runtime

Plugins descriptor files must be named **.megalinter-descriptor.yml and respect MegaLinter Json Schema
Descriptor format is exactly the same than MegaLinter embedded ones (see json schema documentation)
Plugins must be hosted in a url containing **/mega-linter-plugin-**/

Limitations

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

Articles

Limit your technical debt and secure your code base using MegaLinter, by Nicolas Vuillamy
Linting a Jekyll blog with MegaLinter, by Alec Johnson{target=_blank}
Open-source linters landscape in 2021, by Cédric Teyton{target=_blank}
How to linter basic things like trailing whitespaces and newlines{target=_blank}, by Nicolai Antiferov{target=_blank}

Frequently Asked Questions

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

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 MegaLinter with DISABLE: JAVASCRIPT. That way, you will benefit from both your installed linters but also from other MegaLinter linters checking JSON, YAML, Markdown, Dockerfile, Bash, spelling mistakes, dead URLs...

Ok but... how does it work ?

MegaLinter is based on Docker images containing either all linters, or just a selection of linters if you are using a MegaLinter 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 MegaLinter are very welcome, the more we are, the stronger MegaLinter is ! Please follow Contributing Guide

To help, you can also:

⭐ star the repository
🍺 offer a beer !
report problems and request new features
share on twitter{target=_blank}

Special thanks

Contributors

Sites referring to MegaLinter

Global

analysis-tools.dev{target=_blank}
awesome-linters{target=_blank}
schemastore.org{target=_blank}
r2devops.io{target=_blank}

Linters

checkstyle{target=_blank}
clj-kondo{target=_blank}
cspell{target=_blank}
dotenv-linter{target=_blank}
editorconfig-checker{target=_blank}
eslint{target=_blank}
eslint-plugin-jsonc{target=_blank}
hadolint{target=_blank}
htmlhint{target=_blank}
jscpd{target=_blank}
kics{target=_blank}
ktlint{target=_blank}
markdown-link-check{target=_blank}
npm-groovy-lint{target=_blank}
rst-lint{target=_blank}
rubocop{target=_blank}
scalafix{target=_blank}
secretlint{target=_blank}
stylelint{target=_blank}

Open-source teams

MegaLinter 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

MegaLinter 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

GNU Affero General Public License

MegaLinter 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

MegaLinter 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, Credentials, GraphQL, JSON & YAML with JSON schemas, Markdown tables formatting, Puppet, reStructuredText, Rust, Scala, Spell checker, Swift, Visual Basic .NET ...

Automatically apply formatting and fixes

MegaLinter 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

MegaLinter 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

Console

Gitlab Merge Request comments

Enhanced Configuration

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

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 documentation

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 MegaLinter 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

Installation links for related IDEs

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

Plugins management

For linters less commonly used, MegaLinters 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
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

V4 versus V5

Tool to upgrade user repos configuration files using npx mega-linter-runner --upgrade (will upgrade references to nvuillam/mega-linter into megalinter/megalinter)
Migration from github individual repo nvuillam/mega-linter to github organization repo megalinter/megalinter
Migration from docker hub space nvuillam to space megalinter
- Docker images are now megalinter/megalinter or megalinter/megalinter-FLAVOR
Documentation is now hosted at https://megalinter.github.io/
Version management: Now mega-linter docker images, github action and mega-linter-runner versions are aligned
- latest for latest official release
- beta for current content of main branch
- alpha for current content of alpha branch
- docker image, github action and mega-linter-runner can still be called with exact version number
Being more inclusive: rename master branch into main
IGNORE_GITIGNORED_FILES parameter default to true

Name		Name	Last commit message	Last commit date
Latest commit History 1,470 Commits
.automation		.automation
.devcontainer		.devcontainer
.github		.github
.vscode		.vscode
TEMPLATES		TEMPLATES
docs		docs
flavors		flavors
mega-linter-runner		mega-linter-runner
megalinter		megalinter
.codecov.yml		.codecov.yml
.cspell.json		.cspell.json
.dockerfilelintrc		.dockerfilelintrc
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.eslintignore		.eslintignore
.gitattributes		.gitattributes
.gitignore		.gitignore
.hadolint.yaml		.hadolint.yaml
.jscpd.json		.jscpd.json
.markdown-link-check.json		.markdown-link-check.json
.markdownlint.json		.markdownlint.json
.mega-linter.yml		.mega-linter.yml
.secretlintignore		.secretlintignore
.trivyignore		.trivyignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
Dockerfile		Dockerfile
Dockerfile-quick		Dockerfile-quick
LICENSE		LICENSE
README.md		README.md
action.yml		action.yml
build.sh		build.sh
entrypoint.sh		entrypoint.sh
mkdocs.yml		mkdocs.yml
requirements.dev.txt		requirements.dev.txt

License

jon-mccormack/megalinter

Folders and files

Latest commit

History

Repository files navigation

MegaLinter

Table of Contents

Why MegaLinter

Quick Start

Supported Linters

Languages

Formats

Tooling formats

Other

Installation

Assisted installation

Upgrade from MegaLinter v4

Manual installation

GitHub Action

Azure Pipelines

Jenkins

GitLab

Concourse

Pipeline step

Use it as reusable task

Run MegaLinter locally

Configuration

Common variables

Activation and deactivation

Filter linted files

Apply fixes

Linter specific variables

Pre-commands

Post-commands

Reporters

Flavors

Badge

Markdown

reStructuredText

Plugins

Use plugins

Example

Plugins Catalog

Create plugins

Limitations

Articles

Frequently Asked Questions

How to contribute

Special thanks

Contributors

Sites referring to MegaLinter

Global

Linters

Open-source teams

Super-Linter team

License

MegaLinter vs Super-Linter

Performances

More languages and formats linted

Automatically apply formatting and fixes

Run locally

Reports

Capabilities

Additional Reporters

Enhanced Configuration

Enhanced Documentation

Plugins management

Simplify architecture and evolutive maintenance

Improve robustness & stability

V4 versus V5

About

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases

Packages 0

Packages