# バッチ設計書 16-flatpak.yml

## 概要

本ドキュメントは、GitHub Actions ワークフロー `flatpak.yml` の設計仕様を記載したバッチ設計書です。Flatpakパッケージのビルドを実行するワークフローの詳細を説明します。

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

このバッチは、GhosttyのFlatpakパッケージをビルドします。x86_64およびaarch64アーキテクチャ向けのFlatpakバンドルを並列でビルドし、Linuxユーザーに配布可能な形式を生成します。Flathub互換のビルドプロセスを使用し、GNOME 47ランタイムを基盤としています。

**業務上の目的・背景**：Flatpakは、Linux向けのクロスディストリビューション対応パッケージ形式です。サンドボックス化されたアプリケーション配布を可能にし、多くのLinuxディストリビューションで利用できます。Flathubでの配布を視野に入れた標準的なビルドプロセスを採用することで、幅広いLinuxユーザーへのリーチを実現します。

**バッチの実行タイミング**：手動実行（workflow_dispatch）のみ。通常はリリースワークフロー（release-tag.yml等）から呼び出されます。ソースtarballのrun-idとartifact-idを入力パラメータとして受け取ります。

**主要な処理内容**：
1. ソースtarballアーティファクトのダウンロード
2. tarballの展開
3. flatpak-builderによるFlatpakパッケージビルド
4. アーキテクチャ別の並列ビルド（x86_64, aarch64）

**前後の処理との関連**：build-distワークフローで生成されたソースtarballを前提条件とします。release-tag.ymlやrelease-tip.ymlから呼び出されることを想定しています。ビルド成果物は後続のリリース処理やFlathub提出で使用されます。

**影響範囲**：GitHub Actionsのビルドアーティファクトとしてcom.mitchellh.ghosttyバンドルが生成されます。本ワークフロー自体はストレージやデータベースに直接影響しません。

## バッチ種別

CI/CD / パッケージビルド

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（リリース時） |
| 実行時刻 | 指定なし |
| 実行曜日 | 指定なし |
| 実行日 | 指定なし |
| トリガー | 手動（workflow_dispatch） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| リポジトリ | ghostty-org/ghostty リポジトリでのみ実行 |
| ソースtarball | build-distで生成されたghostty-source.tar.gzが存在すること |
| 有効なrun-id | ソースtarballを含むワークフロー実行のID |
| 有効なartifact-id | ダウンロード対象のアーティファクトID |

### 実行可否判定

`github.repository == 'ghostty-org/ghostty'` の条件で、公式リポジトリでのみ実行されます。入力パラメータ（source-run-id, source-artifact-id）が正しく指定されている必要があります。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| source-run-id | string | Yes | なし | アーティファクトを生成したワークフロー実行のID |
| source-artifact-id | string | Yes | なし | ダウンロードするソースtarballのアーティファクトID |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| ghostty-source.tar.gz | tarball | ソースコードアーカイブ |
| GitHub Actions Artifacts | アーティファクト | 前段ワークフローの出力 |
| com.mitchellh.ghostty.yml | YAML | Flatpakマニフェスト |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| GitHub Actions Artifacts | Flatpakバンドル | ビルドされたFlatpakパッケージ |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| バンドル名 | com.mitchellh.ghostty |
| 出力先 | GitHub Actionsアーティファクト |
| 対象アーキテクチャ | x86_64, aarch64 |

## 処理フロー

### 処理シーケンス

```
1. アーティファクトダウンロード
   └─ 指定されたrun-id/artifact-idからソースtarballを取得
2. tarball展開
   └─ distディレクトリに展開（strip-components: 1）
3. Flatpakビルド
   └─ flatpak/flatpak-github-actions/flatpak-builder でビルド
   └─ マニフェスト: dist/flatpak/com.mitchellh.ghostty.yml
   └─ キャッシュキー: flatpak-builder-${{ github.sha }}
```

### フローチャート

```mermaid
flowchart TD
    A[ワークフロー開始] --> B{リポジトリチェック}
    B -->|ghostty-org以外| C[スキップ]
    B -->|ghostty-org/ghostty| D[アーティファクトダウンロード]
    D --> E{ダウンロード成功?}
    E -->|失敗| F[エラー終了]
    E -->|成功| G[tarball展開]
    G --> H[Flatpakビルド実行]
    H --> I{ビルド成功?}
    I -->|失敗| J[エラー終了]
    I -->|成功| K[バンドル保存]
    K --> L[ワークフロー終了]
    C --> L
```

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

本ワークフローではデータベース操作は行いません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ダウンロード失敗 | アーティファクトが存在しない | run-id/artifact-idを確認 |
| - | ビルドエラー | Flatpakビルドプロセスの失敗 | ログを確認し問題を修正 |
| - | マニフェストエラー | com.mitchellh.ghostty.ymlの不整合 | マニフェストを確認 |

### リトライ仕様

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

### 障害時対応

1. GitHub Actions UIでエラーログを確認
2. アーティファクトの存在とIDを確認
3. Flatpakビルドエラーの場合はcom.mitchellh.ghostty.ymlを確認
4. 必要に応じてワークフローを手動で再実行

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 2（x86_64, aarch64） |
| 目標処理時間 | 指定なし |
| メモリ使用量上限 | 指定なし |

## 排他制御

排他制御は設定されていません。マトリックスビルドにより、x86_64とaarch64のビルドが並列で実行されます。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ワークフロー開始時 | GitHub Actions標準ログ |
| 展開ログ | tarball展開時 | --verboseオプションによる詳細出力 |
| ビルドログ | Flatpakビルド時 | flatpak-builderの出力（verbose: true） |
| 終了ログ | ワークフロー終了時 | ジョブ完了ステータス |

## 監視・アラート

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

## 備考

- コンテナイメージ: ghcr.io/flathub-infra/flatpak-github-actions:gnome-47
- コンテナオプション: --privileged（Flatpakビルドに必要）
- マトリックスビルド:
  - x86_64: namespace-profile-ghostty-md
  - aarch64: namespace-profile-ghostty-md-arm64
- fail-fast: false により、一方のアーキテクチャが失敗しても他方は継続
- flatpak/flatpak-github-actions/flatpak-builder@v6.6 を使用
- actions/download-artifact@v8.0.0 を使用
- キャッシュキー: flatpak-builder-${{ github.sha }}
- マニフェストパス: dist/flatpak/com.mitchellh.ghostty.yml
