APC 技術ブログ

株式会社エーピーコミュニケーションズの技術ブログです。

株式会社 エーピーコミュニケーションズの技術ブログです。

トップ > GitHub Actions > 既存プロジェクトのGitHub Actionsを効率よく読み解くためのチェックポイント

既存プロジェクトのGitHub Actionsを効率よく読み解くためのチェックポイント

GitHub Actions CI/CD

こんにちは、クラウド事業部の山路です。

近年、CI/CDツールとしてGitHub Actionsを利用するのが当たり前になってきました。それなりの歴史や規模があるプロジェクトに参画すると、Workflowの数が膨大になっており、新しくチームに入ったメンバーが「どのWorkflowが何をしているのか」を追いかけるだけで一苦労…というケースも少なくありません。

今回は、新しい現場やプロジェクトに参画した際、GitHub Actionsの全体像や挙動を効率的にキャッチアップするために、個人的に意識してチェックしているポイントを整理してみました。この記事では、GitHub Actionsそのものを一から学ぶのではなく、GitHub Actionsを利用している既存プロジェクトに初めて参画し、「既存のWorkflowが何をしているのか把握したい」という方を対象としています。

「全部理解するのは大変そうだけど、とりあえず現場で何を見ればいいのか知りたい」という方に向けて、私自身が既存プロジェクトを読む際に確認しているポイントをまとめます。

何をもって「GitHub Actionsを理解した」と言えるか

本題に入る前に、「GitHub Actionsを理解した」とは、どんな状態を指すのか、少しだけ私の考えを書いておきます。

GitHub Actionsは2019年に正式リリースしてから進化を続けています。例えばActionと呼ばれる、Workflow内部で使われる再利用可能なパーツについては、企業や個人が提供するものを含めると膨大な数のパッケージが存在します。これらの全容を把握し続けるのは困難なため、「大事なポイントだけ押さえておき、他は必要に応じて調べる」、とするのが現実的です。

私個人は、以下の5つの観点が押さえられていれば、大事なポイントは押さえられている、と考えます。

  • 実行のきっかけ: そのWorkflowはいつ実行されるか・されないか
  • 実行時の処理内容: そのWorkflowの中でどんな処理が実行されるか
  • 実行場所・権限: Workflowはどの環境で、どの程度の権限を付与されるか
  • 実行結果の通知先: Workflowが成功・失敗した時はどこに・誰宛てに通知されるか
  • 変更時の影響: あるWorkflowを変更すると、どこにどんな影響があるか

本記事でも、主に上記5つのポイントを押さえることを念頭に書いています。

前提知識の整理

まずは、Workflowの挙動を読み解くために最低限知っておきたい前提知識と、事前に確認しておくべき「自分自身の権限」について整理します。

GitHub Actionsの基本構成

GitHub Actionsの詳細な仕様をすべて暗記している必要はありませんが、最低限以下のポイントを押さえているとキャッチアップがスムーズになります。

  • Workflow定義ファイルの配置場所: リポジトリ内の .github/workflows/ 配下にYAML形式で格納されていること
  • 基本構成: Workflow / Job / Step / Actionの関係性を理解していること、Workflow全体のトリガーとなる on、権限を表す permissions などの構造・書き方を押さえていること
  • 起動条件 (トリガー) : push / pull_request / workflow_dispatch（手動実行）/ schedule（定期実行）などを把握していること

もし「GitHub Actionsの仕様をしっかり基礎から学び直したい」という場合は、公式ドキュメントに加えて以下の書籍などをあらかじめ読んでおくのもおすすめです。

gihyo.jp

自分に付与されたGitHub権限の把握

GitHub Actionsの情報を追いかけるには、当然ですが対象のGitHubリポジトリの閲覧権限が必要です。新規プロジェクトに参画した直後だと権限付与の手続きの最中なこともあるかと思うので、その場合は他の情報や申請を確認したり、アクセスできる範囲でGitHub Actionsの情報がないかを探したりしましょう。

また、GitHubリポジトリの権限が付与されても、権限によってはリポジトリのすべての設定が見えない場合もあります。権限の範囲によっては、Workflowの挙動を追うために必要な画面や設定情報にアクセスできない場合もあるため、リポジトリのどの設定にアクセスできるかは事前に確認しておくと良いでしょう。

例として、GitHubの以下の画面は、Workflowの挙動を追いかける中で見る機会もあるでしょう。ただし、以下の値が確認できなくとも、Workflowの定義ファイルを追いかければ、それらが処理中にどのように使われているかは把握できるため、あくまで自身の権限がどの程度かを押さえておくくらいの認識で良いと思います。

  • Secrets / Variables: Workflowが参照する環境変数や秘密情報。一般の閲覧権限（Read）のみだと、Secret/Variablesを表示する Settings タブ自体が表示されず、Web UIから定義内容を確認できないことがあります。
  • Environments / Deployments: デプロイ先の環境ごとに設定された承認ルール (Required reviewers) や環境固有のVariables/Secrets。
  • コンテナレジストリ (GitHub Packages / GHCRなど): ビルド成果物を格納するレジストリ。Workflowの処理中にビルドしたDockerイメージ等の格納先として利用する場合があります。

効率的にWorkflowをキャッチアップするためのチェックポイント

ここからは、実際にリポジトリ内のWorkflowを読み解いていく際の手順とチェックポイントです。

1. 重要度の高いWorkflowを見極める

GitHubリポジトリ内に数十個の定義ファイル（.github/workflows/*.yml）がある場合、最初からすべてを1つずつ解読しようとするのは効率が悪いです。まずはその中から優先度を決め、優先度の高いものから順に見ていきたいところです。

個人的には、以下の3つの観点で優先度をつけ、重要度の高いものから順に見ていきます。

  • 自分の業務担当: 当然ながら、自分の業務範囲に近いものほど優先して確認すべきです。インフラの設計構築を担当するなら、システムのインフラを作成・変更するWorkflowは優先度が高くなるでしょう。
  • 実行頻度の高いもの: 頻繁に使われるWorkflowほど重要度が高いと捉え、GitHubの Actions タブを開き、直近で実行頻度が高いものを重点的に追いかけます。
  • 影響範囲の広いもの: Workflow名で影響範囲がわかるなら、影響範囲の広いものを優先します。インフラ担当なら、本番環境へのデプロイを行うWorkflowの方が、開発環境への変更プランニングをするものより優先度は高いでしょう。

ただし、これらの基準は必ずしも毎回使えるものではありません。基準を定めるのが難しい (自分のプロジェクト内の立ち位置が曖昧で担当範囲が明確でない、CI/CDを導入し始めたばかりで一部業務でのみ使っている、など) 、基準同士が衝突する (自分の業務範囲だが、直近3ヶ月以上使われていない、など) などのケースもあるからです。その場合、まずは GitHubの「Actions」タブを開き、直近で実行頻度が高いワークフローはどれか を確認し、優先順位をつけるのがよいと考えています。

2. 重要なWorkflowの「概要」をざっくり掴む

Workflowの優先順位が決まったら、各Workflowが「何をするものか」の概要を把握します。

Workflow名やJob名から内容を推測できる、または description に簡潔な説明が書かれていればそれを読むのも手ですが、定義ファイルが長い場合は生成AIを活用して概要を要約してもらうのも手軽です。

以下のような簡単なプロンプトでも、ある程度の内容は把握できるかと思います。

# 例：AIツールにYAMLを渡して概要を聞く際のプロンプト例
以下のGitHub ActionsのYAMLファイルを読み込み、どのようなトリガーで起動し、
具体的にどのような処理（テスト、ビルド、デプロイ等）を行っているか箇条書きで要約してください。

※AIの要約した結果は鵜呑みにせず、あくまで参考程度のものとして扱ってください。

3. 重要なWorkflowの「詳細」を掘り下げる

概要を掴んだ後は、改めてWorkflowの重要度を見直した上で、自分の担当領域（開発・インフラ・QAなど）に直接関係するワークフローから重点的にコードを読んでいきます。

ここでは例として、 「Terraformのplan / applyを実行するワークフロー」を対象に、個人的にチェックしているポイントを挙げます。

起動条件（Triggers）の確認

どの処理がいつ起動するかを把握することで、Terraformコードを変更する際や運用作業時のチェックポイントがわかります。

よく見るパターンとしては、以下のタイミングと処理内容が組み合わさるものがあります。

  • PRの作成・更新時: terraform fmt terraform validate やtflintなどのツールによる静的解析、terraform plan による実環境との差分チェック
  • mainブランチへのマージ: 前述のチェックを実行後に terraform apply を実行。プロジェクトによってはGitHub EnvironmentのRequired reviewersなどを利用して、承認後にapplyを実行する場合もあります。
  • 手動・スケジュール実行: Drift Detection用のWorkflowを定期的に起動するケースなどがあります。

また、Workflow自体が起動するトリガーのほか、特定の条件下でのみ実行するJob / Stepが定義されている場合もあります。

各Job/Stepで実行する処理内容

各Job/Stepで実行する内容、処理の分割粒度を確認します。

複雑な処理を行う、または開発時と処理を共通化する、などの場合、Workflowの定義ファイルだけに処理が収まっておらず、Reusable WorkflowsやMakefile / Shell script、TypeScript/JavaScriptなどに処理が外出しされているケースも多いです。YAMLだけでなく、それらが呼び出しているスクリプトも読めるようにしておくと理解がスムーズです。

また、処理の分割粒度について、例えばTerraformを扱うWorkflowでは、 terraform init terraform validate terraform plan など、処理の目的に応じてStepを分けることがあります。1つのStepに複数のコマンドをまとめることもできますが、適度に分割し、ログから失敗した処理を特定しやすくなり、Stepごとに条件やタイムアウトなどを設定できるようになります。

なお、完了時の通知先を把握すると、Workflowが失敗した際どこに通知が飛ぶのか（誰が落ちたことに気づける構造になっているか）把握できます。

使用するRunner（実行環境）

Workflowの実行環境として ubuntu-latest などのGitHub-hosted Runnerが使われているか、あるいはSelf-hosted Runnerが使われているか、をチェックします。

Self-hosted Runnerを利用するケースは、プライベートネットワーク内のリソースへのアクセスや、セキュリティ・コンプライアンス上の理由などがあります。一般には重要度の高い処理が行われるため、相対的に優先度の高いWorkflowといえます。

Terraformを扱うWorkflowでは、実行環境に機密情報を含むファイルが生成される可能性がある点に注意が必要です。例えば、保存済みのPlanファイルには、機密情報が平文で含まれる場合があります。そのため、Runnerの種類を確認するだけでなく、実行後にファイルがどのように扱われるか、後続のJobなどからアクセスできる状態で残らないかも確認しましょう。

権限周り（permissions / OIDC）

WorkflowのGitHubに対する実行権限をデフォルトから変更する場合は permissions で設定します。またWorkflowから外部サービスにアクセスする際の権限も別途追加する必要があります。

Terraformを扱うWorkflowの場合、多くはコードを適用する環境へのアクセス権限が必要となります。権限の付与方法は様々ですが、近年はOIDC (OpenID Connect) を使うことが主流です。

GitHubリポジトリへのWrite権限や外部サービスの変更権限などが付与されていれば、そのWorkflowは多くの操作が可能です。その分何か問題があった時の影響度も大きいと言えます。そのため、強い権限が付与されたWorkflowほど重要度が高く、かつ扱いに注意が必要なものであると判断できます。

その他

ここまでWorkflowの内容を追いかければ、どのWorkflowが重要か、おおよそ見当はつくかと思います。もし余裕があるなら、重要度の高いWorkflowをリストアップしておき、定期的にそれらのWorkflowに変更が入ったか見ておくと良いでしょう。

また、ここで重要度の高いWorkflowに分類されたものの「作成者」が誰かを押さえておくと、何か質問した時の問い合わせ先やPRレビュアーを見つけやすくなります。

4. 開発・運用ルールが明文化されているか確認する

既存のWorkflowの挙動が把握できたら、将来的に自分がWorkflowを修正・追加することを想定し、プロジェクト内の運用ルールを探します。

例えば以下のような場所を見ておくと、Rulesやガイドラインを見つけられることがあります。

  • リポジトリ内の README.md などのMarkdownファイル
  • 社内Wikiツール（Confluence, Notion, GitHub Wiki など）
  • AIエージェント用の指示ファイル（AGENTS.md, CLAUDE.md など）

5. Workflowの追加・変更・削除に取り組む

これまで整理した内容をもとに、Workflowの追加・変更・削除を行います。仮にWorkflowの変更を以下のような手順で進める場合、多くの場面でここまで整理した内容が生かされるかと思います。

  • 変更内容の確認: 実装する処理内容は何か、影響範囲はどの程度か、その時に必要な権限や実行場所は何かを押さえます。特にプロジェクト特有の情報や設定については、既存Workflowの内容を参考に検討することができます。例えばReusable Workflowを対象に作業する場合、それを修正・削除することで、プロジェクト内の広範囲に影響する可能性があります。
  • Workflowの設計・作成: Workflowの設計や作成は、既存Workflowやプロジェクト内ルールを確認してから着手します。例えばReusable Workflowで定義済みの処理があればそれを活用する、処理をスクリプトとして外出しするか検討する、既存Workflowに処理を追加するか新たなWorkflowを用意する、などの点です。
  • PRレビュー: 社内ルールやCODEOWNERSによってレビュー担当者が決まっている場合はそれに従います。担当者が明確でない場合、対象のWorkflowなどに詳しいメンバーを探します。過去のWorkflow作成者も、レビュー担当候補となります。

※なお、Workflowのテストをどのように実施すべきかについては、私もこうすべきという考えが出せていない状態です。パッと浮かぶのはWorkflowファイルの静的解析 (YAMLの構文チェックなど) 、PR上での実行 (pull_requestトリガーの場合は実行可能) などですが、場合によっては一時的に手動実行トリガー ( workflow_dispatch ) を追加する、actを利用する、などが挙げられます。

まとめ

今回は「既存プロジェクトのGitHub Actionsを効率よく読み解くためのチェックポイント」として、5つのポイントを取り上げました。

もしかしたら生成AIでGitHubリポジトリ全体を対象に指示すればサクッと出してくれるかもしれませんが、GitHub Actionsの概要をつかみたい、といった方は、上記ステップを参考にしてみるとスムーズに理解できるかもしれません。