このページの目次

このページの目次

GitHub Actions

標準プラットフォーム

GitHub Actions は標準の CI/CD プラットフォームであり、ユーザーがパイプラインシステムを指定していない場合のデフォルトである。ツールに依存しないパイプラインの規則は パイプライン に記載されている。

アクション更新のチェックリスト

GitHub Actions のワークフローを作成または変更するときは、次の事項を確認する。

  1. 使用するアクションに新しい安定版があるか確認する。
  2. 更新前に公式の README またはドキュメントを確認する。
  3. 破壊的変更がないか確認する。
  4. 必要な入力、権限、ランタイムバージョン、挙動に変更がないか確認する。
  5. 移行が安全な場合は、現在サポートされているバージョンへの移行を優先する。

リリースノートや移行手順を確認せずに、アクションのバージョン番号だけを書き換えないこと。メジャーバージョンタグ(@v4 など)はマイナー・パッチ更新を自動で取り込むため、このチェックリストはメジャーバージョンを跨ぐ更新で使う。

CI の階層構造

CI でも、可能な限りローカル開発で使う標準のプロジェクトツールと同じものを使う。

次の構造を優先する。

GitHub Actions
    -> mise
        -> project task
            -> pnpm / uv / prek / cocogitto / test tooling

プロジェクトのロジックをワークフロー YAML に直接重複して記述するのではなく、この構造を使う。

mise を CI から呼び出すエントリーポイントとし、ツールのセットアップ手順をワークフロー YAML に重複して記述しないこと。詳細は mise を参照。

イベントスコープ

  • 同じチェックを必要とするトリガーを、同じワークフローファイルにまとめる。プロジェクト検証のワークフローは push(デフォルトブランチ)と pull_request で実行し、プルリクエストにしか存在しない規則(プルリクエストのタイトル規則など)は、pull_request 単独をトリガーとする独立したワークフローに置く。
  • この分割を、複数トリガーのワークフロー内のジョブに if: github.event_name == 'pull_request' を付けて模倣しないこと。push の実行ではそのジョブが skipped と表示され、実行全体が部分的な失敗に見える。ツールに依存しない規則は パイプライン を参照。
  • pull_request のデフォルトは opened、synchronize、reopened であり、コードの検証にはこの組み合わせが適している。デフォルトを超える場合にのみ types: を列挙する。編集で変わりうるプルリクエストのメタデータ(タイトル)を検証するワークフローは edited を追加し、タイトルを変更したプルリクエストが再検証されるようにする。結果を変えられないアクティビティタイプを列挙しないこと。列挙したタイプはそれぞれ新たなトリガーになる。
  • マージゲートは skipped の必須チェックも通過とみなすため、この規則は実行一覧を読みやすくするためのものである。実際にマージを止めてしまう危険は、ワークフローが pull_request で起動しない、またはジョブがフィルターで除外されて一度も結果が返らず、pending のまま残るケースである。必須チェックは、必要なすべての場面で必ず実行され結果が返るように構成すること。

チェックアウトの深さ

  • actions/checkout はデフォルトで 1 つのコミットだけを取得する。デフォルトを維持すること。ほとんどのジョブに必要なのは、検証対象のツリーだけである。
  • 履歴を読み取るジョブ(cog check、変更履歴の生成、git describe、ベースとの差分ロジック)でのみ fetch-depth: 0 を設定すること。
  • 1 つの責務だけが完全な履歴を必要とし、他は必要としない場合は、共有チェックアウトを深くするのではなく、その責務を専用のジョブに分割すること。パイプライン の原則では、履歴の読み取りもそれ自体が 1 つの責務であり、分割すれば検証ジョブのチェックアウトを浅く保てる。

命名と可読性

ツールに依存しない原則については パイプライン を参照。

GitHub Actions 固有の規則は次のとおりである。

  • ワークフローには、目的を示す name を設定する(CI、Release など)。ファイル名に頼らず、ジョブ名をワークフロー名としてそのまま使わない。
  • すべてのジョブにわかりやすい name を設定する。ジョブ名はブランチ保護のステータスチェックとして表示されるため、失敗したチェックからツールの呼び出しではなく責務(Validate、Validate PR title)を特定できるようにする。
  • すべてのステップには、何をするか、何を検証するかを示す短い命令形のフレーズで名前を付ける(Install dependencies (pnpm)、Check commit history (cog) など)。name のない run: ステップは生のコマンドとして表示されるが、コマンドはドキュメントではない。
  • 1 つのワークフローファイルには 1 つの関心事だけを持たせる。トリガーや対象者が分かれる場合は分割し、肥大化した 1 つのファイルより複数の小さなワークフローを優先する。

ハードニングの既定設定

明確な理由がない限り、すべてのワークフローに次を適用する。

permissions:
  contents: read

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  validate:
    timeout-minutes: 15
  • 最小権限:permissions はデフォルトで contents: read とし、必要なジョブでのみ権限を広げる。
  • すべてのジョブに timeout-minutes を設定し、ハングしたジョブがプラットフォームのデフォルト上限までランナーの実行時間を消費しないようにする。
  • cancel-in-progress 付きの concurrency を使い、同じ ref で置き換えられた実行をキューに残さず、キャンセルする。
  • 信頼できない入力(プルリクエストのタイトル、ブランチ名、issue の内容)は、環境変数を介して run: スクリプトに渡し、${{ }} に直接埋め込まないこと。直接埋め込むと、スクリプトインジェクションが可能になる。
  • 信頼できる発行元が提供する現在のメジャーバージョンタグでアクションを参照すること(actions/checkout@v7、jdx/mise-action@v4)。タグの参照先は、そのメジャー内の修正、ランタイム更新、新機能を含むバージョンへ継続的に更新され、アップグレードはレビュー担当者が読み取れる 1 トークンの差分になる。
  • 完全なコミット SHA よりタグを優先すること。SHA はアクションを 1 つのリビジョンに固定するため、修正が届かず、ワークフローが実行バージョンを示さなくなり、アップグレードのたびに SHA を手動で検索することになる。SHA を固定するのは、不変ビルドまたはサプライチェーンポリシーで明示的に定められている場合に限り、解決済みバージョンを末尾コメントに記録すること。裸のブランチ名やバージョンなしのタグをアクションに使用しないこと。
  • 浮動するメジャータグは発行元を信頼することを意味する。上記の最小権限のデフォルトと組み合わせ、プルリクエストのコードを実行するワークフローにシークレットを決して公開しないこと。
  • pull_request_target を使ってプルリクエストのコードをチェックアウトし、実行しないこと。リポジトリのシークレット付きでベースブランチのワークフロー定義が実行される。pull_request を使うこと。

関連

  • パイプライン — どの CI システムにも適用できるパイプラインの構造と命名に関する規則。
  • 品質ゲート — 同じプロジェクト設定で、ローカルと同等のチェックを実行する。
  • Git ワークフロー — CI における Conventional Commits の検証。squash merge 時のプルリクエストタイトルに関する規則を含む。