Blender Extensions リポジトリの GitHub Pages デプロイガイド

このドキュメントでは、GitHub Actions を使用して Blender アドオンの静的 Extensions リポジトリを自動でビルドし、GitHub Pages にデプロイする方法について説明します。

## 注意

このドキュメントはClineを使用して自作したBlender ExtensionsをGitHub Pagesにデプロイするために実行したタスクを元に、Clineによって自動生成されました。


## 概要

この方法では、以下のプロセスを自動化します。

1.  `v` で始まる Git タグ (例: `v1.2.3`) がリポジトリにプッシュされることをトリガーとします。
2.  GitHub Actions ワークフローが実行されます。
3.  ワークフロー内で Blender がセットアップされます。
4.  アドオンのソースファイル (`__init__.py`, `blender_manifest.toml` など) が ZIP ファイルにパッケージ化されます。
5.  Blender のコマンドラインツール (`extension server-generate`) を使用して、ZIP ファイルから `index.json` (リポジトリインデックス) と `index.html` (簡単なリスト表示ページ) が生成されます。
6.  生成されたファイル (`addon.zip`, `index.json`, `index.html`) が GitHub Pages 用のブランチ (通常は `gh-pages`) にデプロイされます。
7.  (オプション) 同時に GitHub Release が作成され、`addon.zip` と `index.json` がアセットとしてアップロードされます。

これにより、ユーザーは Blender のプリファレンスからあなたの GitHub Pages URL (`https://<username>.github.io/<repository>/index.json`) をリポジトリとして追加し、アドオンを簡単にインストール・更新できるようになります。

## 前提条件

*   **Blender アドオンプロジェクト:** `__init__.py` と `blender_manifest.toml` を含む基本的なアドオン構造が必要です。
*   **GitHub リポジトリ:** プロジェクトのソースコードがホストされている GitHub リポジトリ。
*   **GitHub Pages の有効化:** リポジトリの **Settings > Pages** で GitHub Pages が有効になっていること。
    *   **Source:** "Deploy from a branch" を選択。
    *   **Branch:** ワークフローがデプロイするブランチ (通常は `gh-pages`) とフォルダ (`/(root)`) を選択します。`gh-pages` ブランチが存在しない場合、ワークフローが初回実行時に自動作成します。

## GitHub Actions ワークフローの設定

リポジトリの `.github/workflows/` ディレクトリに、以下のような内容の YAML ファイル (例: `package.yml`) を作成します。

```yaml
name: Package Blender Add-on with index.json

# タグ（例: v1.0.0）のプッシュで実行
on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    # リリース作成と Pages デプロイに必要な権限
    permissions:
      contents: write
    steps:
      # 1. ソースコードのチェックアウト
      - name: Checkout code
        uses: actions/checkout@v4 # 最新版推奨

      # 2. Blender のダウンロードと展開 (バージョンは適宜変更)
      - name: Download Blender
        run: |
          BLENDER_VERSION="4.2.0" # 使用するBlenderバージョン
          BLENDER_ARCHIVE="blender-${BLENDER_VERSION}-linux-x64.tar.xz"
          BLENDER_DIR_NAME="blender-${BLENDER_VERSION}-linux-x64"
          wget "https://download.blender.org/release/Blender${BLENDER_VERSION%.*}/${BLENDER_ARCHIVE}"
          tar -xf "${BLENDER_ARCHIVE}"
          # Blender実行ファイルを後続ステップで使えるようにPATHに追加
          echo "$PWD/${BLENDER_DIR_NAME}" >> $GITHUB_PATH

      # 3. アドオン用ZIPパッケージの生成 (アドオンファイル名を指定)
      - name: Create ZIP package for add-on
        run: |
          zip addon.zip __init__.py blender_manifest.toml # アドオンに必要なファイルを追加

      # 4. index.json生成用のリポジトリフォルダを準備
      - name: Prepare repository folder for index generation
        run: |
          mkdir repo
          cp addon.zip repo/

      # 5. Blenderを利用して index.json と index.html を生成
      - name: Generate index.json with Blender
        run: |
          # GitHub Pages の URL を設定 (自分のリポジトリに合わせて変更)
          # BASE_URL="https://kurotori4423.github.io/AvatarExporter/" # Blender 4.2 では --base-url 未対応
          echo "Generating index.json and index.html"
          # --html オプションでHTMLも生成
          # 注意: Blender 4.2 では --base-url は認識されないため削除
          blender --background --factory-startup --command extension server-generate --repo-dir=$(pwd)/repo --html
          echo "Generated files in repo directory:"
          ls -l repo/

      # 6. (オプション) 成果物をアーティファクトとしてアップロード
      - name: Upload package and index as artifacts
        uses: actions/upload-artifact@v4
        with:
          name: addon-package-and-index
          path: |
            repo/addon.zip # repo/ 内のファイルを指定
            repo/index.json
            repo/index.html

      # 7. (オプション) GitHub Releaseの作成
      - name: Create GitHub Release
        id: create_release
        uses: softprops/action-gh-release@v2 # 最新版推奨
        with:
          # リリースノートを自動生成する場合など
          # generate_release_notes: true
          tag_name: ${{ github.ref }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      # 8. (オプション) リリースアセットとしてZIPファイルをアップロード
      - name: Upload Release Assets
        uses: softprops/action-gh-release@v2 # 最新版推奨
        with:
          files: |
            repo/addon.zip # repo/ 内のファイルを指定
            # repo/index.json # 通常、リリースにはZIPのみ含めることが多い
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      # 9. 生成されたファイルを GitHub Pages にデプロイ
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./repo # repo ディレクトリの内容をデプロイ
          # publish_branch: gh-pages # デプロイ先ブランチ (デフォルト: gh-pages)
          # commit_message: 'Deploy extension repository files for ${{ github.ref }}' # コミットメッセージ
```

**重要なポイント:**

*   **`permissions: contents: write`:** GitHub Release の作成や `gh-pages` ブランチへのプッシュ（デプロイ）には、この権限が必要です。
*   **Blender バージョン:** ワークフロー内で使用する Blender のバージョン (`BLENDER_VERSION`) を、アドオンがサポートするバージョンに合わせてください。ダウンロード URL もそれに合わせます。
*   **`$GITHUB_PATH`:** Blender の実行ファイルがあるディレクトリを `$GITHUB_PATH` に追加することで、後続のステップで `blender` コマンドが利用可能になります。
*   **ZIP パッケージ化:** `zip addon.zip ...` の部分で、アドオンの動作に必要なファイルのみを含めるようにします。
*   **`server-generate`:** `--repo-dir` で ZIP ファイルがあるディレクトリを指定し、`--html` で HTML ファイルも生成します。Blender 4.2 では `--base-url` が使えないため注意が必要です (相対パスで解決されることを期待)。
*   **`peaceiris/actions-gh-pages`:** `publish_dir: ./repo` で、`server-generate` がファイルを生成した `repo` ディレクトリの内容をデプロイ対象として指定します。

## 使い方

1.  アドオンのコードを変更したら、`main` (または開発用) ブランチにコミット＆プッシュします。
2.  リリース準備ができたら、バージョン番号で Git タグを作成し、プッシュします。
    ```bash
    # 例: バージョン 1.1.0 のタグを作成
    git tag v1.1.0
    # 作成したタグを GitHub にプッシュ
    git push origin v1.1.0
    ```
3.  タグのプッシュにより、GitHub Actions ワークフローが自動的に実行されます。
4.  ワークフローが完了すると、GitHub Pages が更新され、(設定していれば) GitHub Release も作成されます。

## Blender へのリポジトリ追加

ユーザーは以下の手順でアドオンリポジトリを追加できます。

1.  Blender を開き、`編集` > `プリファレンス` > `アドオン` に移動します。
2.  `拡張機能リポジトリ` > `リポジトリ` タブを開きます。
3.  `[+]` > `リモートリポジトリを追加` を選択します。
4.  URL として、デプロイされた `index.json` の URL (例: `https://<username>.github.io/<repository>/index.json`) を入力します。
5.  `OK` をクリックします。
6.  リポジトリリストから追加したリポジトリを選択し、アドオンを検索・インストールします。

これで、GitHub Actions を利用した Blender Extensions リポジトリの自動デプロイが設定できました。

## 参考ドキュメント

https://docs.blender.org/manual/en/latest/advanced/extensions/creating_repository/static_repository.html