# Megalinter Setup > Install or upgrade MegaLinter on a repository. Use when the user wants to add MegaLinter to a project, set up linting CI, update MegaLinter configuration or version, or says "install megalinter", "setup linting", "add code quality checks", "update megalinter skills". Always goes through npx mega-linter-runner (--install or --upgrade), then refines .mega-linter.yml. In upgrade mode it also refreshes the installed MegaLinter skills and sub-agents. Also sets up a MegaLinter custom flavor repository when the user explicitly asks for one. - Skill: `oxsecurity/megalinter-setup` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add oxsecurity/megalinter-setup` - Raw SKILL.md: https://api.skillmd.com/api/skills/oxsecurity/megalinter-setup/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MegaLinter by OX Security, Copyright 2026 - https://megalinter.i - Author: oxsecurity (https://skillmd.com/u/oxsecurity) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/oxsecurity/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](https://megalinter.io/flavors/) (`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: ```bash npx mega-linter-runner --install --no-prompt \ --flavor \ --setup-ci \ --setup-default-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 `.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: ```bash 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". **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[-]:` 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: | Evidence in the repository or user profile | Install mode | |:----------------------------------------------------------------------------------------------------------------------------|:-------------| | A MegaLinter plugin folder (`megalinter` under a `plugins/` directory of your platform) | plugin | | `.claude/skills/megalinter*`, `.github/skills/megalinter*`, `.agents/skills/megalinter*` or the same under the user profile | skills | | Neither, or both | ask the user | **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. | Platform | Update command | |:-------------------------|:----------------------------------------------------| | Claude Code | `/plugin update megalinter@megalinter` | | Cursor | **Customize → Plugins**, then update **MegaLinter** | | GitHub Copilot | `copilot plugin install megalinter@megalinter` | | Codex | `codex plugin marketplace upgrade megalinter` | | Gemini CLI / Antigravity | `gemini extensions update megalinter` | Otherwise, check how they are installed: ```bash 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: ```bash 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: ```bash npx skills add oxsecurity/megalinter/skills -s '*' -a -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. ## 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 `_FORWARD_EXCLUDED_DIRECTORIES: false` (per linter). Validate the file against its JSON schema: ## 4. Install or refresh the MegaLinter sub-agents (if your platform supports them) This skill ships three sub-agent definitions in its `agents/` folder (`megalinter-watcher`, `megalinter-runner`, `megalinter-fixer`) that make the other MegaLinter skills faster and cheaper by keeping CI logs and linter output out of the main context. **Skip this whole step if MegaLinter was installed as an agent plugin**: the plugin already ships the three definitions (declared for Claude Code and Cursor, and carried as `com.github.copilot/agents/*.agent.md` for the Copilot clients). Copying them again would install a second set that drifts on the next plugin update. Confirm before skipping: check that the three agents are actually listed among the agents available to you, under either their namespaced (`megalinter:megalinter-watcher`) or bare (`megalinter-watcher`) name. If they are not — the platform may not load the plugin's agents — tell the user, and install them from `agents/` as described below. If the coding agent you are running on supports custom sub-agent definitions (Claude Code, OpenCode, GitHub Copilot, Codex... — you know whether you do), read `agents/INSTALL.md` in this skill's directory and follow the instructions for your platform: copy the three `agents/*.md` files to your platform's agents folder, adapting the file name and the frontmatter when needed. Copilot in particular requires a `.agent.md` suffix in `.github/agents/`, and rejects the `model: haiku` override. If a target file already exists, ask the user before overwriting it. In upgrade mode the existing files are precisely what needs replacing: show the user what changed, and preserve any customization they made (a model override, an adapted `tools` list) when re-applying the new version. If your platform has no sub-agent support, skip this step — the skills degrade gracefully to inline execution. ## 5. Observability dashboards (optional) MegaLinter can send its results to observability platforms (Grafana, Datadog, Elastic, New Relic) and ships ready-to-use dashboards: quality gate, error trends, top rules and files across repositories. Documentation: Offer this to the user only if they seem interested in monitoring or already use one of these platforms. If accepted: 1. Ask which provider they use, and make sure the provider auth environment variables are available (never write secrets in committed files): - grafana: `GRAFANA_URL` + `GRAFANA_TOKEN` (service account token) - datadog: `DD_SITE` + `DD_API_KEY` + `DD_APP_KEY` (or `DD_BEARER_TOKEN`) - elastic: `KIBANA_URL` + `ELASTIC_API_KEY` - newrelic: `NEW_RELIC_API_KEY` + `NEW_RELIC_ACCOUNT_ID` + `NEW_RELIC_REGION` 2. Provision the dashboards: `npx mega-linter-runner --upload-dashboards ` (idempotent, re-run anytime to refresh). 3. Add to `.mega-linter.yml`: `API_REPORTER: true`, `API_REPORTER_PROVIDER: `, and the provider's non-secret variables (endpoints, site, region — see the documentation page of the provider). Point the user to the CI secrets to define for the auth variables (`API_REPORTER_*` tokens/keys). ## 6. Wrap up - Show the user the generated/updated files. - Propose the two ways to see MegaLinter in action (first install and upgrade alike), and offer to do it for them. A local run is **resource-consuming** (Docker-based, downloads an image of several GB on first run, then loads CPU/RAM/disk), so **running in CI is usually the recommended option** — ask the user which one they want (use your platform's structured question mechanism if it has one, with the CI option first/recommended) instead of picking silently: - **Create a pull request** (recommended) with the generated/updated files (commit on the current branch if it is already a feature branch, otherwise on a new branch — never on the default branch —, push, open the PR), then run the `megalinter-check` skill (watch mode) on the created PR to watch the CI job results and fix the errors. - **Run MegaLinter locally** through the `megalinter-check` skill (local mode) to preview and fix errors before pushing anything. Its first run starts with a prerun analysis (`--prerun`, MegaLinter v10 or beta) that suggests `.mega-linter.yml` performance tuning (directories to exclude, flavor) before the real lint. - Do not commit or push without user confirmation, and never on the default branch.