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

注意

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

概要

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

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

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 ディレクトリの内容をデプロイ対象として指定します。

使い方

アドオンのコードを変更したら、main (または開発用) ブランチにコミット＆プッシュします。

リリース準備ができたら、バージョン番号で Git タグを作成し、プッシュします。

# 例: バージョン 1.1.0 のタグを作成
git tag v1.1.0
# 作成したタグを GitHub にプッシュ
git push origin v1.1.0

タグのプッシュにより、GitHub Actions ワークフローが自動的に実行されます。
ワークフローが完了すると、GitHub Pages が更新され、(設定していれば) GitHub Release も作成されます。

Blender へのリポジトリ追加

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

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

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

参考ドキュメント