# バッチ設計書 2-Stale Issues/PR Manager

## 概要

本ドキュメントは、Stale Issues/PR Managerバッチ（stale.yml）の設計仕様を記載したものである。このバッチは、非アクティブなIssueおよびPull Requestを自動的に検出し、staleラベルを付与した後、一定期間経過後にクローズする定期実行バッチである。

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

**業務上の目的・背景**：開発プロジェクトでは、長期間更新されていないIssueやPRが蓄積し、リポジトリの管理が煩雑になる問題がある。本バッチはactions/staleアクションを利用して、非アクティブなIssue/PRを自動的に管理し、リポジトリの健全性を維持する。これにより、開発チームは実際にアクティブなIssue/PRに集中でき、プロジェクト管理の効率が向上する。

**バッチの実行タイミング**：毎日22:00 JST（UTC 13:00）に定期実行される。手動実行（workflow_dispatch）も可能である。

**主要な処理内容**：
1. リポジトリ内のすべてのオープンIssue/PRをスキャン
2. 60日間更新がないIssueにstaleラベルを付与し、警告メッセージをコメント
3. staleラベル付与後5日間（合計65日間非アクティブ）でIssueを自動クローズ
4. PRに対しても同様の処理を実行（警告メッセージは異なる）

**前後の処理との関連**：本バッチは独立して動作し、他のバッチへの依存関係はない。staleラベルが付与されたIssue/PRに対してユーザーが何らかのアクション（コメント、更新等）を行うと、staleラベルは自動的に削除される。

**影響範囲**：GitHubリポジトリのすべてのオープンIssueおよびPull Request

## バッチ種別

Issue/PR管理 / クリーンアップ

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 日次 |
| 実行時刻 | 22:00 JST（UTC 13:00） |
| 実行曜日 | 毎日 |
| 実行日 | - |
| トリガー | cron / 手動（workflow_dispatch） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| GITHUB_TOKEN | リポジトリへのIssue/PR操作権限があること |
| staleラベル | `stale`ラベルがリポジトリに存在すること（自動作成される） |

### 実行可否判定

- スケジュール時刻（UTC 13:00）に自動実行
- オープンなIssue/PRが存在しない場合も正常終了（処理対象なし）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| repo-token | string | Yes | ${{ secrets.GITHUB_TOKEN }} | GitHub API認証トークン |
| days-before-issue-stale | number | No | 60 | Issueにstaleラベルを付与するまでの非アクティブ日数 |
| days-before-issue-close | number | No | 5 | staleラベル付与後クローズまでの日数 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| GitHub Issues API | JSON | リポジトリ内のオープンIssue一覧 |
| GitHub Pull Requests API | JSON | リポジトリ内のオープンPR一覧 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| GitHub Issue Labels | API操作 | staleラベルの付与 |
| GitHub Issue Comments | API操作 | staleメッセージのコメント追加 |
| GitHub Issue State | API操作 | 非アクティブIssue/PRのクローズ |

### 出力ファイル仕様

ファイル出力なし（GitHub APIを通じた操作のみ）

## 処理フロー

### 処理シーケンス

```
1. actions/staleアクション実行開始
   └─ actions/stale@v9.1.0を使用
2. オープンIssueのスキャン
   └─ 最終更新日から60日以上経過したIssueを検出
   └─ 該当Issueにstaleラベルを付与
   └─ 警告メッセージをコメントとして追加
3. オープンPRのスキャン
   └─ 最終更新日から一定期間経過したPRを検出
   └─ 該当PRにstaleラベルを付与
   └─ 警告メッセージをコメントとして追加
4. クローズ対象の処理
   └─ staleラベル付与後5日以上経過したIssueをクローズ
5. 処理完了
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[actions/stale実行]
    B --> C[オープンIssueスキャン]
    C --> D{60日以上非アクティブ?}
    D -->|はい| E[staleラベル付与]
    E --> F[警告コメント追加]
    D -->|いいえ| G[スキップ]
    F --> H{staleから5日経過?}
    G --> H
    H -->|はい| I[Issueクローズ]
    H -->|いいえ| J[次のIssueへ]
    I --> J
    J --> K{全Issue処理完了?}
    K -->|いいえ| C
    K -->|はい| L[オープンPRスキャン]
    L --> M[同様の処理]
    M --> N[バッチ終了]
```

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

### 操作別データベース影響一覧

データベース操作なし（GitHub APIのみ使用）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | API Rate Limit | GitHub APIレート制限超過 | 次回実行時に処理継続 |
| - | Permission Error | トークン権限不足 | GITHUB_TOKENの権限確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | actions/staleアクション内部で制御 |
| リトライ間隔 | - |
| リトライ対象エラー | API一時エラー |

### 障害時対応

- ワークフロー失敗時：GitHub Actionsの実行ログを確認し、原因特定後に手動で再実行
- 部分的失敗：次回実行時に未処理のIssue/PRが処理される

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | Issue/PR単位 |
| コミットタイミング | 各API呼び出し時 |
| ロールバック条件 | なし（GitHub APIはトランザクション非対応） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | リポジトリ内の全オープンIssue/PR |
| 目標処理時間 | 10分以内（timeout-minutes: 10） |
| メモリ使用量上限 | GitHub Actions標準ランナー制限内 |

## 排他制御

- 特に排他制御なし
- 同時実行されても、actions/staleアクションが適切に処理

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | バッチ開始時 | actions/staleアクション開始 |
| 進捗ログ | 処理中 | 各Issue/PRの処理状況 |
| 終了ログ | バッチ終了時 | 処理結果サマリー |
| エラーログ | エラー発生時 | エラー詳細 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理時間 | 10分 | GitHub Actionsタイムアウト |
| エラー発生 | - | GitHub Actionsログ |

## 備考

- staleラベルが付与されたIssue/PRに対してアクティビティ（コメント、更新等）があると、staleラベルは自動的に削除される
- Issueのstaleメッセージ：「This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.」
- PRのstaleメッセージ：「This Pull Request has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.」
- 60日後stale、65日後close（stale後5日）の設定
