Megalinter Setup

MegaLinter setup

Install or upgrade MegaLinter on the current repository. Always use npx mega-linter-runner to scaffold or upgrade the configuration — never write .mega-linter.yml or CI workflow files from scratch. Only refine the generated files afterwards.

1. Analyze the repository

Gather what you need to answer the installer's options:

• Flavor: detect the main technology and pick a flavor (python, javascript, java, go, php, ruby, rust, salesforce, swift, terraform, dotnet, dotnetweb, c_cpp, documentation, formatters, security, ...). Mixed or unclear → all.
• CI system: from existing config (.github/ → gitHubActions, .gitlab-ci.yml → gitLabCI, azure-pipelines.yml → azure, bitbucket-pipelines.yml → bitbucket, Jenkinsfile → jenkins, .drone.yml → droneCI) or the git remote host. None → other.
• Default branch: git remote show origin or the current repository default.

2. Install or upgrade

No MegaLinter configuration yet — run the installer non-interactively:

npx mega-linter-runner --install --no-prompt \
  --flavor <flavor> \
  --setup-ci <ci> \
  --setup-default-branch <branch> \
  --fix

If the runner rejects one of the options above ("Invalid option" error), the resolved mega-linter-runner version is outdated: re-run with npx mega-linter-runner@latest (the --setup-* and --linter options need a recent version).

Notes:

• The whole codebase is validated on each run (default). Pass --setup-validate-all-code-base diff only if the user explicitly asks to lint updated files only.
• Add --release beta only if the user asks for the beta version (the installer then writes MEGALINTER_VERSION: beta in .mega-linter.yml).
• Version rule (all skills): runner and Docker image versions always follow MEGALINTER_VERSION from .mega-linter.yml — invoke npx mega-linter-runner@beta when it is beta, plain npx mega-linter-runner in every other case, and never pass --release outside of this install step.
• --fix enables auto-fixes (APPLY_FIXES: all); omit it if the user doesn't want automatic formatting.
• If the user is present and wants to choose interactively, run plain npx mega-linter-runner --install instead and let them answer.

Preserve existing customizations. In non-interactive mode the installer overwrites conflicting files, but it first backs up every pre-existing target as <file>.megalinter-setup.bak (config files and the CI workflow file). After the install:

1. Diff each .megalinter-setup.bak file against its regenerated version.
2. Re-apply the user's customizations that are still relevant (extra workflow steps, env vars, custom triggers, added config entries...). When a customization conflicts with the new template or its intent is unclear, ask the user what to keep.
3. Delete the .megalinter-setup.bak files once merged.

Configuration already exists — upgrade it:

npx mega-linter-runner --upgrade --no-prompt

--upgrade migrates every MegaLinter reference of the repository to the current major version: image tags and action versions in the CI workflow files, deprecated variable names, and the MEGALINTER_VERSION property of .mega-linter.yml. Run it whenever the repository references an older MegaLinter major version (e.g. v8 image tags), even if the user only asked for a "check".

<!-- MAJOR-RELEASE-IMPACTED (example tags below) -->

Mandatory after --upgrade — migrate Docker image references to ghcr.io. Since MegaLinter v9.5.0, images are only published to GitHub Container Registry (Docker Hub is frozen at v9.4.0), and --upgrade does NOT rewrite the registry: it normalizes references to the bare oxsecurity/megalinter... form. So always finish with this pass:

1. Search every CI/workflow file of the repository (.github/workflows/*, .gitlab-ci.yml, azure-pipelines.yml, bitbucket-pipelines.yml, Jenkinsfile, .drone.yml, shell scripts...) for oxsecurity/megalinter occurrences.
2. Rewrite every occurrence used as a Docker image (after image:, container:, services:, docker run, docker pull, or any oxsecurity/megalinter[-<flavor>]:<tag> form, including megalinter-only-* standalone images and docker.io/-prefixed references) to the same reference prefixed with ghcr.io/ — keep flavor and tag unchanged: oxsecurity/megalinter-python:v10 becomes ghcr.io/oxsecurity/megalinter-python:v10.
3. Leave untouched: references already prefixed with ghcr.io/, GitHub Action references (uses: oxsecurity/megalinter@... — actions are not Docker images), and documentation URLs.

3. Refine .mega-linter.yml (only AFTER install/upgrade)

Once the runner has generated/upgraded the files, you may adjust .mega-linter.yml:

• Ensure MEGALINTER_FLAVOR and MEGALINTER_VERSION are set (the installer writes them; add them if upgrading an older config) — they drive which Docker image mega-linter-runner and these skills use.
• Add DISABLE / DISABLE_LINTERS entries the user asks for.
• Add FILTER_REGEX_EXCLUDE for generated or vendored folders (e.g. (dist/|build/|vendor/|node_modules/)). Excluded directories (and folders identified from these regexes) are also automatically forwarded to project-mode linters through their native exclusion arguments or generated ignore/config files; if the repository already maintains its own up-to-date ignore/config files for a linter, that forwarding can be turned off with FORWARD_EXCLUDED_DIRECTORIES: false (global) or <LINTER_KEY>_FORWARD_EXCLUDED_DIRECTORIES: false (per linter).

Validate the file against its JSON schema: https://raw.githubusercontent.com/oxsecurity/megalinter/main/megalinter/descriptors/schemas/megalinter-configuration.jsonschema.json