# バッチ設計書 9-stale-issues.yml

## 概要

本ドキュメントは、OpenCodeプロジェクトの非アクティブIssue自動クローズワークフロー（stale-issues.yml）の設計仕様を定義する。このワークフローは90日以上活動のないIssueにstaleラベルを付与し、さらに7日後に自動クローズする。

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

このワークフローは、actions/staleアクションを使用して、長期間活動のないIssueを自動的に整理する。90日間更新がないIssueにはstaleラベルが付与され、警告メッセージが投稿される。staleラベル付与後7日間経過しても更新がない場合、Issueは自動的にクローズされる。

**業務上の目的・背景**：オープンソースプロジェクトでは、多数のIssueが報告されるが、一部は時間の経過とともに関連性を失ったり、解決済みになったりする。長期間活動のないIssueを放置すると、Issue一覧が肥大化し、本当に対処が必要なIssueの把握が困難になる。本バッチにより、非アクティブなIssueを自動的に整理し、Issue管理の効率化と健全なバックログ維持を実現する。

**バッチの実行タイミング**：毎日01:30 AMにスケジュール実行される。手動でのworkflow_dispatchトリガーも可能。

**主要な処理内容**：
1. 全オープンIssueをスキャン
2. 90日以上活動のないIssueにstaleラベルを付与
3. staleラベル付与時に警告メッセージを投稿
4. 7日以上stale状態が継続したIssueをクローズ
5. クローズ時にクローズメッセージを投稿
6. 更新があった場合はstaleラベルを自動削除

**前後の処理との関連**：独立したバッチとして動作。close-stale-prs.ymlと同様の目的を持つが、対象がIssueである点が異なる。

**影響範囲**：GitHubリポジトリのIssueのラベル、状態、コメントに影響を与える。

## バッチ種別

Issue管理 / 自動クリーンアップ

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 日次 |
| 実行時刻 | 01:30 AM UTC |
| 実行曜日 | 毎日 |
| 実行日 | 毎日 |
| トリガー | cron（30 1 * * *）、手動実行 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| issues: write | Issue書き込み権限 |
| 開始日 | 2025-12-27以降に作成されたIssueが対象 |

### 実行可否判定

ワークフローは常に実行される。actions/staleアクションが内部でIssueの状態を評価する。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| DAYS_BEFORE_STALE | number | No | 90 | stale判定までの日数 |
| DAYS_BEFORE_CLOSE | number | No | 7 | stale後クローズまでの日数 |

### 入力データソース

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

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| Issue labels | ラベル | staleラベルの付与/削除 |
| Issue state | 状態 | オープン→クローズ |
| Issue comments | テキスト | stale警告/クローズメッセージ |

### 出力ファイル仕様

ファイル出力なし。GitHub API操作のみ。

## 処理フロー

### 処理シーケンス

```
1. オープンIssueのスキャン
   └─ actions/stale@v10

2. stale判定（90日ルール）
   ├─ 90日以上活動なし → staleラベル付与
   ├─ 警告メッセージ投稿
   └─ 免除ラベルがある場合はスキップ

3. クローズ判定（7日ルール）
   ├─ staleラベル付与後7日経過 → クローズ
   └─ クローズメッセージ投稿

4. stale解除判定
   └─ 更新があった場合 → staleラベル削除
```

### フローチャート

```mermaid
flowchart TD
    A[ワークフロー開始] --> B[オープンIssueスキャン]
    B --> C{免除ラベルあり?}
    C -->|Yes| D[スキップ]
    C -->|No| E{90日以上非活動?}
    E -->|No| D
    E -->|Yes| F{staleラベルあり?}
    F -->|No| G[staleラベル付与]
    G --> H[警告メッセージ投稿]
    F -->|Yes| I{7日以上経過?}
    I -->|No| D
    I -->|Yes| J[Issueクローズ]
    J --> K[クローズメッセージ投稿]
    D --> L{更新あり?}
    L -->|Yes| M[staleラベル削除]
    L -->|No| N[ワークフロー終了]
    H --> N
    K --> N
    M --> N
```

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

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

本ワークフローはデータベース操作を行わない。GitHub API操作のみ。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | API制限 | GitHub APIレート制限 | 次回実行で再試行 |
| - | 権限エラー | issues: write権限不足 | ワークフロー権限確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（次回スケジュール実行で再試行） |
| リトライ間隔 | 24時間（スケジュール間隔） |
| リトライ対象エラー | 全てのエラー |

### 障害時対応

1. API制限：次回実行を待つか、手動でworkflow_dispatchを実行
2. 権限エラー：ワークフローのpermissions設定を確認
3. 誤クローズ：Issue作成者がIssueを再オープン可能

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | なし（Issue単位で処理） |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし（手動再オープン可能） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | Issue数: 全オープンIssue |
| 目標処理時間 | 10分以内 |
| メモリ使用量上限 | 特に制限なし |

## 排他制御

特になし。actions/staleアクション内で適切に処理される。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| ワークフローログ | 全ステップ | actions/staleの出力 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ワークフロー失敗 | 発生時 | GitHub Actions通知 |

## 備考

- 免除ラベル：pinned、security、feature-request、on-hold
- 開始日：2025-12-27（これ以前のIssueは対象外）
- stale警告メッセージ：
  ```
  [automated] This issue has had no activity for 90 days.
  It will be closed in 7 days if there's no new activity.
  ```
- クローズメッセージ：
  ```
  [automated] Closing due to 90+ days of inactivity.
  Feel free to reopen if you still need this!
  ```
- remove-stale-when-updated: true により、更新があればstaleラベルが自動削除
- actions/stale@v10を使用
- ubuntu-latestランナーで実行
