このページの目次

このページの目次

パイプライン

適用範囲

これらの規則は、GitHub Actions、GitLab CI、CircleCI、Jenkins など、あらゆるシステムの CI/CD パイプラインに適用する。選択したシステム固有の規則は、対応するツールチェーン文書に記載されている。

デフォルトの選択

ユーザーがパイプラインシステムを明示していない場合は、GitHub Actions をデフォルトとする。プラットフォーム固有の規則については、GitHub Actionsを参照すること。

複雑化に伴う構造化

コマンドをただ並べただけのパイプラインは、長くなると読みにくくなる。名前のないステップを積み重ねるのではなく、ステージ、ジョブ、別ファイルに分けて構造化する。

  • パイプラインの各単位は、1 つの関心事だけを扱うこと。トリガーまたは対象者ごとにパイプラインファイルを 1 つ、責務ごとにジョブを 1 つ、コマンドごとにステップを 1 つとする。
  • 増大し続ける 1 つのファイルより、複数の小さなパイプラインファイルを優先する。
  • プロジェクトのロジックをパイプライン YAML に重複して記述せず、プロジェクト固有のタスクを呼び出すこと(miseを参照)。

チェック報告の完全性

  • 1 つのトリガーでしか動かないジョブを、複数トリガーのパイプラインに入れて条件分岐でスキップさせてはならない。そのトリガー専用のパイプラインファイルに分けること。
  • 条件分岐でスキップされたジョブも実行一覧に skipped として残る。そのため、読み手は想定どおりのスキップと失敗を区別し、起動したトリガーも推測する必要がある。
  • 実行一覧を見るだけで合否が分かるようにすること。パイプライン内のすべてのジョブは、そのパイプラインが起動したときには必ず実行される構成にする。
  • マージゲートは skipped の必須チェックも通過として扱うため、上のルールは主に可読性のためである。実際にマージを止めてしまう危険は、必須チェックが一度も結果を返さないケースにある。ワークフローが起動しなかったり、フィルターでジョブが除外されたりすると、チェックが pending のまま残りプルリクエストがブロックされる。必須チェックを求めるすべての場面で必ず結果が返るよう、ワークフローを分けること。

命名と可読性

実行ログだけで、各パイプライン、ジョブ、ステップの内容が分かるようにすること。

  • パイプライン、すべてのジョブ、すべてのステップに名前を付ける。
  • 名前はツールの呼び出しではなく責務を示す。cog ではなく Validate とする。
  • ステップ名は、そのステップが実行または検証する内容を示す、短い命令形の句とする。生のコマンドとして表示されるだけのステップは、実質的に名前がなく、コマンドはドキュメントではない。

関連

  • GitHub Actions — デフォルトのプラットフォーム。ワークフローの命名とハードニングの規則。
  • 品質ゲート — ローカル環境と CI で同じチェックを実行する。