リリース判定チェックリストで定義すべきこと — YAML 定義と Python 自動検証

なぜチェックリストが必要か

ソフトウェアリリースは多くの手順と確認事項が絡み合う複雑なプロセスだ。経験豊富なエンジニアでも、リリース直前の緊張やプレッシャーの下では確認漏れが発生する。特に以下のケースでチェックリストの欠如が重大インシデントにつながることが多い。

テストは CI で全パスしていたが、本番環境固有の設定変更を忘れていた
CHANGELOG は更新したが、リリースノートを作成しないまま公開した
ロールバック手順を確認せずにリリースし、障害発生後に慌てて調べることになった
セキュリティレビューを「次回やる」と先送りして本番に投入した

チェックリストは「人間の記憶」への依存をなくし、必須条件をコードとして定義することでリリース品質を制度的に担保する手段だ。さらに Python スクリプトで自動検証することで、CI/CD パイプラインの品質ゲートとして機能させられる。

必須チェック項目のカテゴリ

チェック項目は6つのカテゴリに分類して定義する。各カテゴリの目的と代表的な項目を示す。

カテゴリ	目的	代表的なチェック項目
🧪 テスト品質	コードの動作品質の保証	全ユニットテスト CI パス / 統合テスト完了 / カバレッジ閾値達成
📝 ドキュメント	変更内容の記録と周知	CHANGELOG 更新 / リリースノート作成 / API ドキュメント更新
🔒 セキュリティ	脆弱性混入の防止	セキュリティレビュー完了 / 依存ライブラリ脆弱性スキャン / 認証・認可テスト
🌐 環境確認	本番環境への適合性確認	ステージング動作確認 / 設定値・環境変数確認 / DB マイグレーション検証
🔄 ロールバック	障害時の回復手段の確保	ロールバック手順文書化 / ロールバック実施可能確認 / バックアップ完了
📢 コミュニケーション	関係者への事前通知	リリーススケジュール周知 / メンテナンス通知送信 / 監視ダッシュボード確認

💡 必須（required）と任意（optional）の区別が重要

すべての項目を「必須」にすると、小規模なパッチリリースでも大量の確認作業が発生しチェックリストが形骸化する。リリース種別（MAJOR / MINOR / PATCH）ごとに required の範囲を変えることが現実的な運用に近づける。

YAML 定義フォーマット

チェックリストを YAML ファイルとして定義することで、Python スクリプトによる自動検証が可能になる。リポジトリの release/ または docs/release/ ディレクトリに配置し、バージョン管理に含める。

YAML — release-checklist.yaml

version: "1.4.0"
release_date: "2026-06-27"
release_type: "minor"  # major / minor / patch

checks:
  - id: ci_tests_pass
    category: testing
    description: "全ユニットテスト・統合テストが CI でパスしている"
    required: true
    verified: false
    verified_by: ""
    verified_at: ""

  - id: changelog_updated
    category: documentation
    description: "CHANGELOG.md を更新し、[Unreleased] から バージョンブロックへ昇格させた"
    required: true
    verified: false
    verified_by: ""
    verified_at: ""

  - id: release_notes_created
    category: documentation
    description: "リリースノート（ユーザー向け・開発者向け）を作成した"
    required: true
    verified: false
    verified_by: ""
    verified_at: ""

  - id: security_review
    category: security
    description: "セキュリティレビューを完了した"
    required: true
    verified: false
    verified_by: ""
    verified_at: ""

  - id: staging_confirmed
    category: environment
    description: "ステージング環境で全機能の動作確認を完了した"
    required: true
    verified: false
    verified_by: ""
    verified_at: ""

  - id: rollback_plan
    category: rollback
    description: "ロールバック手順を文書化し、実施可能なことを確認した"
    required: true
    verified: false
    verified_by: ""
    verified_at: ""

  - id: api_docs_updated
    category: documentation
    description: "API ドキュメントを更新した（API 変更がある場合）"
    required: false
    verified: false
    verified_by: ""
    verified_at: ""

YAML の各フィールドの定義を以下に示す。

フィールド	型	説明
`id`	string	チェック項目の一意識別子（スネークケース）
`category`	string	カテゴリ（testing / documentation / security / environment / rollback / communication）
`description`	string	確認内容を自然言語で記述
`required`	boolean	リリースの必須条件か（false の場合は任意）
`verified`	boolean	確認完了フラグ（完了時に true へ更新）
`verified_by`	string	確認者の名前または GitHub ID
`verified_at`	string	確認日時（ISO 8601 形式）

判定フロー図

YAML 定義されたチェックリストを Python スクリプトが読み込み、必須項目が全て verified: true であれば GO、一つでも未完了であれば NO-GO と判定するフローを示す。

図1：YAML チェックリスト → Python 検証 → GO/NO-GO 判定フロー

Python 自動検証スクリプト

YAML チェックリストを読み込み、必須項目の完了状況を検証して GO/NO-GO を判定するスクリプトだ。未完了の必須項目がある場合は exit code 1 を返し、CI/CD パイプラインをブロックする。

Python — validate_checklist.py

"""
リリース判定チェックリスト 自動検証スクリプト
YAML で定義されたチェックリストを読み込み、
必須項目が全て verified: true であることを確認する。
"""

import sys
import yaml
from pathlib import Path
from dataclasses import dataclass
from typing import Optional


@dataclass
class CheckItem:
    id: str
    category: str
    description: str
    required: bool
    verified: bool
    verified_by: str = ""
    verified_at: str = ""


@dataclass
class ChecklistResult:
    version: str
    release_date: str
    items: list[CheckItem]

    @property
    def required_items(self) -> list[CheckItem]:
        return [i for i in self.items if i.required]

    @property
    def unverified_required(self) -> list[CheckItem]:
        return [i for i in self.required_items if not i.verified]

    @property
    def go(self) -> bool:
        return len(self.unverified_required) == 0

    def report(self) -> None:
        print(f"{'='*60}")
        print(f"  リリース判定レポート v{self.version} ({self.release_date})")
        print(f"{'='*60}")

        # カテゴリ別に整理
        by_category: dict[str, list[CheckItem]] = {}
        for item in self.items:
            by_category.setdefault(item.category, []).append(item)

        for category, items in by_category.items():
            print(f"\n[{category.upper()}]")
            for item in items:
                status = "✅" if item.verified else ("❌" if item.required else "⚪")
                label = "[必須]" if item.required else "[任意]"
                print(f"  {status} {label} {item.description}")
                if item.verified and item.verified_by:
                    print(f"       確認者: {item.verified_by} ({item.verified_at})")

        print(f"\n{'='*60}")
        total = len(self.required_items)
        done = total - len(self.unverified_required)
        print(f"  必須項目: {done}/{total} 完了")

        if self.go:
            print("  判定: ✅ GO — リリース可能です")
        else:
            print("  判定: ❌ NO-GO — 以下の必須項目が未完了です:")
            for item in self.unverified_required:
                print(f"    - [{item.id}] {item.description}")
        print(f"{'='*60}")


def load_checklist(path: str) -> ChecklistResult:
    data = yaml.safe_load(Path(path).read_text(encoding="utf-8"))
    items = [
        CheckItem(
            id=c["id"],
            category=c.get("category", "other"),
            description=c["description"],
            required=c.get("required", True),
            verified=c.get("verified", False),
            verified_by=c.get("verified_by", ""),
            verified_at=c.get("verified_at", ""),
        )
        for c in data.get("checks", [])
    ]
    return ChecklistResult(
        version=str(data.get("version", "unknown")),
        release_date=str(data.get("release_date", "")),
        items=items,
    )


def main() -> int:
    path = sys.argv[1] if len(sys.argv) > 1 else "release-checklist.yaml"
    if not Path(path).exists():
        print(f"❌ ファイルが見つかりません: {path}")
        return 1

    try:
        result = load_checklist(path)
    except (yaml.YAMLError, KeyError) as e:
        print(f"❌ YAML パースエラー: {e}")
        return 1

    result.report()
    return 0 if result.go else 1


if __name__ == "__main__":
    sys.exit(main())

検証結果の出力例

未完了の必須項目がある場合の出力例を示す。NO-GO の場合は exit code 1 が返され CI をブロックする。

Shell — 実行結果（NO-GO の場合）

============================================================
  リリース判定レポート v1.4.0 (2026-06-27)
============================================================

[TESTING]
  ✅ [必須] 全ユニットテスト・統合テストが CI でパスしている
       確認者: alice (2026-06-26T18:00:00Z)

[DOCUMENTATION]
  ❌ [必須] CHANGELOG.md を更新し、[Unreleased] からバージョンブロックへ昇格させた
  ❌ [必須] リリースノート（ユーザー向け・開発者向け）を作成した
  ⚪ [任意] API ドキュメントを更新した（API 変更がある場合）

[SECURITY]
  ✅ [必須] セキュリティレビューを完了した
       確認者: bob (2026-06-26T14:00:00Z)

[ENVIRONMENT]
  ✅ [必須] ステージング環境で全機能の動作確認を完了した
       確認者: alice (2026-06-27T09:00:00Z)

[ROLLBACK]
  ✅ [必須] ロールバック手順を文書化し、実施可能なことを確認した
       確認者: charlie (2026-06-26T16:00:00Z)

============================================================
  必須項目: 4/6 完了
  判定: ❌ NO-GO — 以下の必須項目が未完了です:
    - [changelog_updated] CHANGELOG.md を更新し...
    - [release_notes_created] リリースノート（ユーザー向け・開発者向け）を作成した
============================================================

CI/CD への組み込み

チェックリスト検証を GitHub Actions のリリースワークフローに組み込む例を示す。必須項目が未完了の場合はワークフローが失敗し、本番デプロイをブロックする。

YAML — .github/workflows/release-gate.yml

name: Release Gate Check

on:
  workflow_dispatch:
  push:
    branches:
      - "release/**"

jobs:
  checklist-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install dependencies
        run: pip install pyyaml

      - name: Validate release checklist
        run: |
          python tools/validate_checklist.py release/release-checklist.yaml
        # exit code 1 → workflow fails → deploy is blocked

  deploy:
    needs: checklist-gate
    runs-on: ubuntu-latest
    if: success()
    steps:
      - name: Deploy to production
        run: echo "Deploying..."

運用上のヒント

✅ チェックリストはリリースブランチ作成と同時に生成する

make release VERSION=1.4.0 のような Makefile ターゲットで、バージョン番号を埋め込んだ YAML チェックリストを自動生成する。手動でコピーするとバージョン番号の記載漏れが発生する。

💡 verified フラグの更新は PR でレビューさせる

YAML の verified: true への変更は通常の PR として提出し、別のメンバーにレビューさせる。「確認した人が承認する」という二重チェックの仕組みが品質ゲートの信頼性を高める。

⚠️ チェックリストの形骸化を防ぐ

「いつも全部チェックしている」状態になったらレビューのタイミングだ。実際に引っかかった項目・それが防いだインシデントを四半期ごとに振り返り、チェックリストを最適化し続けることが重要だ。

まとめ

リリース判定チェックリストは、人間の記憶への依存をなくしてリリース品質を制度的に担保するドキュメントだ。以下の3点を実装すれば、CI/CD の品質ゲートとして機能する。

YAML 定義：チェック項目・必須/任意・確認者・確認日時をリポジトリで管理する
Python 自動検証：必須項目の未完了があれば exit code 1 → CI ブロックを実現する
PR フロー統合：verified: true への更新を PR レビューで二重チェックする

✅ 関連記事

チェックリストと連動して管理するドキュメントとして、アーキテクチャの決定記録を残す ADR も重要だ。次の記事「ADR（Architecture Decision Record）で定義すべきこと」では、技術的意思決定を将来の開発者へ引き継ぐ方法を解説する。

リリース判定チェックリストで定義すべきこと
YAML 定義・必須項目・Python による GO/NO-GO 自動判定