MegaLinter is an Open-Source tool for CI/CD workflows that analyzes the consistency of your code, IAC, configuration, and scripts in your repository sources, to ensure all your projects sources are clean and formatted whatever IDE/toolbox is used by their developers, powered by OX Security.
Supporting 53 languages, 24 formats, 21 tooling formats and 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
Process
Console reporter
Github PR reporter
- 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
- Run
npx mega-linter-runner --installto 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@v3byoxsecurity/megalinter@v6in 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
All linters are integrated in the MegaLinter docker image, which is frequently upgraded with their latest versions
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 :)
- Run
npx mega-linter-runner --upgradeto automatically upgrade your configuration from v4 or v5 to v6 :)
The following instructions examples are using latest MegaLinter stable version (v6 , always corresponding to the latest release)
- Docker image:
oxsecurity/megalinter:v6 - GitHub Action:
oxsecurity/megalinter@v6
You can also use beta version (corresponding to the content of main branch)
- Docker image:
oxsecurity/megalinter:beta - GitHub Action:
oxsecurity/megalinter@beta
- 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_URLenvironment 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@v3
with:
token: ${{ secrets.PAT || secrets.GITHUB_TOKEN }}
fetch-depth: 0 # If you use VALIDATE_ALL_CODEBASE = true, you can remove this line to improve performances
# MegaLinter
- name: MegaLinter
id: ml
# You can override MegaLinter flavor used to have faster performances
# More info at https://megalinter.github.io/flavors/
uses: oxsecurity/megalinter@v6
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@v3
with:
name: MegaLinter reports
path: |
megalinter-reports
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@v4
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"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: oxsecurity/megalinter:v6
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:
- megalinter-reports
expire_in: 1 weekCreate a Gitlab access token and define it in a variable GITLAB_ACCESS_TOKEN_MEGALINTER in the project CI/CD masked variables
Use the following Azure Pipelines YAML template
Add the following job in your azure-pipelines.yaml file
# Run MegaLinter to detect linting and security issues
- job: MegaLinter
pool:
vmImage: ubuntu-latest
steps:
# Pull MegaLinter docker image
- script: docker pull oxsecurity/megalinter:v6
displayName: Pull MegaLinter
# Run MegaLinter
- script: |
docker run -v $(System.DefaultWorkingDirectory):/tmp/lint \
-e GIT_AUTHORIZATION_BEARER=$(System.AccessToken) \
-e CI=true \
-e TF_BUILD=true \
-e SYSTEM_ACCESSTOKEN=$(System.AccessToken) \
-e SYSTEM_COLLECTIONURI=$(System.CollectionUri) \
-e SYSTEM_PULLREQUEST_PULLREQUESTID=$(System.PullRequest.PullRequestId) \
-e SYSTEM_TEAMPROJECT="$(System.TeamProject)" \
-e BUILD_BUILD_ID=$(Build.BuildId) \
-e BUILD_REPOSITORY_ID=$(Build.Repository.ID) \
oxsecurity/megalinter:v6
displayName: Run MegaLinter
# Upload MegaLinter reports
- task: PublishPipelineArtifact@1
condition: succeededOrFailed()
displayName: Upload MegaLinter reports
inputs:
targetPath: "$(System.DefaultWorkingDirectory)/megalinter-reports/"
artifactName: MegaLinterReportTo benefit from Pull Request comments, please follow configuration instructions
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 'oxsecurity/megalinter:v6'
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,megalinter-reports/**/*', defaultExcludes: false, followSymlinks: false
}
}
}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: oxsecurity/megalinter
tag: v6
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: trueOR
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: oxsecurity/megalinter
tag: v6
inputs:
- name: repo
## uncomment this if you want reports as task output
# output:
# - name: reports
# path: repo/megalinter-reports
run:
path: bash
args:
- -cxe
- |
cd repo
export DEFAULT_WORKSPACE=$(pwd)
bash -ex /entrypoint.sh- Use that
task-linting.yamltask in pipeline
Note:
-
make sure
task-linting.yamlis available in thatrepoinput at root -
task
outputis 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: trueWarning: Drone CI support is experimental and is undergoing heavy modifications (see issue #2047).
-
Create a
.drone.ymlfile on the root directory of your repository -
Copy and paste the following template:
kind: pipeline
type: docker
name: MegaLinter
workspace:
path: /tmp/lint
steps:
- name: megalinter
image: oxsecurity/megalinter:v6
environment:
DEFAULT_WORKSPACE: /tmp/lintThis uses the Drone CI docker runner, so it's needed to install and configure it beforehand on your Drone CI server.
The Drone CI workflow should trigger automatically for every scenario (push, pull request, sync...) however, you can optionally change this behavior by changing the trigger. For example:
kind: pipeline
type: docker
name: MegaLinter
workspace:
path: /tmp/lint
steps:
- name: megalinter
image: oxsecurity/megalinter:v6
environment:
DEFAULT_WORKSPACE: /tmp/lint
trigger:
event:
- pushThe workflow above should only trigger on push, not on any other situation. For more information about how to configure Drone CI trigger rules, click here.
You can also run megalinter with its Docker container, just execute this command:
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock:rw -v $(pwd):/tmp/lint:rw oxsecurity/megalinter:v6
No extra arguments are needed, however, megalinter will lint all of the files inside the /tmp/lint folder, so it may be needed to configure your tool of choice to use the /tmp/lint folder as workspace.
This can also be changed:
Example:
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock:rw -v $(pwd):/example/folder:rw oxsecurity/megalinter:v6
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 in your custom CI/CD pipelines
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
| 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) |
| CLEAR_REPORT_FOLDER | false |
Flag to clear files from report folder (usually megalinter-reports) before starting the linting process |
| 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) | |
| DISABLE_ERRORS_LINTERS | List of enabled but not blocking 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. Later files take precedence. |
|
| FAIL_IF_MISSING_LINTER_IN_FLAVOR | false |
If set to true, MegaLinter fails if a linter is missing in the selected flavor |
| FAIL_IF_UPDATED_SOURCES | false |
If set to true, MegaLinter fails if a linter or formatter has auto-fixed sources, even if there are no errors |
| 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. Use none to not generate this file. |
| 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 |
| MEGALINTER_FILES_TO_LINT | [] | Comma-separated list of files to analyze. Using this variable will bypass other file listing methods |
| 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 | false |
Display all files analyzed by the linter instead of only the number |
| REPORT_OUTPUT_FOLDER | ${GITHUB_WORKSPACE}/megalinter-reports |
Directory for generating report files. Set to none to not generate reports |
| SHOW_ELAPSED_TIME | false |
Displays elapsed time in reports |
| SHOW_SKIPPED_LINTERS | true |
Displays all disabled linters mega-linter could have run |
| SKIP_CLI_LINT_MODES | [] | Comma-separated list of cli_lint_modes. To use if you want to skip linters with some CLI lint modes (ex: file,project). Available values: file,cli_lint_mode,project. |
| 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. |
MegaLinter have all linters enabled by default, but allows to enable only some, or disable only some
- If
ENABLEis not set, all descriptors are activated by default. If set, all linters of listed descriptors will be activated by default - If
ENABLE_LINTERSis set, only listed linters will be processed - If
DISABLEis set, the linters in the listed descriptors will be skipped - If
DISABLE_LINTERSis set, the listed linters will be skipped - If
DISABLE_ERRORS_LINTERSis set, the listed linters will be run, but if errors are found, they will be considered as non blocking
Examples:
- Run all javascript and groovy linters except STANDARD javascript linter. DevSkim errors will be non-blocking
ENABLE: JAVASCRIPT,GROOVY
DISABLE_LINTERS: JAVASCRIPT_STANDARD
DISABLE_ERRORS_LINTERS: REPOSITORY_DEVSKIM- 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_PSALMIf 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)
Warning: not applicable with linters using CLI lint mode project (see details)
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:
allto 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:
committo create a new commit and push it on the same branch, orpull_requestto 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
megalinter-reports/- 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
See variables related to a single linter behavior in linters documentations
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)
- command: pip install flake8-cognitive-complexity
venv: flake8 # Will be run within flake8 python virtualenv. There is one virtualenv per python-based linter, with the same nameMegaLinter 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)Each linter has a lint mode by default, visible in its MegaLinter documentation (example):
list_of_files: All files are sent in single call to the linterproject: The linter is called from the root of the project, without specifying any file namefile: The linter is called once by file (so the performances may not be very good)
You can override the CLI_LINT_MODE by using configuration variable for each linter (see linters documentation)
- Linters with
filedefault lint mode can not be overridden tolist_of_files - Linters with
projectdefault lint mode can not be overridden tolist_of_filesorfile
Allowing file or list_of_files to be overridden to project is mostly for workarounds, for example with linters that have a problem to find their config file when the current folder is not the repo root.
Special considerations:
- As list of files is not sent to the linter command, linters using
projectlint mode do not take in account some variables like FILTER_REGEX_INCLUDE and FILTER_REGEX_EXCLUDE. For those linters, you must check their documentation to define ignore configuration as it is awaited by the linter (for example with a.secretlintignorefile for secretlint)
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 |
| SARIF (beta) | Generates an aggregated SARIF output file | Inactive |
| 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 |
| Azure Pipelines Pull Request comments | Mega-Linter posts a comment on the PR with a summary of lint results, and links to detailed logs | Active if in Azure Pipelines |
| 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 |
| 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 |
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 & v5 images.
| Flavor | Description | Embedded linters | Info | |
|---|---|---|---|---|
 |
all | Default MegaLinter Flavor | 112 |   |
| ci_light | Optimized for CI items (Dockerfile, Jenkinsfile, JSON/YAML schemas,XML | 20 |   |
|
| cupcake | MegaLinter for the most commonly used languages | 80 |   |
|
| documentation | MegaLinter for documentation projects | 47 |   |
|
| dotnet | Optimized for C, C++, C# or VB based projects | 59 |   |
|
| go | Optimized for GO based projects | 49 |   |
|
| java | Optimized for JAVA based projects | 50 |   |
|
| javascript | Optimized for JAVASCRIPT or TYPESCRIPT based projects | 56 |   |
|
| php | Optimized for PHP based projects | 50 |   |
|
| python | Optimized for PYTHON based projects | 57 |   |
|
| ruby | Optimized for RUBY based projects | 47 |   |
|
| rust | Optimized for RUST based projects | 47 |   |
|
| salesforce | Optimized for Salesforce based projects | 50 |   |
|
| security | Optimized for security | 21 |   |
|
| swift | Optimized for SWIFT based projects | 47 |   |
|
| terraform | Optimized for TERRAFORM based projects | 52 |   |
If you need a new flavor, post an issue 😉
You can show MegaLinter status with a badge in your repository README
If your main branch is main , replace main by main in URLs
- Format
[](https://github.com/<OWNER>/<REPOSITORY>/actions?query=workflow%3AMegaLinter+branch%3Amain)- Example
[](https://github.com/nvuillam/npm-groovy-lint/actions?query=workflow%3AMegaLinter+branch%3Amain)- 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%3AmainNote: IF you did not use MegaLinter as GitHub Action name, please read GitHub Actions Badges documentation{target=_blank}
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 !
Add plugin URLs in PLUGINS property of .mega-linter.yml. URLs must either begin with "https://" or take the form of "file://<path>", where <path> points to a valid plugin descriptor file.
Note: Both <path> and the default mount directory (/tmp/lint/<path>) will be checked for a valid descriptor.
PLUGINS:
- https://raw.githubusercontent.com/oxsecurity/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
- file://.automation/test/mega-linter-plugin-test/test.megalinter-descriptor.yml- jupyfmt: The uncompromising Jupyter notebook formatter (usage)
- linkcheck: Plugin to check and validate markdown links exist and working.
- nitpick: Command-line tool and flake8 plugin to enforce the same settings across multiple language-independent projects. (usage)
- mustache: Plugin to validate Logstash pipeline definition files using mustache
- salt-lint: Checks Salt State files (SLS) for best practices and behavior that could potentially be improved.
Submit a PR if you want your plugin to appear here :)
You can implement your own descriptors and load them as plugins during MegaLinter runtime
- Descriptor format is exactly the same than MegaLinter embedded ones (see json schema documentation)
- Plugins descriptor files must be named **.megalinter-descriptor.yml and respect MegaLinter Json Schema
- Plugins must be hosted in a url containing **/mega-linter-plugin-**/
- File URLs must conform to the same directory and file naming criteria as defined above.
- For now, the only
installattributes managed aredockerfileinstructions starting byRUN
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)
- except files in ignored folders (
- 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)
- List all project files:
- 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...)
- Parallelly, for each linter with matching files:
- 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_ERRORSor<descriptor_or_linter_key>_DISABLE_ERRORS) - 1 if errors
- 0 if no error (or only non blocking errors if user defined
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}
- analysis-tools.dev{target=_blank}
- awesome-linters{target=_blank}
- schemastore.org{target=_blank}
- r2devops.io{target=_blank}
- abhith.net{target=_blank}
- iac-analyzers.dev/
- checkstyle{target=_blank}
- clj-kondo{target=_blank}
- cspell{target=_blank}
- djlint{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}
- lintr{target=_blank}
- markdown-link-check{target=_blank}
- npm-groovy-lint{target=_blank}
- npm-package-json-lint{target=_blank}
- pmd{target=_blank}
- rst-lint{target=_blank}
- rstcheck{target=_blank}
- rubocop{target=_blank}
- scalafix{target=_blank}
- secretlint{target=_blank}
- stylelint{target=_blank}
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 !
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} :)
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
- 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
- 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 ...
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)
MegaLinter can be run locally thanks to mega-linter-runner
- 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
- 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)
- 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
For linters less commonly used, MegaLinters offers a plugins architecture so anyone can publish plugins
- 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...)
- 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
-
Tool to upgrade user repos configuration files using
npx mega-linter-runner --upgrade(will upgrade references to nvuillam/mega-linter into oxsecurity/megalinter) -
Migration from github individual repo nvuillam/mega-linter to github organization repo oxsecurity/megalinter
-
Migration from docker hub space nvuillam to space megalinter
- Docker images are now oxsecurity/megalinter or oxsecurity/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
masterbranch intomain -
IGNORE_GITIGNORED_FILES parameter default to
true