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

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

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
IGNORE_GENERATED_FILES	`false`	If set to `true`, Mega-Linter will skip files containing `@generated` marker but without `@not-generated` marker (more info at https://generated.at)
IGNORE_GITIGNORED_FILES	`false`	If set to `true`, Mega-Linter 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 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_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

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)