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.

Custom flavor repositories: if — and only if — the user explicitly asks to create or maintain a custom MegaLinter flavor (their own image with just the linters they need, published from a dedicated megalinter-custom-flavor-* repository), this is a different job from the install flow below: load custom-flavor.md from this skill's directory and follow it instead. Everything else on this page targets a project that consumes MegaLinter.

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.

Also upgrade the MegaLinter skills and sub-agents

The repository configuration is only half of the setup. The MegaLinter skills you are running, and the sub-agent definitions they installed, were copied into the project (or the user profile) when they were added and do not update themselves — so an upgraded repository can still be driven by guidance written for an older MegaLinter. Refresh them whenever you run an upgrade, and whenever the user asks to update the MegaLinter skills.

First determine how MegaLinter was installed, because the two install modes update differently. Namespacing is not a reliable signal: only some platforms prefix plugin skills with the plugin name (megalinter:megalinter-setup), and no platform lets you query where a skill came from. Determine it from the filesystem, and ask the user when it stays ambiguous:

If it was installed as an agent plugin, the skills CLI does not manage it: update the plugin instead, and skip the rest of this section — the sub-agents are refreshed with it.

Otherwise, check how they are installed:

npx skills list

MegaLinter entries show their install path and Source. A local source means the files are not managed by the skills CLI (the MegaLinter repository's own skills/ folder, or a manual copy): leave those alone and tell the user.

Otherwise update them, naming the skills explicitly — a bare npx skills update would also update every unrelated skill installed in the project:

npx skills update megalinter megalinter-setup megalinter-check megalinter-fix -y

Add -p to restrict to project-level skills, or -g for the user-level ones, when both exist and only one should move.

If the update reports nothing to do (skills added with --copy are not always tracked), re-run the install command instead — it overwrites the installed copies with the current version:

npx skills add oxsecurity/megalinter/skills -s '*' -a <agent> -y

Then refresh the sub-agents: skills update rewrites the skill folders only, never the copies made into your platform's agents folder (.claude/agents/, .opencode/agent/, .github/agents/). Re-apply step 4 below for the three definitions so they match the refreshed skills, asking the user before overwriting any they customized.

Finally, note that the skill you are currently executing may have just been rewritten. After the refresh, re-read SKILL.md in this skill's directory and continue from the updated instructions if they differ from what you loaded.