actionlint

actionlint

明らかに壊れている GitHub Actions ワークフローをリポジトリに入れないようにします。 ワークフローファイルに変更を加えるコミットの前に、 ステージ済みのファイルに対して actionlint を実行します。 終了コードが 0 以外の場合、修正するまでコミットはブロックされます。

これは vcs-identity-check および vcs-commit-msg とともに、 もう 1 つのコミット前提条件として機能します。 これら 3 つはそれぞれ独立しているため、順序は問いません。

判断に迷ったら、オペレーターに確認してください

何かが曖昧な場合、 前提条件が満たされていない場合、 または進め方に確信が持てない場合は、 推測せずに作業を止め、オペレーターに確認してください。 誤ったコミットや、 誤った修正、 質問すれば解消できる不足を埋めるためにトークンを費やすより、質問を 1 つするほうが低コストです。 これは以下のすべての手順に当てはまります。

実行するタイミング（ゲート）

ステージ済みの変更にワークフローファイル（.github/workflows/*.yml または .github/workflows/*.yaml）が含まれる場合に、この手順を実行します。 一致するステージ済みファイルがない場合、このスキルは適用されません。 何も言わずに終了してください。

リモートは確認しません。 .github/workflows/ 内のワークフローファイルは GitHub Actions（GitHub.com と GitHub Enterprise の両方）専用です。 そのため、ファイルが存在するだけで十分な判定材料となります。 リモートが github.com を指しているか確認しても、カスタムドメインを使う Enterprise や、まだリモートのないローカルリポジトリでは誤検知の見落としが増えるだけです。

対象はワークフローファイルのみです。 actionlint は action.yml / action.yaml（複合アクションのメタデータ）をリントしないため、ここでは対象外です。

手順

以下のすべての手順は、リポジトリのルートから実行します — cd "$(git rev-parse --show-toplevel)" — git が出力するパスはこのディレクトリからの相対パスであり、 actionlint も同じディレクトリからパスを解決する必要があるためです。

1. ステージ済みのワークフローファイルを収集します （追加／コピー／変更／名前変更 — 削除は lint 不要です）：

   git diff --cached --name-only --diff-filter=ACMR -- .github/workflows \
     | grep -E '\.ya?ml$'
   

   結果が空 → このゲートの対象ではありません； 停止します。

2. actionlint が利用可能であることを確認します： command -v actionlint。 見つからない場合は、mise スキルを使ってインストールします （下記のactionlint のインストールを参照）— brew／go install／curl パイプは決して使わないでください。 その方法で actionlint をインストールできない場合 （mise がない、またはプロジェクトが mise を使っていない場合）は、 担当者に伝えて停止します — 別のインストーラーを使わないでください。

3. ステージ済みの内容と作業ツリーの内容が一致していることを確認します。 actionlint はインデックスではなく作業ツリーを読み取るため、 ステージ済みのワークフローにステージされていない変更が加わっていると、 コミットされるものとは異なるバージョンが lint されてしまいます：

   git diff --name-only -- <staged-files…>
   

   出力があれば → バージョンが一致していません； コミットされない内容を lint するのではなく、 担当者に再ステージするか変更を退避するよう依頼して停止します。

4. ステージ済みのファイルを lint します。引数として渡すことで、 変更していない既存ワークフローの無関係なエラーがこのコミットを妨げないようにします：

   actionlint <staged-files…>
   

   通常の actionlint を実行します — PATH にある場合に限り shellcheck／pyflakes を自動で使用するため、 ゲートで切り替える設定はありません。 手順 3 で問題がなければ、これによりコミットされるものだけがチェックされます。

5. 終了コードに応じて対応します（$?）：

   • 0 — 問題なし； ワークフロー部分はコミット可能です。
   • 1 — actionlint がワークフロー内の問題を検出しました。 無効な YAML や誤ったワークフロー構造も含まれます （これらには [syntax-check] タグが付いています）— これは「明らかに壊れている」ケースです。 出力を表示し、コミットをブロックしたままにします。 やみくもにワークフローを書き換えないでください： 修正方法が明らかでない場合は、担当者に確認してください。 修正後、再ステージして（git add）、手順 3 から再実行します； 終了コードが 0 になった場合にのみコミットできます。
   • 2 — コマンドライン引数が無効です： ワークフローの問題ではなく、actionlint の呼び出し方法の誤りです。 呼び出し方法（手順 4）を修正して再実行します。
   • 3 — actionlint がファイルを読み取れませんでした（could not read …）： 通常はパスを解決できていません — コマンドがリポジトリのルートから実行されたことを確認してから再実行します。

6. 終了コードが 0 の場合にのみコミットを許可します。 このスキルはゲートであり、コミットそのものではありません — 0 の場合、ワークフローチェックに合格しており、 通常のコミットフロー（vcs-identity-check / vcs-commit-msg）が続行されます。 ゼロ以外の終了コードではコミットをブロックしたままにします； --no-verify を使うなどして回避しないでください。

actionlint が見つからない場合のインストール

mise でインストールします。 mise スキルが利用できる場合は、 詳細（バージョンの固定、mise.lock、バックエンドポリシー）はそのスキルに任せます — ここではそれが標準の方法です。

mise スキルは利用できないものの mise バイナリがある場合は、 mise.toml の [tools] に actionlint を追加します：

[tools]
actionlint = "<version>"

mise latest actionlint で <version> を確認します （すべてのバージョン：mise ls-remote actionlint）— latest は使わず、バージョンを完全に固定してください。 名前を actionlint のまま指定すると、aqua 経由で aqua:rhysd/actionlint に解決されます。 いずれの場合も、brew、go install、curl パイプのスクリプトは決して使わないでください。

このスキルは shellcheck や pyflakes をインストールしません。 それらが PATH にある場合、actionlint が自動で検出します （run: 内のシェルや Python のチェックにも適用されます）。 これらがなくてもエラーにはなりません。 連携を確実に無効にするには、 空の値を渡します：actionlint -shellcheck= -pyflakes=。

既存の actionlint 設定

リポジトリに .github/actionlint.yaml（または .yml）がすでにある場合、 actionlint は自動で使用します （セルフホストランナーのラベル、設定変数、パスごとの無視設定）。 この設定を尊重してください： 上書きせず、-init-config で初期化しないでください。 設定は任意です — なくても actionlint は問題なく実行できます。

任意：pre-commit フックで適用する

上記の手順では、エージェントが作成するコミットを保護します。 手入力によるコミットも検出できるように、pre-commit フックを提案してください （インストールはユーザーの同意がある場合に限ります。強制せず、提案してください）。

actionlint には、公式の pre-commit-framework 連携機能があります。 .pre-commit-config.yaml で次のように設定します。

- repo: https://github.com/rhysd/actionlint
  rev: <vX.Y.Z>
  hooks:
    - id: actionlint-system

rev には、該当するリリースタグを設定します。 mise latest actionlint で取得したバージョンの先頭に v を付けたものです （バージョンが X.Y.Z の場合、タグは vX.Y.Z です）。 リリースタグは https://github.com/rhysd/actionlint/releases にも掲載されています。

actionlint-system のフック ID を使用してください。 これにより、Go ツールチェーン経由の取得（actionlint）や Docker（actionlint-docker）ではなく、 すでに PATH 上にあるバイナリ（mise で管理されているもの）が実行されます。 pre-commit ランナー自体は mise スキルを通じてインストールしてください （Python CLI のため、pipx バックエンドを使用します）。

対象外

• uses: の参照の SHA ピン留め — これは actionlint ではなく、pinact / Dependabot の対象です。
• CI 連携（別途対応してください）。

報告

チェック後、リントしたワークフローファイル、終了コード、 見つかった問題（ある場合）、およびコミットが許可されるかブロックされるかを報告してください。