自作キーボードのZMKファームウェアをGitHub Actionsでビルドする際に、手順通りに設定したにもかかわらずエラーが発生しUF2ファイルが生成されないケースは珍しくありません。本記事では、auto-kdk環境で起こりやすいGitHub Actionsのエラー原因と対処の考え方を整理します。
発生しているエラーの全体像
最初に発生する「Unexpected value ‘include’」「Required property is missing: jobs」というエラーは、GitHub ActionsのYAML構造が正しく解釈されていない場合に出ます。
これはファイル名や拡張子の問題というより、ワークフローのインデント構造やトップレベルキーの不整合が原因であることが多いです。
その後にビルドは開始されるものの「exit code 1」で失敗する場合、ビルド環境側でZMKの依存関係やツールチェーンが正常に構築できていない可能性があります。
GitHub Actions YAMLの基本構造ミス
GitHub Actionsのワークフローは「name」「on」「jobs」が必須構成です。
このうち「jobs」が正しくルートに存在しない場合、構文エラーとして扱われます。
初心者向けテンプレートをそのまま貼り付ける際に、インデント崩れやコピー時の空白混入が原因になることもあります。
auto-kdkとZMKのビルド特有の注意点
auto-kdkはZMKのビルドを自動化する仕組みですが、GitHub Actionsの仕様変更に影響を受けやすい構成です。
特にZMKはZephyrベースのため、toolchainやwestコマンドのバージョン差異でビルド失敗することがあります。
手順書通りでも、リポジトリ側の依存バージョンと実行環境がズレているとexit code 1が発生します。
Node.js 20廃止警告と今回のエラーの関係
表示されている「Node.js 20 actions are deprecated」は警告であり、今回の直接原因ではない可能性が高いです。
ただし将来的にはActionsランナーの仕様変更で影響を受けるため、actionのバージョン更新は必要になります。
現時点ではビルド失敗の主因はNode.jsではなくZMKビルド環境側の問題であることが多いです。
よくある原因とチェックポイント
まず確認すべきはworkflowファイルのインデントと構造です。
次にZMKのconfigやboard設定が最新のauto-kdk仕様と一致しているかを確認します。
またGitHub Actionsのキャッシュや古い依存が残っている場合もビルド失敗の原因になります。
解決アプローチの優先順位
最初にYAML構文の検証を行い、次にローカルでZMKビルドが通るか確認します。
その後GitHub Actionsのログを詳細に確認し、どのステップでexit code 1が出ているか特定します。
環境依存の場合は、toolchain更新やworkflowの公式テンプレートへの差し替えが有効です。
まとめ
ZMKとauto-kdkのGitHub Actionsエラーは、単純な記述ミスと環境依存の両方が原因になり得ます。
特にYAML構造とビルド環境のズレが最も多い要因であり、Node.js警告は直接原因ではないケースがほとんどです。
順番に切り分けることで、UF2生成まで安定して到達できるようになります。
コメント