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

Blender

Last updated at 2025-04-08Posted at 2025-04-08

このドキュメントでは、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 リポジトリの自動デプロイが設定できました。

参考ドキュメント

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up