mcpField
G
git-multibranch

git-multibranch

github.com/letta-aiクラウド・DevOps15237 回インストール4 週間前に更新
リポジトリ

git-multibranch について

Git Multi-Branch Deployment は、Git の post-receive hook で複数ブランチを異なる Web サーバーの配置先へデプロイするためのガイド型スキルです。SSH、ベアリポジトリ、Web サーバー設定、デプロイ検証を扱います。

主な機能

  1. 01専用 Git ユーザーと SSH の設定
  2. 02ベアリポジトリとブランチの作成
  3. 03ブランチごとの Web 配置先設定
  4. 04post-receive hook によるデプロイ
  5. 05push、デプロイ、配信ページの検証

活用シーン

  1. 01main と dev を別々のディレクトリに配置
  2. 02SSH 経由の Web デプロイを構築
  3. 03hook の実行や権限の問題を調査

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/letta-ai/skills --skill git-multibranch

インストール後、Claude Code で/git-multibranchを入力して読み込まれたか確認します。

詳細

Git の複数ブランチデプロイ

概要

このスキルでは、複数のブランチ（例：main、dev）を、post-receive フックを介して異なる Web サーバーの場所に自動デプロイする、Git ベースのデプロイシステムを設定する方法を説明します。SSH の設定、Git リポジトリのセットアップ、Web サーバーの設定、自動デプロイのワークフローについて扱います。

前提条件の確認

開始する前に、必要なツールと設定がすべて揃っていることを確認してください。

  • 必要なパッケージを確認します：git、openssh-server、sshpass（テスト用）、Web サーバー（nginx/apache）
  • SSH（22）と HTTP/HTTPS（80/443）のポートが使用可能か確認します
  • ユーザー作成の権限があることを確認します
  • Git のデフォルトブランチ名を事前に設定します：git config --global init.defaultBranch main

アプローチ：ステップごとの実装

1. ユーザーと SSH のセットアップ

作業：

  • ホームディレクトリを持つ専用の Git ユーザーを作成します
  • SSH 認証用のパスワードを設定します
  • パスワード認証を許可するよう SSH を設定します

SSH 設定に関する考慮事項：

  • /etc/ssh/sshd_config の設定を変更します：PasswordAuthentication yes、ChallengeResponseAuthentication yes
  • 影響する可能性のある追加設定を検討します：UsePAM、KbdInteractiveAuthentication
  • 設定を変更した後、SSH サービスを再起動します
  • テスト時の SSH ホストキー検証に備えます（キーを事前に受け入れるか、StrictHostKeyChecking を処理します）
2. Git リポジトリの作成

作業：

  • Git ユーザーのホームディレクトリにベア Git リポジトリを作成します
  • 適切な権限で初期化します
  • コンテンツを含む初期ブランチを作成します

ブランチのセットアップパターン：

1. Clone the bare repo to a temp location
2. Create initial commit on main branch
3. Create and populate additional branches (e.g., dev)
4. Push all branches to the bare repo
3. Web サーバーの設定

作業：

  • 各ブランチ用のデプロイディレクトリを作成します（例：/var/www/main、/var/www/dev）
  • Git ユーザーに適切な所有権と権限を設定します
  • 各デプロイ先のバーチャルホストまたはサーバーブロックを設定します
  • HTTPS が必要な場合は SSL 証明書を用意します

SSL 証明書の生成（自己署名）：

  • 適切な subject と SAN 拡張を指定して openssl req を使用します
  • 最新の TLS プロトコルで証明書を使用するよう Web サーバーを設定します
4. Post-Receive フックの作成

作業：

  • ベアリポジトリの hooks/ ディレクトリに実行可能な post-receive フックを作成します
  • ref の更新を解析し、プッシュされたブランチを判別します
  • 該当するブランチを対応するデプロイディレクトリにチェックアウトします

フックの構成：

1. Read stdin for ref updates (oldrev newrev refname)
2. Parse branch name from refname
3. For each target branch, checkout to deployment directory using GIT_WORK_TREE
5. サービスの設定

作業：

  • 必要なサービス（SSH、Web サーバー）を起動し、有効化します
  • 永続化が必要な場合は、サービスが起動時に開始するよう設定します
  • サービスが稼働し、アクセス可能であることを確認します

検証方法

SSH アクセスの検証
  • パスワードを使用して SSH 接続をテストします：sshpass -p <password> ssh -o StrictHostKeyChecking=no <user>@<host>
  • SSH 経由の Git 操作が正しく動作することを確認します
Git 操作の検証
  • SSH 経由でリポジトリをクローンします
  • テスト用のコミットを作成し、各ブランチにプッシュします
  • エラーなくプッシュが完了することを確認します
デプロイの検証
  • プッシュのたびに、コンテンツが正しいデプロイディレクトリに配置されることを確認します
  • Web サーバーが各ブランチ／エンドポイントに対して正しいコンテンツを配信することをテストします
  • 必要な時間内にデプロイが完了することを確認します
エンドツーエンドテストのパターン
1. Clone repository to fresh test directory
2. Make changes to branch content
3. Push changes
4. Immediately verify web endpoint reflects changes
5. Time the deployment if latency requirements exist

よくある落とし穴と間違い

ブランチ名の混同
  • 問題： Git は main ではなく master をデフォルトにする場合があります
  • 解決策： リポジトリを作成する前に git config --global init.defaultBranch main を設定します
  • 復旧方法： すでに作成済みの場合は、git branch -m master main でブランチ名を変更します
SSH 設定の不足
  • 問題： 設定を変更しても SSH 接続に失敗します
  • 原因： UsePAM、KbdInteractiveAuthentication などの設定が不足しているか、サービスが再起動されていません
  • 解決策： SSH 関連の設定をすべて確認し、変更後に sshd を再起動します
ホスト鍵の検証エラー
  • 問題： SSH コマンドでホスト鍵の検証エラーが発生します
  • 解決策：
    • ホスト鍵を事前に受け入れます：ssh-keyscan -H <host> >> ~/.ssh/known_hosts
    • テストでは StrictHostKeyChecking=no を使用します（セキュリティへの影響を明記してください）
テスト中のプッシュ競合
  • 問題： 再テスト時に fast-forward 以外のエラーが発生します
  • 原因： 以前のテストデータが新しいプッシュと競合しています
  • 解決策：
    • テストの実行ごとに新しいテストディレクトリを使用します
    • 適切な場合は強制プッシュします：git push --force
    • テスト間でリポジトリの状態をリセットします
post-receive フックの問題
  • 問題： フックが実行されない、またはデプロイが失敗しても通知されません
  • 原因： フックに実行権限がない、シバンが間違っている、GIT_WORK_TREE が設定されていない
  • 確認方法： フックにログ記録を追加し、ls -la hooks/ で権限を確認します
サービスの状態に関する問題
  • 問題： サービスが実行されない、または起動時に開始しません
  • 解決策： 起動時にサービスを維持するには systemctl enable を使用し、テスト前にステータスを確認します
前提条件の不足
  • 問題： 必要なツールがインストールされていないため、コマンドが失敗します
  • 解決策： 最初にすべての前提条件を確認し、セットアップを始める前に不足しているパッケージをインストールします

考慮すべきエッジケース

未処理のブランチへのプッシュ
  • 設定済みのブランチ以外がプッシュされた場合の動作を決めます
  • 無視する、警告する、エラーにする、のどれが適切かを記載します
デプロイの失敗
  • post-receive フックにエラー処理を追加することを検討します
  • デプロイ失敗時の通知方法を決めます
同時プッシュ
  • 同時プッシュによる競合状態の可能性に注意します
  • 本番環境ではロック機構の追加を検討します
権限の問題
  • Git ユーザーがすべてのデプロイディレクトリへの書き込み権限を持っていることを確認します
  • ディレクトリの作成後に所有者を確認します

効率化の推奨事項

繰り返しの削減
  • 繰り返し実行する SSH コマンドには環境変数を設定します：export GIT_SSH_COMMAND='sshpass -p password ssh -o StrictHostKeyChecking=no'
  • 関連する操作をまとめて、1 回のシェル呼び出しで実行します
テストをクリーンに保つ
  • アーティファクトが蓄積しない、分離されたテストディレクトリを使用します
  • 実行ごとにテストリポジトリをクリーンアップします
コマンドの利用可否
  • 使用前にコマンドの存在を確認します（例：処理時間の計測前に command -v time を実行します）
  • 代替手段を用意します（例：time の代わりに date +%s%3N を使用します）

コメント

Markdown 対応