Zenn
🔧

CI/CDパイプラインのファイル検知不具合を修正（開発日記 No.058）

に公開
GitHub Actions
CI/CD
開発日記
idea

関連リンク

はじめに

昨日はOpenRouterのAPIキーを使ったテストやGitHub Actionsの基本的な動作確認を行いました。今日は、以前から気になっていたCI/CDパイプライン、特に研究資料を自動で記事形式に変換するパイプラインで発生している不具合の修正に取り組みます。

背景と目的

現在運用している研究資料変換パイプライン (research_converter.yml) で、2つの問題が発生していました。

  1. ファイル削除の誤検知: リポジトリからファイルを削除した際、それが「変更」としてパイプラインに検知されてしまい、意図しないエラーが発生していました。
  2. ファイル変更の検知漏れ: 本来検知されるべきファイルの変更が、なぜかパイプライン上で正しく取得できていないケースがありました。

これらの問題により、パイプラインが頻繁に失敗し、自動化の恩恵を受けられていない状況でした。今回の目的は、これらの不具合の原因を特定し修正することで、パイプラインを安定稼働させることです。

検討内容

まずは、GitHub Actionsの実行ログを詳細に確認しました。

  1. ファイル削除の誤検知について: ログを見ると、git diff コマンドが削除されたファイルも差分としてリストアップしていることがわかりました。パイプラインの設計上、削除は「変更」として扱いたくないため、git diff の挙動を制御する必要があると判断しました。
  2. ファイル変更の検知漏れについて: こちらのログでは、変更されたファイル自体は git diff で検出できているものの、その後のステップでファイル名を正しく扱えていないようでした。GitHub Actionsの出力（outputs）の形式、特に複数ファイルが変更された場合のマルチライン出力の扱いに問題があるのではないかと推測しました。

これらのログ分析に基づき、git diff コマンドのオプションとGitHub Actionsの出力設定を見直すことにしました。

実装内容

特定した原因に基づき、research_converter.yml ワークフローファイルを以下のように修正しました。

  1. ファイル削除を除外:
    git diff コマンドを実行しているステップで、--diff-filter=d オプションを追加しました。これにより、削除されたファイル（deleted）は差分検出の対象から除外されます。

    # 修正前 (例)
- name: Get changed files
  id: files
  run: |
    echo "::set-output name=changed_files::$(git diff --name-only ${{ github.event.before }} ${{ github.sha }} -- '*.md')"

# 修正後 (例)
- name: Get changed files
  id: files
  run: |
    echo "::set-output name=changed_files::$(git diff --name-only --diff-filter=d ${{ github.event.before }} ${{ github.sha }} -- '*.md')"

    注: 上記は修正内容を説明するための簡略化された例です。実際のコードとは異なる場合があります。

  2. GitHub Actionsのマルチライン出力対応:
    変更されたファイルリストを後続のステップで正しく扱えるように、GitHub Actionsの出力形式をマルチラインに対応したものに修正しました。具体的には、ファイル名を改行区切りで出力し、それを適切に処理できるようにしました。（具体的な修正方法はワークフローの構成によりますが、echo "::set-output name=...::$(... | paste -sd '\n')" のような形式や、区切り文字を使った工夫などが考えられます。）

これらの修正をリポジトリにプッシュし、パイプラインが意図通りに動作することを確認しました。

技術的なポイント

今回の修正における技術的なポイントは以下の2点です。

  • git diff --diff-filter: このオプションを使うことで、追加 (A)、コピー (C)、削除 (D)、変更 (M)、リネーム (R) など、特定の種類の変更のみを git diff の対象にすることができます。今回は削除を除外するために d を指定しましたが、他のフィルターと組み合わせることも可能です。
  • GitHub Actionsの出力 (outputs): ステップ間でデータを渡すための outputs は、デフォルトでは改行文字などがエスケープされることがあります。マルチラインのテキスト（ファイルリストなど）を正しく渡すためには、出力形式と後続ステップでの受け取り方を工夫する必要があります。

所感

CI/CDパイプラインのデバッグは、時として地道で根気のいる作業だと改めて感じました。特に、ローカル環境では再現しにくい問題も多く、GitHub Actionsのログとにらめっこする時間が長かったです。

ファイル削除がデフォルトで「変更」として扱われる git diff の挙動は少し意外でしたが、--diff-filter という便利なオプションを知ることができたのは収穫でした。また、GitHub Actionsの出力形式の問題は、以前にも似たようなことで少しハマった記憶があり、改めて仕様の理解が重要だと痛感しました。

原因を特定し、修正がうまく反映されてパイプラインが緑色（成功）になった瞬間は、やはり嬉しいものですね。地道な作業でしたが、これで今後の開発効率が少し改善されると思うと、達成感があります。

今後の課題

今回の修正により、研究資料変換パイプラインの安定性は向上したはずですが、今後も継続的に動作を監視していく必要があります。予期せぬエッジケースで問題が再発しないか、注意深く見ていきたいと思います。

また、他のCI/CDパイプラインでも同様にファイル削除やマルチライン出力の扱いで問題が発生していないか、点検してみる必要がありそうです。

まとめ

今回は、CI/CDパイプライン (research_converter.yml) で発生していたファイル削除の誤検知とファイル変更の検知漏れという2つの不具合を修正しました。

  • git diff コマンドに --diff-filter=d オプションを追加し、削除されたファイルを差分検出から除外。
  • GitHub Actionsの出力形式を修正し、マルチラインのファイルリストを正しく扱えるように改善。

これらの修正により、パイプラインの安定性が向上し、より信頼性の高い自動化プロセスを構築することができました。git コマンドのオプションやGitHub Actionsの細かな仕様への理解が、安定したCI/CD環境の構築には不可欠であることを再認識しました。

GitHubで編集を提案

Discussion