# バッチ設計書 17-milestone.yml

## 概要

本ドキュメントは、GitHub Actions ワークフロー `milestone.yml` の設計仕様を記載したバッチ設計書です。PRマージ時およびIssueクローズ時にマイルストーンを自動設定するワークフローの詳細を説明します。

### 本バッチの処理概要

このバッチは、プロジェクト管理の自動化を実現するワークフローです。プルリクエストがマージされた際、およびIssueがクローズされた際に、適切なマイルストーンを自動的に設定します。これにより、リリース管理とプロジェクト進捗の追跡が効率化されます。

**業務上の目的・背景**：ソフトウェア開発プロジェクトでは、マイルストーンを使用してリリース計画を管理します。しかし、PRやIssueに手動でマイルストーンを設定する作業は煩雑で忘れられがちです。本ワークフローは、この管理作業を自動化し、全てのマージされたPRとクローズされたIssueが適切なマイルストーンに紐付けられることを保証します。

**バッチの実行タイミング**：イベント駆動で実行されます。PRがマージされた時（pull_request_target.closed + merged == true）、およびIssueがクローズされた時（issues.closed）にトリガーされます。

**主要な処理内容**：
1. PRマージイベントの検出とマイルストーン設定（bind-pr）
2. Issueクローズイベントの検出とマイルストーン設定（bind-issue）
3. 関連するPRの修正情報に基づくマイルストーン関連付け

**前後の処理との関連**：本ワークフローは独立して実行されます。PRのマージやIssueのクローズなど、他のワークフローや人間の操作によって引き起こされるイベントに反応します。マイルストーン設定自体は他のワークフローに影響しません。

**影響範囲**：GitHub上のPRとIssueのマイルストーン設定が更新されます。リポジトリのマイルストーン管理に影響を与えますが、コードやビルドには影響しません。

## バッチ種別

イベント駆動 / プロジェクト管理自動化

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動 |
| 実行時刻 | 指定なし |
| 実行曜日 | 指定なし |
| 実行日 | 指定なし |
| トリガー | issues.closed / pull_request_target.closed |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| PRマージ | pull_request_target.closed かつ merged == true |
| Issueクローズ | issues.closed かつ state == 'closed' |
| マイルストーン存在 | 設定対象のマイルストーンが存在すること |

### 実行可否判定

- PRマイルストーン設定：`github.event.pull_request.merged == true` の条件でマージされたPRのみ対象
- Issueマイルストーン設定：`github.event.issue.state == 'closed'` の条件でクローズされたIssueのみ対象

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | 入力パラメータなし（イベントデータを使用） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| github.event.pull_request | オブジェクト | PRイベントデータ |
| github.event.issue | オブジェクト | Issueイベントデータ |
| GitHub Milestones | API | リポジトリのマイルストーン一覧 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| GitHub PR/Issue | メタデータ | マイルストーン設定 |
| GitHub Actions ログ | テキスト | 処理結果 |

### 出力ファイル仕様

本ワークフローではファイル出力は行いません。

## 処理フロー

### 処理シーケンス

```
1. イベント検出
   └─ PRクローズまたはIssueクローズイベントを検知
2. 条件判定
   ├─ PRの場合: merged == true を確認
   └─ Issueの場合: state == 'closed' を確認
3. マイルストーン設定
   ├─ PRの場合: bind-pr アクションで設定
   └─ Issueの場合: bind-issue アクションで設定
4. 完了
   └─ 設定結果をログに出力
```

### フローチャート

```mermaid
flowchart TD
    A[イベント発生] --> B{イベント種別}
    B -->|PR closed| C{マージ済み?}
    B -->|Issue closed| D{クローズ済み?}
    C -->|Yes| E[bind-pr 実行]
    C -->|No| F[スキップ]
    D -->|Yes| G[bind-issue 実行]
    D -->|No| H[スキップ]
    E --> I[マイルストーン設定完了]
    G --> I
    F --> J[ワークフロー終了]
    H --> J
    I --> J
```

## データベース操作仕様

本ワークフローではデータベース操作は行いません。GitHub APIを通じてPR/Issueのメタデータを更新します。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 認証エラー | GITHUB_TOKENの権限不足 | トークン権限を確認 |
| - | マイルストーン不在 | 設定対象のマイルストーンが存在しない | マイルストーンを作成 |
| - | API制限 | GitHub API制限に到達 | 時間をおいて確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（自動リトライなし） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

1. GitHub Actions UIでエラーログを確認
2. GITHUB_TOKENの権限を確認
3. マイルストーンの存在を確認
4. 必要に応じて手動でマイルストーンを設定

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 単一PR/Issue単位 |
| コミットタイミング | API呼び出し完了時 |
| ロールバック条件 | ロールバック不可（手動で修正可能） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1件/イベント |
| 目標処理時間 | 1分以内 |
| メモリ使用量上限 | 指定なし |

## 排他制御

排他制御は設定されていません。各イベントは独立して処理されます。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ワークフロー開始時 | GitHub Actions標準ログ |
| 処理ログ | マイルストーン設定時 | 設定対象と結果 |
| 終了ログ | ワークフロー終了時 | ジョブ完了ステータス |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ワークフロー失敗 | 1回 | GitHub通知 |

## 備考

- hustcer/milestone-action@v3.1 を使用
- PRマージ時: action: bind-pr（デフォルトアクション）
- Issueクローズ時: action: bind-issue
- namespace-profile-ghostty-smランナーで実行
- GITHUB_TOKENを使用（secrets.GITHUB_TOKEN）
- pull_request_targetを使用することでフォークからのPRも処理可能
