GitHubで作品を開発する

12.1 作品をGitHubに置く

このガイドでは1リポジトリに1作品を基本にします。Project Starterで作るリポジトリでは、作品をproject/に置き、READMEや検査・リリースの設定をその外に置きます。同じ作品の改良は作業ブランチで進め、配布する版はリリースで管理します。

neko-adventure/         リポジトリのルート
├── .git/
├── project/            エディターで開く作品フォルダ
├── README.md
└── .github/workflows/  この作品の検査とリリース

Project StarterでScratch作品を移す

scratch.mit.eduで作ってきた作品は、turbowarp-plus-editor-project-starterでGitHubのリポジトリに移せます。作品をsb3-toolchainの作品フォルダに展開し、検査とリリースを行うGitHub Actionsと、issue・プルリクエストの書式を加えたリポジトリを作ります。Node.js 24以降、Git、GitHub CLI（gh）が必要です。

次の例は、作業フォルダにneko.sb3がある場合です。

npx @kubohiroya/turbowarp-plus-editor-project-starter@0.2.0 init ./neko.sb3 --dir neko-adventure

initは手元にリポジトリを作り、Gitの作者情報があれば最初のコミットまで行います。作者情報が未設定の場合は、リポジトリで作者を設定し、git -C neko-adventure commit -m "Import neko"を実行します。共有しているScratch作品は、SB3のパスの代わりに作品ページのURLを渡せます。

生成したneko-adventure/projectは、エディターの「ファイル」→「プロジェクトフォルダを開く…」で開けます。GitHubに置く準備ができたら、gh auth loginで認証してからpublishを実行します。既定では非公開のリポジトリを作り、mainを送ります。

npx @kubohiroya/turbowarp-plus-editor-project-starter@0.2.0 publish neko-adventure

移行期間にScratchでも編集を続ける場合や、Scratch側の作品ページの扱いは、移行の手順で説明しています。

turbowarp-plus-editor-project-starter · sb3-toolchainの作品フォルダ

12.2 開発の流れと、どこで何をするか

1つの変更を、1つのissue・1つのブランチ・1つのプルリクエストで進めます。mainブランチはいつでも遊べる状態に保ち、作業はブランチで行います。

ブラウザーで作品フォルダを読み書きするには、File System Access対応のChromeやEdgeが必要です。操作ごとに必要な接続と権限は、対応表で確認できます。操作と接続の対応表

GitとGitHubの操作をコーディングエージェントに任せる

作品フォルダはテキストとファイルなので、ブランチ・コミット・push・プルリクエストの作成を、Claude CodeやCodexなどのコーディングエージェントに任せられます。この進め方では、エディターでの作業を作品の編集と保存までにし、人は変更を確かめてマージとリリースを決めます。push・pull・プルリクエストの作成のために、エディターをGitHubに接続する必要はありません。

1. エディターで編集して「ファイル」→「プロジェクトを保存」を選び、作品を止めます。
2. エージェントに、issueの番号と頼みたいこと（ブランチを作ってコミットし、pushしてプルリクエストを作るなど）を伝えます。
3. エージェントがブランチを切り替えたりpullしたりして作品フォルダが変わると、エディターの右下に「外部変更あり」が出て、変更を読み込みます（フォルダが外で変わったとき）。
4. プルリクエストができたら、12.9のとおりエディターの「マージ」でブロック単位に比べるか、GitHubの画面で確かめて、人がマージします。

エージェントには、保存前の作業ツリーを書き換えないこと、project.source.jsonを変えたらsb3-toolchain checkを通すこと、マージやリリースは頼まれたときだけ行うことを、リポジトリのAGENTS.mdで伝えます。Project Starter 0.2.0以降は、AGENTS.mdと、Claude Codeにそれを読ませるCLAUDE.mdを作ります。それより前に作ったリポジトリには、AGENTS.mdのテンプレートを写し、__PROJECT_DIR__などを自分の作品フォルダ名とsb3-toolchainの版に置き換えて置きます。

12.3 やることをissueに書く

1. GitHubでリポジトリを開き、「Issues」→「New issue」を押します。
2. 「アイデア・改善」か「不具合」を選び、書式に沿って書きます。「できあがりの目安」には、完成したと言える確かめ方をチェックボックスで書きます。
3. 「Create」を押すと、#12のような番号が付きます。自分で取りかかるときは「Assignees」に自分を入れます。

1つのissueには、1つのプルリクエストで終えられる大きさの変更を書きます。大きな目標は、いくつかのissueに分けます。

12.4 作業用のブランチを作る

ブランチを作る前に、手元のmainをGitHubの最新に合わせます（12.7のpull）。そのあと、エディターでブランチを作ります。

1. 「ファイル」→「リポジトリを選択…」でリポジトリのフォルダを選びます。作品をまだ開いていなければ、ローカルGitの上部の「作品を開く」でproject/を開きます。
2. 作品の実行を止め、編集をすべて保存し、必要な変更をコミットしておきます。未保存の編集や未コミットの変更があると、ブランチを切り替えられません。
3. ローカルGitの「PRを作成」を開き、「ローカルブランチ」の「新しいブランチの名前」に、issueの番号と内容が分かる名前（例：12-neko-walk）を入れます。「作ったら切り替える」にチェックし、「ブランチを作る」を押します。メニューバーのブランチのボタンの「新しいブランチ…」からも作れます。

過去のコミットから枝分かれさせるときは、「Git 履歴」でコミットの「⋯」→「ここからブランチを作る…」を選びます。

GitHubのissueの「Development」→「Create a branch」で作った場合は、手元でfetchしてから、「GitHub（origin）のブランチ」の一覧で「作って切り替える」を押します。GitHub Desktopの「New branch」やgit switch -c 12-neko-walkで作った場合は、ローカルGitの「ローカル状態を更新」を押します。必要に応じて「ファイル」→「プロジェクトフォルダを開く…」で同じフォルダを開き直します。

12.5 作品を編集して保存する

ブロック、変数・リスト、スプライト、コスチューム、音などを編集し、「ファイル」→「プロジェクトを保存」を選びます。作品フォルダのproject.source.jsonと、必要に応じてassets/とsb3-source.jsonが更新されます。保存の前に、フォルダが外部で変更されていないかを確かめます。

同じリポジトリの作品を更新する間は「プロジェクトを保存」を使います。「名前を変えて保存…」でSB3を作ると、作品フォルダとのつながりが外れます。保存済みのファイルのGit状態は「作品フォルダ」パネルで確認できます。

作品フォルダを開いて保存する · フォルダが外で変わったとき

12.6 変更を確認してローカルにコミットする

保存すると編集内容が作品フォルダに書き込まれ、コミットすると選んだファイルの変更が手元のGit履歴に加わります。GitHubに送るにはpushを使います。

1. 「ファイルの保存」を開きます。未保存のファイル名を選ぶと、右側で最新コミット（HEAD）との差分を確認できます。「未保存のファイルを保存」を押すと編集内容が作品フォルダに書き込まれます。
2. 横の「保存のコミット」に切り替えます。ファイル名を押すと、右側で差分を確認できます。作品のコードはスプライトやステージの「コード」を選ぶと、変更前と変更後のブロックで比較できます。
3. 「その他のファイル」や「ファイル単位の一覧」で、コミットするファイルにチェックを付けます。スプライトやステージの差分を開き、右下の「コミットに含める」で選ぶこともできます。左下のコミット欄で選択件数を確かめ、「コミットメッセージ」に変更内容（例：ネコが進む歩数を変更 (#12)）を入力して「コミット」を押します。
4. 画面左上の「Git 履歴」で作ったコミットを選ぶと、「PRを作成」が開き、含まれた変更を確認できます。

コミットの作者を設定する

コミットの作者には、作品リポジトリのuser.nameとuser.emailが優先して使われます。DesktopがGitのグローバル作者設定をエディターに渡すビルドでは、リポジトリに作者情報がないときにその設定を使います。

作者が未設定と表示されたら、作品のリポジトリをターミナルで開き、そのリポジトリに名前とメールアドレスを設定します。公開リポジトリには、GitHubのアカウント設定で確認したnoreplyアドレスも使えます。設定後に「ローカル状態を更新」を押して、もう一度コミットします。

git config --local user.name "あなたの名前"
git config --local user.email "you@example.com"

ローカルGitで変更と履歴を確かめる · 作品の変更をブロックで比べる

12.7 GitHubに送る（push）

GitHub接続付きのエディターでは、エディターからpush・pullできます。既定の接続方式は、メニューバー左端のPlusロゴ→「GitHub 接続設定…」で選びます。

1. ローカルGitの先頭行にある「GitHub に接続…」を開きます。接続先を確認し、「GitHub に送ることを許可する（push）」にチェックして「GitHub に接続」を押します。表示に従ってGitHubで認証します。
2. 接続後に「マージ」を開き、「GitHub と同期」の「現在のブランチを送る（push）」を押します。強制pushは行いません。
3. GitHubの変更を取り込むときは「リモートの情報を更新（fetch）」と「手元のブランチとファイルを更新（pull）」を使います。pullはfast-forwardできる場合だけ行い、取り込んだあとは「作品を再読込」で開き直します。

接続がない場合

公開版（GitHub Pages）のように、ローカルGitに「GitHub に接続…」が出ず、「GitHub 接続設定…」に「GitHub 接続先が設定されていません。」と表示される場合は、次のいずれかでpush・pullを行います。

• GitHub Desktop。「File」→「Add local repository」でリポジトリのフォルダを追加し、「Push origin」（新しいブランチでは「Publish branch」）で送ります。取り込むときは「Fetch origin」→「Pull origin」を使います。
• コマンド。新しいブランチを初めて送るときはgit push -u origin 12-neko-walk、取り込むときはgit pull --ff-onlyを実行します。

エディターの外で操作したあとは、リポジトリ名の横の「ローカル状態を更新」を押します。作品を開き直すときは「ファイル」→「プロジェクトフォルダを開く…」で同じフォルダを選びます。エディターは開き直す前に、保存していない編集がないかを確かめます。

GitHubと同期する

12.8 プルリクエストを作る

「GitHub に送ることを許可する（push）」を付けてGitHubに接続している場合は、ローカルGitの「PRを作成」で「反映先のブランチ」を選び、「PRに含めるコミット」にチェックを付けます。「PRのタイトル」と「PRの説明」を記入し、「PRの内容を確認」で内容を確かめてから「PRを作成」を押します。エディターは選んだコミットを反映先に適用し、PR用のブランチをGitHubに送ります。選んだコミットが別のコミットに依存していて適用できない場合は、必要なコミットも選びます。接続がない場合は「このGitHub接続ではPRを作成できません。」と表示されるので、GitHubの画面で作ります。

GitHubの画面でPRを作る

作業ブランチをGitHubに送ってから、GitHubの画面でPRを作ります。GitHubに送る手順

1. GitHubでリポジトリを開くと、送ったブランチの「Compare & pull request」が表示されます。押して、「base: main ← compare: 12-neko-walk」になっていることを確かめます。
2. 書式に沿って、何を変えたか、変えたスプライト・ステージ、確かめ方を書きます。既定ブランチにマージしたときにissueも閉じるには、本文にCloses #12と書きます。関連付けだけなら#12と書きます。
3. 「Create pull request」を押します。コマンドではgh pr create --fillで作れます。

検査結果とSB3を確認する

Project Starterのワークフローを含むリポジトリでプルリクエストを作ると、Actionsの「Check project」が作品フォルダを検査し、SB3を作ります。プルリクエストの「Checks」→「Check project」→「Summary」の「Artifacts」からSB3をダウンロードし、TurboWarpかエディターで開いて、書いた確かめ方のとおりに動くかを試せます。

12.9 確かめてマージする

確かめる人は、変更をスクリプト単位で読みます。

ローカルGitの「マージ」でPRを選び、「変更ファイル」を開くと、ステージ・スプライトごとに、変更前と変更後のスクリプトをブロックで比べられます。読み終えたスクリプトには、比較枠の右下で「確認済み」を付けられます。

• 公開リポジトリ。接続なしで「PR一覧」から選べます。
• 非公開リポジトリ。ローカルGitの「GitHub に接続…」で認証すると、アクセスできるリポジトリのPRを一覧から選べます。反映先を取得できず、候補が複数ある場合は、比較先のブランチを選べます。

接続中に開いたPRは、「PRの作品を開いて動作確認」で比較した版のローカルブランチ（例：PR #219ならpr/219）に切り替えて実行できます。右ペインのPR番号とタイトルはGitHubへのリンクです。差分をエディターのタブや別ウィンドウで開く方法は、プルリクエストをスクリプト単位でレビューするで説明しています。

接続がない場合

公開PRはエディターの「変更ファイル」で確認できます。非公開PRは、GitHubにログインしてPRの「Files changed」で差分を確認します。動作を確かめるには、「Checks」から「Check project」のSB3を取得し、エディターの「ファイル」から開きます。

レビューを送るには、エディターのレビュー送信の条件を確認します。接続でレビュー送信を許可できるときは、比較画面の「レビューを送信」から操作できます。GitHubで送るときは、PRの「Files changed」か「Conversation」にコメントを書きます。修正を同じ作業ブランチにpushするとPRが更新されます。PRが更新されると、エディターでは内容が変わったスクリプトの「確認済み」が外れます。

エディターでマージする

「マージ」の一覧でCIの結果を確かめ、対象のPRを選びます。「GitHub に送ることを許可する（push）」を付けたGitHub接続で、必要なチェックとレビューを通過すると、「概要」のマージ状況カードの右上に緑色の「スカッシュしてマージ」が表示されます。押すと、反映先と対象のコミットを確かめるダイアログが開きます。エディターでのマージはスカッシュマージだけです。PRの差分・CI・マージ可否を読み直すには、PRタイトルの横の「GitHubからPR情報を読み直す」を押します。

GitHubの画面でマージする

「Check project」など必要な検査とレビューが済んだら、対象ブランチと最新の差分を確かめ、GitHubで選べる方式でマージします。「Squash and merge」は変更を1つのコミットにまとめます。マージ後、不要になった作業ブランチはPR画面の「Delete branch」で削除できます。

手元では、メニューバーのブランチ名からmainに切り替え、pullで最新を取り込み、「作品を再読込」で開き直します。

プルリクエストをスクリプト単位でレビューする

12.10 リリースして配る

「ファイル」→「リリース…」から、公開するものに応じて次の操作に進みます。

• npmパッケージ。「確認コマンドをコピー」を押し、パッケージのディレクトリでnpm publish --dry-runを実行します。公開するファイルを確かめてから「公開コマンドをコピー」を押し、認証済みの端末でnpm publishを実行します。
• GitHubのリビジョンタグ。「対象コミット」を確かめ、「タグ名」（例：v1.0.0）を入れます。pushを許可してGitHubに接続していれば「タグを GitHub に送る」を押します。pushを許可していない場合は、タグを送るgit push origin …のコマンドが表示されるので、リポジトリの端末で実行します。
• GitHub Pages。「Packager で HTML を書き出す」で、単一のHTMLファイルを生成します。「Pages の公開設定を開く」で、公開元が「Deploy from a branch」になっていることと、そのブランチ・フォルダを確かめます。pushを許可した接続では、エディターに戻って「公開先のブランチを取得」を押し、ブランチ、フォルダ（/または/docs）、HTMLを選びます。「HTML を GitHub に送る」を押すと、選んだ場所のindex.htmlだけを更新するコミットが送られます。接続がない場合は「GitHub でファイルを追加」からGitHubの画面でアップロードします。デプロイの状況はGitHubのPages設定で確認できます。GitHubの公開元設定ガイド

作品をGitHub Releasesで配布する

1. エディターの「ファイル」→「リリース…」で「GitHub Releases を開く」を選ぶと、GitHubのリリース一覧が開きます。「Draft a new release」を押します。
2. 「Choose a tag」で、公開するコミットに付けたタグ（例：v1.0.0）を選びます。ここでタグを作る場合は、名前を入れて「Create new tag on publish」を選び、対象のブランチを指定します。
3. 「Generate release notes」を押すと、マージしたプルリクエストの一覧が入ります。遊ぶ人向けの説明を書き足します。
4. 「Publish release」を押します。コマンドではgh release create v1.0.0 --generate-notesで作れます。

リリースを公開すると、Actionsの「Release」がそのタグの作品フォルダからSB3を作り、<名前>-v1.0.0.sb3（名前はscratch-project.jsonのsb3Name）とSHA256SUMS.txtをリリースに添付します。添付されたSB3は、TurboWarpやScratchで開けます。Scratchの作品ページも新しくするには、ScratchのエディターでSB3を読み込み、「今すぐ保存」で上書きします。

版の名前は、不具合の修正だけなら最後の数字（v1.0.1）、遊べることが増えたら真ん中の数字（v1.1.0）を上げると、遊ぶ人に変更の大きさが伝わります。

保存して配布する

12.11 ぶつかったとき・困ったとき

作品のブロックやスプライトの設定は、1つのproject.source.jsonに入っています。2つのブランチが同じスプライトの近い場所を変えると、プルリクエストに「This branch has conflicts」と表示されることがあります。Gitのマージが途中の状態では、エディターはコミットやブランチの切り替えを行いません。

• ぶつからないようにする。プルリクエストを小さく保ち、早めにマージします。同じ時期に作業するときは、担当するスプライトを分けます。
• ぶつかったら作り直す。最新のmainから新しいブランチを作り、エディターで同じ変更をやり直します。スクリプトはコピー・貼り付けか.blocks3の書き出し・読み込みで新しいブランチの作品に持ち込めます。新しいプルリクエストを作り、古いほうは閉じます。
• JSONを直接直す。Gitに慣れている場合は、コマンドでmainを取り込み、project.source.jsonの衝突を直してからsb3-toolchain check projectで検査します。