Megalinter Check

MegaLinter check

Collect the current MegaLinter errors and produce a compact error list that the megalinter-fix skill can consume.

Choose a mode

• Watch mode — a MegaLinter CI job exists for the current branch/PR (running or completed): parse its logs. No Docker needed.
• Local mode — no CI job available, or the user wants a pre-push check: run MegaLinter with Docker via npx mega-linter-runner.
• Targeted re-check (local, after fixes): re-run only the previously-failing linters in parallel standalone images.

Watch mode

1. Detect the provider from git remote get-url origin and the CI config files present.
2. Load the matching provider guide from this skill's directory — only the one you need:
   • GitHub Actions → providers/github.md
   • GitLab CI → providers/gitlab.md
   • Azure Pipelines → providers/azure.md
   • Bitbucket Pipelines → providers/bitbucket.md
3. Follow the guide: locate the MegaLinter job, wait for completion if running, fetch the logs of the MegaLinter step.
4. Parse the MegaLinter summary (the ❌/✅ table) and per-linter error sections.

Local mode

Before the first local run, make sure the user is aware that running MegaLinter locally is resource-consuming: it needs a reasonably powerful machine (CPU, RAM, free disk space) and a good internet connection — MegaLinter is Docker-based and the first run downloads a large image (can be several GB depending on the flavor). Because of this, watch mode (CI does the work) is usually the recommended option. When both modes are possible (a MegaLinter CI job exists for the repository, or a branch/PR could be pushed to trigger one) and the user did not explicitly choose, ask them which mode to use (use your platform's structured question mechanism if it has one, with watch mode first/recommended) instead of starting a local run.

Engine preflight (before every local run)

Requires a container engine (docker or podman) that actually responds - an installed binary proves nothing: with a stopped backend (e.g. Docker Desktop's Windows service), the docker CLI can hang indefinitely instead of failing fast. Probe with a bound before starting any run:

timeout 10 docker info --format '{{.ServerVersion}}'    # exit 124 = installed but not answering
timeout 10 podman info --format '{{.Version.Version}}'

• Chosen engine answers → proceed (pass --container-engine podman when using podman).
• Chosen engine errors or times out → probe the other engine the same way; if it answers, use it instead.
• Neither answers → do not start a run (it would hang the same way). Tell the user what you found ("Docker Desktop appears installed but is not responding - is it running?") and ask whether you should install or start an engine — then (and only then) load container-engine.md from this skill's directory for the setup instructions (prefer podman: free of charge even in enterprise contexts). If the user declines, fall back to watch mode.

Flavor and version are resolved automatically from MEGALINTER_FLAVOR / MEGALINTER_VERSION in .mega-linter.yml — do not pass --flavor or --release yourself.

npx mega-linter-runner                            # docker
npx mega-linter-runner --container-engine podman  # podman

Tip: for repeated local runs (e.g. fix → re-check loops), install the runner once with npm install -g mega-linter-runner and call mega-linter-runner directly — it avoids the npx package resolution overhead on every invocation.

• Add --fix if .mega-linter.yml defines APPLY_FIXES other than none (the repository has opted into auto-fixing).
• Cap parallelism on local machines: MegaLinter defaults to one parallel linter process per CPU core, which can saturate a dev machine where Docker shares resources with everything else. When running on a local computer — not in CI (no CI/GITHUB_ACTIONS/GITLAB_CI-style environment variable set) — add -e PARALLEL_PROCESS_NUMBER=4 to full runs (use the machine's core count instead if it has fewer than 4). Skip this when the repository configuration already sets PARALLEL_PROCESS_NUMBER; never write it into .mega-linter.yml, where it would also slow down CI.
• Always add -e JSON_REPORTER=true to full runs: the JSON report is not generated by default (JSON_REPORTER defaults to false), and this env variable overrides the repository configuration, guaranteeing megalinter-reports/mega-linter-report.json.
• Then read megalinter-reports/mega-linter-report.json and megalinter-reports/linters_logs/ERROR-*.log instead of parsing the console output, and extract the console tips from the persisted log file (see "Console tips" below) - do not re-read the whole console stream for them.
• A missing report file never means "wait": the runner is synchronous — once the command has exited, no report file will ever appear afterwards. Do not poll, sleep, or re-run for it. If the expected files are absent (the repository may set REPORT_OUTPUT_FOLDER to a custom folder or none, TEXT_REPORTER: false, or a different TEXT_REPORTER_SUB_FOLDER), fall back in order: check REPORT_OUTPUT_FOLDER in .mega-linter.yml and glob **/mega-linter-report.json / **/linters_logs/ under it, then parse the console output — the ❌/✅ summary table and per-linter error sections are always printed there.

Run with a time bound - never wait unbounded

Local runs can hang for environmental reasons (engine backend down, Windows bind-mount stalls - see below), so give every local invocation (prerun, full run, targeted re-check) an explicit bound:

1. Prefer the runner's own flag when available: check npx mega-linter-runner --help for --timeout, and pass --timeout <seconds> if listed - on expiry it also stops and removes the container. Do not assume it exists (older runner versions / pinned MEGALINTER_VERSION).
2. Fallback: wrap with the shell coreutils command - timeout <seconds> npx mega-linter-runner .... This kills the wrapper only, not the container: after it fires, do the orphan cleanup below.
3. Launch in the background with output going to a log file and check it every 1-2 minutes; never sit in a single indefinite blocking call.

Suggested bounds: full run 30 min, prerun or targeted single-linter run 10 min - a full flavor run on a mid-size repo normally takes minutes, not hours. First run on a machine: pre-pull the image separately (docker pull <image> / podman pull <image>) so the multi-GB download does not eat the bound.

Stalled or just slow? Diagnose, don't keep waiting

No new log output for ~5 minutes is a possible stall, not proof of work. Diagnose actively (<engine> = docker or podman):

1. <engine> ps -a - is the container still there, and how long has it been "Up"?
2. <engine> logs --tail 30 <name> - what was the last line? A phase boundary that never advances (e.g. "...collects the files to analyse", "Processing linters on [N] parallel cores") shows where it is stuck.
3. <engine> exec <name> ps aux - what is running inside, and how much cumulative CPU TIME do those processes show vs the container's wall-clock uptime? Seconds of CPU over hours of uptime = I/O stall (filesystem or network), not real computation: stop waiting, kill the run, clean up (below), and report the diagnosis instead of polling further. On Windows the usual culprit is the WSL2 bind-mount penalty - see "Windows bind-mount slowness" in performance.md.

Orphaned containers after a forced kill

Killing the wrapping command (shell timeout expiring, Ctrl-C, killing the npx process) does not reliably stop the container - especially on Windows, where signal forwarding is unreliable. Only the runner's own --timeout guarantees cleanup. After any forced interrupt:

1. <engine> ps -a - look for a still-"Up" container running a megalinter image.
2. <engine> stop <name>, then <engine> rm <name>, for each match.