megalinter-setup

MegaLinter のセットアップ

現在のリポジトリに MegaLinter をインストールするか、アップグレードします。**設定を生成またはアップグレードする際は、必ず npx mega-linter-runner を使用してください。.mega-linter.yml` や CI ワークフローファイルをゼロから作成してはいけません。**生成されたファイルは、その後にのみ調整してください。

カスタムフレーバーリポジトリ：ユーザーが独自のカスタム MegaLinter フレーバー（必要なリンターだけを含む独自イメージを、専用の megalinter-custom-flavor-* リポジトリから公開するもの）の作成または保守を明示的に依頼した場合に限り、これは以下のインストールフローとは異なる作業です。このスキルのディレクトリから custom-flavor.md を読み込み、代わりにその手順に従ってください。このページのその他すべての内容は、MegaLinter を利用するプロジェクトを対象としています。

1. リポジトリを分析する

インストーラーのオプションに回答するために必要な情報を集めます。

• フレーバー：主な技術を検出し、フレーバー（python、javascript、java、go、php、ruby、rust、salesforce、swift、terraform、dotnet、dotnetweb、c_cpp、documentation、formatters、security、...）を選択します。複数の技術が混在している場合や、判断が難しい場合は all を選択します。
• CI システム：既存の設定（.github/ → gitHubActions、.gitlab-ci.yml → gitLabCI、azure-pipelines.yml → azure、bitbucket-pipelines.yml → bitbucket、Jenkinsfile → jenkins、.drone.yml → droneCI）または git のリモートホストから特定します。どれもない場合は other を選択します。
• デフォルトブランチ：git remote show origin または現在のリポジトリのデフォルトを確認します。

2. インストールまたはアップグレード

MegaLinter の設定がまだない場合 — インストーラーを非対話モードで実行します。

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

上記のオプションのいずれかがランナーに拒否される場合（「Invalid option」エラー）、解決された mega-linter-runner のバージョンが古くなっています。npx mega-linter-runner@latest で再実行してください（--setup-* オプションと --linter オプションには、最近のバージョンが必要です）。

注意事項：

• （デフォルトでは）実行のたびにコードベース全体が検証されます。更新されたファイルだけをリントするようユーザーから明示的に依頼された場合に限り、--setup-validate-all-code-base diff を渡してください。
• ベータ版をユーザーから依頼された場合に限り、--release beta を追加してください（その場合、インストーラーは .mega-linter.yml に MEGALINTER_VERSION: beta を書き込みます）。
• バージョンのルール（すべてのスキルに適用）：ランナーと Docker イメージのバージョンは、常に .mega-linter.yml の MEGALINTER_VERSION に従います。値が beta の場合は npx mega-linter-runner@beta を実行し、それ以外の場合は常に npx mega-linter-runner を実行してください。また、このインストール手順以外では --release を決して渡さないでください。
• --fix を指定すると、自動修正が有効になります（APPLY_FIXES: all）。ユーザーが自動整形を望まない場合は省略してください。
• ユーザーがその場にいて、対話形式で選択したい場合は、代わりに npx mega-linter-runner --install をそのまま実行し、ユーザーに回答してもらってください。

既存のカスタマイズを保持してください。 非対話モードでは、インストーラーは競合するファイルを上書きしますが、その前に既存の対象ファイル（設定ファイルと CI ワークフローファイル）をすべて <file>.megalinter-setup.bak としてバックアップします。インストール後：

1. 各 .megalinter-setup.bak ファイルと再生成されたファイルを比較します。
2. 現在も有効なユーザーのカスタマイズ（追加のワークフローステップ、環境変数、カスタムトリガー、追加された設定項目など）を再適用します。カスタマイズが新しいテンプレートと競合する場合、または意図が不明な場合は、何を残すかユーザーに確認してください。
3. 統合が済んだら、.megalinter-setup.bak ファイルを削除します。

すでに設定がある場合 — アップグレードします。

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

--upgrade は、CI ワークフローファイル内のイメージタグやアクションのバージョン、非推奨の変数名、.mega-linter.yml の MEGALINTER_VERSION プロパティなど、リポジトリ内の MegaLinter に関するすべての項目を現在のメジャーバージョンに移行します。ユーザーが「チェック」だけを依頼した場合でも、リポジトリが古い MegaLinter のメジャーバージョン（例：v8 のイメージタグ）を参照している場合は、必ず実行してください。

--upgrade の後に必ず実施 — Docker イメージの参照を ghcr.io に移行します。 MegaLinter v9.5.0 以降、イメージは GitHub Container Registry にのみ公開されています（Docker Hub は v9.4.0 で更新が停止しています）。また、--upgrade はレジストリを書き換えず、参照をプレフィックスなしの oxsecurity/megalinter... 形式に正規化します。そのため、必ず次の手順で仕上げてください。

1. リポジトリ内のすべての CI／ワークフローファイル（.github/workflows/*、.gitlab-ci.yml、azure-pipelines.yml、bitbucket-pipelines.yml、Jenkinsfile、.drone.yml、シェルスクリプトなど）を検索し、oxsecurity/megalinter の出現箇所を調べます。
2. Docker イメージとして使われているすべての出現箇所（image:、container:、services:、docker run、docker pull の後、および oxsecurity/megalinter[-<flavor>]:<tag> 形式。megalinter-only-* の単独イメージや docker.io/ を前置した参照も含む）を、同じ参照の前に ghcr.io/ を付けたものに書き換えます。フレーバーとタグはそのままにしてください。例：oxsecurity/megalinter-python:v10 は ghcr.io/oxsecurity/megalinter-python:v10 に変更します。
3. 次の参照は変更しないでください。すでに ghcr.io/ が前置されている参照、GitHub Action の参照（uses: oxsecurity/megalinter@... — アクションは Docker イメージではありません）、ドキュメントの URL。

MegaLinter のスキルとサブエージェントも更新する

リポジトリの設定は、セットアップの半分にすぎません。実行中の MegaLinter スキルと、それらがインストールしたサブエージェントの定義は、追加時にプロジェクト（またはユーザープロファイル）へコピーされており、自動では更新されません。そのため、リポジトリをアップグレードしても、古い MegaLinter 向けのガイダンスに従って実行されることがあります。アップグレードを実行するたびに、またユーザーから MegaLinter スキルの更新を依頼されたときにも、これらを更新してください。

まず、MegaLinter のインストール方法を確認してください。インストール方法によって更新方法が異なります。名前空間は確実な判断材料ではありません。プラットフォームによってはプラグインのスキルにプラグイン名が付加されます（megalinter:megalinter-setup）が、どのプラットフォームでもスキルの出所を問い合わせることはできません。ファイルシステムから判断し、特定できない場合はユーザーに確認してください。

リポジトリまたはユーザープロファイル内の証拠	インストール方法
使用しているプラットフォームの plugins/ ディレクトリ内にある MegaLinter プラグインフォルダー（megalinter）	プラグイン
.claude/skills/megalinter*、.github/skills/megalinter*、.agents/skills/megalinter*、またはユーザープロファイル内の同じパス	スキル
どちらもない、または両方ある	ユーザーに確認

エージェントプラグインとしてインストールされている場合、skills CLI では管理されません。代わりにプラグインを更新し、このセクションの残りはスキップしてください。サブエージェントもプラグインと一緒に更新されます。

プラットフォーム	更新コマンド
Claude Code	/plugin update megalinter@megalinter
Cursor	カスタマイズ → プラグインから、MegaLinterを更新
GitHub Copilot	copilot plugin install megalinter@megalinter
Codex	codex plugin marketplace upgrade megalinter
Gemini CLI / Antigravity	gemini extensions update megalinter

それ以外の場合は、インストール方法を確認してください。

npx skills list

MegaLinter の項目には、インストール先のパスと Source が表示されます。local ソースは、ファイルが skills CLI で管理されていないことを意味します（MegaLinter リポジトリ独自の skills/ フォルダー、または手動コピー）。これらは変更せず、そのことをユーザーに伝えてください。

それ以外の場合は、スキルを明示して更新してください。npx skills update だけを実行すると、プロジェクトにインストールされた無関係なスキルもすべて更新されてしまいます。

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

プロジェクトレベルのスキルだけを対象にする場合は -p を、ユーザーレベルのスキルだけを対象にする場合は -g を追加してください。両方が存在し、片方だけを更新する場合に使います。

更新対象がないと表示された場合（--copy で追加したスキルは追跡されないことがあります）は、代わりにインストールコマンドを再実行してください。現在のバージョンで、インストール済みのコピーが上書きされます。

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

次に、サブエージェントを更新してください。skills update で書き換えられるのはスキルのフォルダーだけで、プラットフォームのエージェントフォルダー（.claude/agents/、.opencode/agent/、.github/agents/）に作成されたコピーは更新されません。3 つの定義が更新後のスキルと一致するよう、以下のステップ 4 を再度実行してください。ユーザーがカスタマイズした定義を上書きする前に、必ずユーザーに確認してください。

最後に、現在実行中のスキル自体が書き換えられた可能性があります。更新後、このスキルのディレクトリにある SKILL.md を再度読み込み、読み込んだ内容と異なる場合は、更新後の指示に従ってください。

3. .mega-linter.yml を調整する（インストール／アップグレード後のみ）

ランナーがファイルを生成／アップグレードした後であれば、.mega-linter.yml を調整できます。

• MEGALINTER_FLAVOR と MEGALINTER_VERSION が設定されていることを確認します（インストーラーが書き込みます。古い設定をアップグレードする場合は追加してください）。これらは、mega-linter-runner とこのスキルで使用する Docker イメージを指定します。
• ユーザーが指定した DISABLE／DISABLE_LINTERS の項目を追加します。
• 生成されたフォルダーやベンダー提供のフォルダーに FILTER_REGEX_EXCLUDE を追加します（例：(dist/|build/|vendor/|node_modules/)）。除外されたディレクトリ（およびこれらの正規表現で特定されたフォルダー）は、ネイティブの除外引数または生成された ignore／設定ファイルを通じて、プロジェクトモードのリンターにも自動的に引き渡されます。リポジトリでリンター独自の最新の ignore／設定ファイルをすでに管理している場合は、FORWARD_EXCLUDED_DIRECTORIES: false（グローバル）または <LINTER_KEY>_FORWARD_EXCLUDED_DIRECTORIES: false（リンターごと）を設定して、この引き渡しを無効にできます。

このファイルを JSON スキーマに照らして検証します：https://raw.githubusercontent.com/oxsecurity/megalinter/main/megalinter/descriptors/schemas/megalinter-configuration.jsonschema.json

4. MegaLinter サブエージェントをインストールまたは更新する（プラットフォームがサポートしている場合）

このスキルには、agents/ フォルダーに 3 つのサブエージェント定義（megalinter-watcher、megalinter-runner、megalinter-fixer）が含まれています。CI ログとリンターの出力をメインコンテキストの外に保持することで、他の MegaLinter スキルをより高速かつ低コストで実行できます。

MegaLinter をエージェントプラグインとしてインストールした場合は、この手順全体をスキップしてください。プラグインには、すでに 3 つの定義が含まれています（Claude Code と Cursor 用に宣言され、Copilot クライアント用には com.github.copilot/agents/*.agent.md として含まれています）。再度コピーすると、次回のプラグイン更新時に古い内容のものが別途インストールされてしまいます。

スキップする前に確認してください。利用可能なエージェントの一覧に、3 つのエージェントが名前空間付き（megalinter:megalinter-watcher）または名前空間なし（megalinter-watcher）の名前で実際に表示されているか確認します。表示されていない場合、プラットフォームがプラグインのエージェントを読み込んでいない可能性があることをユーザーに伝え、以下の説明に従って agents/ からインストールしてください。

使用中のコーディングエージェントがカスタムサブエージェント定義をサポートしている場合（Claude Code、OpenCode、GitHub Copilot、Codex など。サポートの有無はご自身で判断してください）、このスキルのディレクトリにある agents/INSTALL.md を読み、使用するプラットフォーム向けの手順に従ってください。3 つの agents/*.md ファイルをプラットフォームのエージェントフォルダーにコピーし、必要に応じてファイル名とフロントマターを調整します。特に Copilot では、.github/agents/ 内で .agent.md の拡張子が必要であり、model: haiku による上書きは拒否されます。

コピー先のファイルがすでに存在する場合は、上書きする前にユーザーに確認してください。アップグレードモードでは、既存のファイルこそ置き換えが必要なファイルです。変更点をユーザーに示し、新しいバージョンを適用する際は、ユーザーによるカスタマイズ（モデルの上書き、調整済みの tools リストなど）を保持してください。プラットフォームがサブエージェントをサポートしていない場合は、この手順をスキップしてください。このスキルはインライン実行に切り替えても問題なく動作します。

5. 可観測性ダッシュボード（任意）

MegaLinter は結果を可観測性プラットフォーム（Grafana、Datadog、Elastic、New Relic）に送信でき、すぐに使えるダッシュボード（品質ゲート、エラーの傾向、リポジトリ全体の上位ルールとファイル）も提供します。ドキュメント：https://megalinter.io/latest/observability/

ユーザーがモニタリングに関心を示している場合、またはこれらのプラットフォームをすでに利用している場合に限り、提案してください。同意が得られた場合：

1. 利用しているプロバイダーを確認し、プロバイダーの認証用環境変数が利用可能であることを確認します（コミットするファイルにシークレットを絶対に記述しないでください）。
   • grafana：GRAFANA_URL + GRAFANA_TOKEN（サービスアカウントトークン）
   • datadog：DD_SITE + DD_API_KEY + DD_APP_KEY（または DD_BEARER_TOKEN）
   • elastic：KIBANA_URL + ELASTIC_API_KEY
   • newrelic：NEW_RELIC_API_KEY + NEW_RELIC_ACCOUNT_ID + NEW_RELIC_REGION
2. ダッシュボードをプロビジョニングします：npx mega-linter-runner --upload-dashboards <provider>（冪等なので、いつでも再実行して更新できます）。
3. .mega-linter.yml に API_REPORTER: true、API_REPORTER_PROVIDER: <provider>、およびプロバイダーのシークレットではない変数（エンドポイント、サイト、リージョン。プロバイダーのドキュメントページを参照）を追加します。認証用変数の API_REPORTER_* トークン／キーを定義する CI シークレットをユーザーに案内します。

6. 仕上げ

• 生成または更新したファイルをユーザーに示します。
• MegaLinter を実行して動作を確認する 2 つの方法（初回インストールとアップグレードのどちらの場合も）を提案し、代わりに実行することも申し出ます。ローカル実行はリソースを大量に消費します（Docker ベースで、初回実行時に数 GB のイメージをダウンロードし、その後も CPU／RAM／ディスクを使用するため）。そのため、通常はCI での実行が推奨されます。黙って方法を選ぶのではなく、ユーザーにどちらを希望するか尋ねてください（利用しているプラットフォームに構造化された質問機能がある場合は、CI の選択肢を最初に表示し、推奨であることを明記してください）。
  • プルリクエストを作成する（推奨）：生成または更新したファイルを使います（現在のブランチがすでにフィーチャーブランチならそのブランチにコミットし、そうでなければ新しいブランチを作成します。デフォルトブランチには絶対にコミットせず、プッシュしてプルリクエストを開きます）。その後、作成したプルリクエストに対して megalinter-check スキルを実行し（監視モード）、CI ジョブの結果を確認してエラーを修正します。
  • ローカルで MegaLinter を実行する：megalinter-check スキル（ローカルモード）を使って、プッシュする前にエラーを確認して修正します。初回実行では、実際のリントの前に事前分析（--prerun、MegaLinter v10 またはベータ版）が開始され、.mega-linter.yml のパフォーマンス調整（除外するディレクトリ、フレーバー）が提案されます。
• ユーザーの確認なしにコミットまたはプッシュしてはいけません。また、デフォルトブランチには絶対にコミットまたはプッシュしないでください。