Configuration

MegaLinter configuration variables are 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 autocompletion 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

Activation and deactivation

MegaLinter have all linters enabled by default, but allows to enable only some, or disable only some

• If ENABLE isn't 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/)
• Don't lint files inside test and example folders: FILTER_REGEX_EXCLUDE: (test/|examples/)
• Don't 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.

Apply fixes issues

You may see github permission errors, or workflows not run on the new commit.

To solve these issues, you can apply one of the following solutions.

• Method 1: The most secured
  • Create Fine Grained Personal Access Token, scoped only on your repository and then copy the PAT value
  • Define environment secret variable named PAT on your repository, and paste the PAT value
  • Update your Github Actions Workflow to add the environment name

• Method 2: Easier, but any contributor with write access can see your Personal Access Token
  • Create Classic Personal Access Token, then copy the PAT value
  • Define secret variable named PAT on your repository, and paste the PAT value

Notes

• You can use Updated sources reporter if you don't 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)

Environment variables security

MegaLinter runs on a docker image and calls the linters via command line to gather their results.

If you run it from your CI/CD pipelines, the docker image may have access to your environment variables, that can contain secrets defined in CI/CD variables.

As it can be complicated to trust the authors of all the open-source linters, MegaLinter removes variables from the environment used to call linters.

Thanks to this feature, you only need to trust MegaLinter and its internal python dependencies, but there is no need to trust all the linters that are used !

You can add secured variables to the default list using configuration property SECURED_ENV_VARIABLES in .mega-linter.yml or in an environment variable (priority is given to ENV variables above .mega-linter.yml property).

SECURED_ENV_VARIABLES_DEFAULT contains:

• GITHUB_TOKEN
• PAT
• SYSTEM_ACCESSTOKEN
• GIT_AUTHORIZATION_BEARER
• CI_JOB_TOKEN
• GITLAB_ACCESS_TOKEN_MEGALINTER
• GITLAB_CUSTOM_CERTIFICATE
• WEBHOOK_REPORTER_BEARER_TOKEN
• NPM_TOKEN
• DOCKER_USERNAME
• DOCKER_PASSWORD
• CODECOV_TOKEN
• GCR_USERNAME
• GCR_PASSWORD
• SMTP_PASSWORD

Example of adding extra secured variables .mega-linter.yml:

SECURED_ENV_VARIABLES:
  - MY_SECRET_TOKEN
  - ANOTHER_VAR_CONTAINING_SENSITIVE_DATA
  - OX_API_KEY

Example of adding extra secured variables in CI variables, so they can not be overridden in .mega-linter.yml:

SECURED_ENV_VARIABLES=MY_SECRET_TOKEN,ANOTHER_VAR_CONTAINING_SENSITIVE_DATA,OX_API_KEY

Notes:

• If you override SECURED_ENV_VARIABLES_DEFAULT, it replaces the default list, so it's better to only define SECURED_ENV_VARIABLES to add them to the default list !
• Environment variables are secured for each command line called (linters, plugins, sarif formatter...) except for PRE_COMMANDS , as you might need secured values within their code.

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 isn't the repo root.

Special considerations:

• As list of files isn't sent to the linter command, linters using project lint mode don't 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's awaited by the linter (for example with a .secretlintignore file for secretlint)