Skip to content

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

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)
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
GIT_AUTHORIZATION_BEARER If set, calls git with Authorization: Bearer+value
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.

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
  • If DISABLE_ERRORS_LINTERS is 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_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)

Warning: not applicable with linters using CLI lint mode project (see details)

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
megalinter-reports/

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)
  - 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 name

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)

CLI lint mode

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 linter
  • project: The linter is called from the root of the project, without specifying any file name
  • file: 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 file default lint mode can not be overridden to list_of_files
  • Linters with project default lint mode can not be overridden to list_of_files or file

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 project lint 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 .secretlintignore file for secretlint)