publish-project-to-github

プロジェクトを GitHub に公開する

完成したローカルプロジェクトを、整理された公開成果物に仕上げます。リポジトリの作成、公開範囲の設定、デプロイは個別の段階として扱います。プッシュに成功したからといって、公開サイトが動作しているとは限りません。

成果物

該当する項目を作成します。

• 範囲を限定した Git リポジトリ
• 公開範囲を意図的に設定した GitHub リポジトリ
• プロジェクト固有の README.md
• プロジェクトがビジュアルな場合は、実際のプレビュー画像
• 価値がある場合は、移植可能なビルドまたはリミックス用プロンプト
• 対応するウェブプロジェクト向けに設定した GitHub Pages サイト
• プッシュ後およびデプロイ後の読み戻し確認

1. 範囲と権限を確認する

作業を始める前に、ローカルプロジェクト、リポジトリの状態、リモート、ローカルの指示を確認します。

以下を確認するか、安全に推定します。

• 正確なプロジェクトディレクトリと対象ファイル
• リポジトリ名と所有者
• 対象を公開にするか非公開にするか
• 既存のリポジトリを更新するか、新規作成するか
• ライブウェブサイト、ソースのホスティング、またはその両方をユーザーが希望しているか

ユーザーが公開共有、公開 URL、オープンソース、または同等の内容を明示的に求めている場合に限り、公開リポジトリの作成が許可されます。それ以外の場合は、作成前に公開範囲を確認してください。

明確な許可なしに、強制プッシュ、既存のリモートの上書き、リポジトリの公開範囲の変更、既存の Pages 設定の置き換えを行ってはいけません。

2. パッケージ化の前に監査する

プロジェクトのルートから、同梱の監査を実行します。

bash /path/to/publish-project-to-github/scripts/audit_public_project.sh .

その後、スクリプトの結果だけに頼らず、検出事項を確認します。

以下が含まれている場合は、公開を中止します。

• API キー、トークン、秘密鍵、パスワード、または .env ファイル
• 個人データや非公開のクライアント情報
• 実行時に必要な、ローカルファイルシステムの絶対パス
• ライセンスのない、または非公開のアセット
• 不足している実行時ファイル
• 既存のリポジトリ名の所有者が不明確

外部の実行時 URL と生成済みアセットをすべて確認します。必要なネットワーク依存関係があれば、README に記載します。

公開する前に、既存のライセンスを確認します。ユーザーがプロジェクトの再利用や変更を明示的に希望していて、ライセンスがない場合は、勝手に決めず、追加するライセンスを尋ねてください。目的が公開閲覧のみであれば、ライセンスがないことはデプロイの妨げにはなりませんが、再利用の権利が明示的に付与されていないことを伝えてください。

3. パッケージ化の方法を選ぶ

既存のクリーンなリポジトリ

リモート、履歴、追跡対象ファイルが公開予定のプロジェクトと一致している場合は、既存のチェックアウトを使用します。依頼されたファイルのみをステージします。

複数のプロジェクトが混在するワークスペース

ソースのワークスペースに、無関係な実験、削除済みファイル、非公開ファイル、または履歴が含まれている場合は、クリーンなプロジェクトディレクトリか、隣接する別のチェックアウトを作成します。対象となる実行時ファイルだけをコピーします。手間を省くために、複数の内容が混在したフォルダー全体を公開してはいけません。

既存の公開リポジトリ

変更する前に、デフォルトブランチ、Pages のソース、README、ライセンス、リモートの状態を確認します。意図的にプルまたは調整を行い、強制プッシュで差異を隠してはいけません。

静的な単一ファイルの実験では、次の最小構成を優先します。

project-name/
├── index.html
├── README.md
├── PROMPT.md        # optional
├── assets/          # optional previews or runtime assets
└── .gitignore

4. リポジトリの紹介ページを作成する

実際のプロジェクトに基づいて README を作成します。assets/README-template.md は構成のたたき台として使い、最終的な文章としては使いません。

以下を含めてください。

• プロジェクト名と、どのような体験を提供するのかを具体的に説明する一文
• ページ上部付近のライブデモへのリンクと、GitHub 以外で役立つ場合はリポジトリのソースへのリンク
• 実際に動作しているプロジェクトから撮影したスクリーンショットまたは短い GIF
• 主な操作や機能
• アーキテクチャと、一般的でない実装上の選択についての簡潔な説明
• 正確なローカルでの実行手順
• プロジェクトの構成
• 実行時の依存関係とネットワーク要件
• 参考にした作品がある場合は、独自性、クレジット表記、非提携に関する注記

エージェントが作成したプロジェクトでは、必要に応じて公式リンクと、関連するコーディングエージェントを使ってプロジェクトを再構築またはリミックスする方法を示す、移植可能なプロンプトを追加します。公開前に、現在の公式 URL を確認してください。

「最先端」「見事」「本番環境対応」といった一般的な主張は避けてください。具体的な工夫や動作を説明してください。

5. ローカルで検証する

モジュールベースのサイトをディスクから直接開くのではなく、プロジェクトで実際に使われているランタイムを使用してください。

静的サイトの場合：

python3 -m http.server 4173 --bind 127.0.0.1

以下を確認してください。

• 初期表示
• 主な操作の流れ
• 主な操作から戻る、閉じる、または復旧する流れ
• 通常のデスクトップ表示と、プロジェクトがレスポンシブな場合は 390 × 844 前後の狭い表示領域
• README に記載されたすべての実行コマンド
• ファイルの欠落と 404
• コンソールのエラーと警告
• /project-name/ のようなリポジトリのサブパスでの相対 URL

ユーザーが指定したブラウザー、またはリポジトリの指示で必須とされているブラウザーを使用してください。検証済みのランタイムから README 用のプレビューを撮影してください。

6. リポジトリをコミットして作成する

GitHub CLI と認証済みのセッションを必須とします。

gh --version
gh auth status

作成前に名前が使用可能か確認してください。

gh repo view OWNER/REPOSITORY

意図したパッケージだけを初期化してコミットしてください。

git init -b main
git add -- README.md index.html .gitignore
git diff --cached --check
git commit -m "Publish PROJECT_NAME"

混在したツリーでは、範囲を絞った git add を git add -A に置き換えず、任意のファイルは個別に明示して追加してください。

監査とローカル検証に合格してから作成し、プッシュしてください。

gh repo create OWNER/REPOSITORY \
  --public \
  --source=. \
  --remote=origin \
  --push \
  --description "CONCRETE_DESCRIPTION"

公開の承認がない場合は --private を使用してください。リポジトリがすでに存在する場合は、リモートを明示的に設定し、再作成せずにプッシュしてください。

7. 公開サイトを設定する

Pages を有効にする前に、プロジェクトを分類してください。

• 静的サイトのルート: main と / を公開します。
• 静的ドキュメントフォルダー: main と /docs を公開します。
• フレームワークのビルド: フレームワークがサポートする Pages の出力先と、現在の GitHub Actions 公式ガイドラインを使用します。
• サーバー、データベース、またはプライベートランタイム: GitHub Pages には対応していません。制約を説明し、ユーザーの承認がある場合にのみ別のホストを選択してください。

Pages の設定を変更する前に、references/github-pages.md を読んでください。リポジトリのホームページを公開 URL に設定し、実態に即した少数のディスカバリートピックを追加してください。

8. 外部の状態を検証する

すべての外部変更を読み戻して確認してください。

gh repo view OWNER/REPOSITORY \
  --json nameWithOwner,url,visibility,description,homepageUrl,defaultBranchRef

gh api repos/OWNER/REPOSITORY/pages
gh api repos/OWNER/REPOSITORY/pages/builds/latest

Pages のビルドが built と報告されるか、明確な理由で失敗するまで待ってください。その後、公開 URL を開いて以下を確認してください。

• 最終的な HTTPS URL への HTTP ナビゲーションが成功する
• 想定したプロジェクトの UI が表示される
• 代表的な操作によってアプリケーションの主要な状態が変化し、正常に戻るか閉じることができる
• リポジトリのサブパスでアセットが解決される
• ブラウザーにエラーや警告が表示されない
• README のリンクが解決される

公開ページの作成がユーザーの依頼内容である場合は、ユーザーのために公開ページを開いたままにしてください。

9. 正確な結果を引き継ぐ

以下を返してください。

• リポジトリ URL
• 作成した場合は公開サイト URL
• コミットとブランチ
• Pages のビルド状況
• 実際に実行したチェック
• 残っている依存関係、ライセンス、またはデプロイ上の制約

「プッシュ済み」「Pages 設定済み」「Pages ビルド済み」「公開サイト検証済み」を区別してください。これらをまとめて、ひとつの成功報告として扱わないでください。

失敗時のルール

• 関係のない未コミットの変更や履歴を保持してください。
• 秘密情報を公開せず、コミット済みの場合はプッシュする前に履歴から削除してください。
• ローカルのコンテキストから特定できない場合、GitHub の所有者や既存のリポジトリの公開先を推測しないでください。
• file:// のプレビューが GitHub Pages との互換性を証明すると主張しないでください。
• 外部への書き込みを検証する際、CLI が正常終了したことだけを根拠にしないでください。
• GitHub Pages に互換性がない場合、別のホストへ黙って切り替えないでください。

リソース

• パッケージ化または公開の前に scripts/audit_public_project.sh を実行してください。
• Pages の設定またはデバッグを行う前に references/github-pages.md を読んでください。
• assets/README-template.md をコピーし、プロジェクトの根拠に基づいてすべてのプレースホルダーを書き換えてください。