# バッチ設計書 12-clean-artifacts.yml

## 概要

本ドキュメントは、GitHub Actions ワークフロー `clean-artifacts.yml` の設計仕様を記載したバッチ設計書です。GitHub Actionsのアーティファクトを定期的にクリーンアップする自動化処理の詳細を説明します。

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

このバッチは、GitHub Actionsで生成された古いアーティファクト（ビルド成果物）を自動的に削除し、ストレージ使用量を最適化します。1週間以上経過したアーティファクトを毎日定期的に削除することで、リポジトリのストレージコストを抑制し、不要なデータの蓄積を防ぎます。

**業務上の目的・背景**：GitHub Actionsでは、ワークフロー実行時にビルド成果物やテスト結果などのアーティファクトが生成されます。これらは時間経過とともに蓄積し、GitHubのストレージ制限に影響を与える可能性があります。特に活発に開発されているプロジェクトでは、日々多くのアーティファクトが生成されるため、定期的なクリーンアップが必要です。本ワークフローは、この運用タスクを自動化し、手動管理の負担を排除します。

**バッチの実行タイミング**：毎日0時（UTC）にスケジュール実行されます。また、workflow_dispatchによる手動実行も可能であり、緊急のクリーンアップが必要な場合に対応できます。

**主要な処理内容**：
1. 1週間以上経過したアーティファクトの特定
2. タグ付きリリースに関連するアーティファクトの除外
3. 直近5件のアーティファクトの保持
4. 条件に合致するアーティファクトの削除

**前後の処理との関連**：本ワークフローは独立して実行され、他のワークフローとの依存関係はありません。他のワークフローで生成されたアーティファクトを対象としますが、それらの実行状態には影響しません。

**影響範囲**：GitHubリポジトリに保存されている全てのアーティファクトが対象となります。ただし、タグ付きリリースのアーティファクトと直近5件のアーティファクトは保護されます。削除されたアーティファクトは復元できません。

## バッチ種別

データクレンジング / メンテナンス

## 実行スケジュール

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

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| GitHub Actions有効 | リポジトリでGitHub Actionsが有効であること |
| アーティファクト存在 | 削除対象となるアーティファクトが存在すること |

### 実行可否判定

特別な実行可否判定はありません。スケジュールまたは手動トリガーで常に実行されます。削除対象のアーティファクトが存在しない場合でもエラーにはならず、正常終了します。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | 入力パラメータなし |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| GitHub Artifacts API | API | リポジトリのアーティファクト一覧 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| GitHub Actions ログ | テキスト | 削除されたアーティファクトの情報 |

### 出力ファイル仕様

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

## 処理フロー

### 処理シーケンス

```
1. ワークフロー開始
   └─ スケジュールまたは手動トリガーで開始
2. アーティファクト一覧取得
   └─ GitHub APIでリポジトリの全アーティファクトを取得
3. 削除対象フィルタリング
   └─ 1週間以上経過、タグなし、直近5件以外を特定
4. アーティファクト削除
   └─ 条件に合致するアーティファクトを削除
5. ワークフロー終了
   └─ 削除結果をログに出力
```

### フローチャート

```mermaid
flowchart TD
    A[ワークフロー開始] --> B[アーティファクト一覧取得]
    B --> C{削除対象あり?}
    C -->|なし| D[スキップ]
    C -->|あり| E[年齢フィルタ適用]
    E --> F[タグ付きを除外]
    F --> G[直近5件を除外]
    G --> H[アーティファクト削除]
    H --> I[ワークフロー終了]
    D --> I
```

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

本ワークフローではデータベース操作は行いません。GitHub APIを使用してアーティファクトの管理を行います。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | API制限エラー | GitHub API制限に到達 | 時間をおいて再実行 |
| - | 認証エラー | GITHUB_TOKENの権限不足 | トークン権限を確認 |
| - | タイムアウト | 処理が10分を超過 | アーティファクト数を確認 |

### リトライ仕様

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

### 障害時対応

1. GitHub Actions UIでエラーログを確認
2. API制限の場合は時間をおいて手動で再実行
3. 継続的に失敗する場合はアクションのバージョンを確認

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | アーティファクト単位 |
| コミットタイミング | 各削除完了時 |
| ロールバック条件 | ロールバック不可（削除は不可逆） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 可変（アーティファクト数に依存） |
| 目標処理時間 | 10分以内（timeout-minutes: 10） |
| メモリ使用量上限 | 指定なし |

## 排他制御

排他制御は設定されていません。同時実行が発生する可能性は低いですが、発生した場合は両方のジョブが実行されます。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ワークフロー開始時 | GitHub Actions標準ログ |
| 処理ログ | 削除実行時 | 削除されたアーティファクト情報 |
| 終了ログ | ワークフロー終了時 | ジョブ完了ステータス |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ワークフロー失敗 | 1回 | GitHub通知 |
| 処理時間 | 10分超過 | 自動タイムアウト |

## 備考

- c-hive/gha-remove-artifacts@v1.4.0 アクションを使用
- 削除基準：1週間以上経過（age: "1 week"）
- 保護対象：タグ付きリリース（skip-tags: true）
- 保持件数：直近5件（skip-recent: 5）
- ubuntu-latestランナーで実行
