Mastra platform の GitHub 連携

GitHub 連携を使うと、Mastra platform プロジェクトを GitHub リポジトリに接続できます。リポジトリに変更をプッシュすると、Studio と Server が自動的にデプロイされます。

注記

この連携は、GitHub.com でホストされているリポジトリでのみ利用できます。セルフホストの GitHub Enterprise インスタンスは現在サポートされていません。

リポジトリを接続すると、platform は次の処理を行います。

• 設定したブランチにプッシュされるたびに、Studio と Server をビルドしてデプロイします。
• テンプレートから作成したプロジェクトに、マネージドデータベースと Gateway API キーをプロビジョニングします。
• 各デプロイにコミット、ブランチ、プルリクエストのコンテキストを表示します。
• ビルドステータスを GitHub にチェック実行として返し、プロジェクトダッシュボードにはリアルタイムのステータスバッジとインラインログを表示します。

GitHub 連携を使用する場面

次のいずれかを行う場合は、GitHub 連携を選択してください。

• main またはその他の任意のブランチからプッシュでデプロイする。Studio と Server に別々のブランチを指定することもできます。
• Mastra テンプレートからプロジェクトをスキャフォールドするマネージドオンボーディングフローを使用する。このフローには、新しいリポジトリ、マネージドデータベース、Gateway API キーが含まれます。
• トリアージのために、platform ダッシュボードでプルリクエストとコミットのコンテキストを確認する。

CLI フロー（mastra studio deploy と mastra server deploy）は、単発のデプロイや GitHub 以外の CI プロバイダーでも引き続き利用できます。CLI のみを使用する手順については、Studio と Server を参照してください。

Mastra GitHub App をインストールする

この連携は Mastra GitHub App によって提供されます。

App はリポジトリの内容を読み取り、設定されたブランチの push イベントを監視します。また、デプロイステータスをチェック実行として書き戻します。

1. Mastra platform ダッシュボードで、組織の設定を開きます。このページには GitHub App セクションがあります。

2. Install GitHub App を選択し、インストール先の GitHub アカウントまたは組織を選びます。

   GitHub 組織の所有者でない場合、GitHub は管理者の承認が必要な保留中の installation request を作成します。ダッシュボードでは、完了したインストールとあわせて保留中のリクエストも追跡できます。

3. App がアクセスできるリポジトリを選択します。特定のリポジトリに限定することも、アカウント上のすべてのリポジトリへのアクセスを許可することもできます。

   GitHub の App 設定から、いつでもリポジトリへのアクセスを取り消したり変更したりできます。

注記

後から GitHub によって App の必須権限が更新された場合、ダッシュボードには承認リンク付きの outdated permissions 警告が表示されます。管理者が再承認するまで、リポジトリ操作は 403 を返します。

保留中のインストールリクエスト

管理者以外のユーザーが組織に App をリクエストすると、GitHub.com で組織の管理者が承認するまで保留状態になります。ダッシュボードでは、次の操作ができます。

• アクティブなインストールの横に保留中のリクエストを表示する。
• 同じユーザーが複数の GitHub アカウントへのアクセスを一度にリクエストする。
• ページを開いたときに保留状態を GitHub と照合し、管理者が却下したリクエストや申請者が取り下げたリクエストを削除する。

保留中のリクエストをキャンセルするには、ダッシュボードで対象の横にある Cancel を選択します。

テンプレートからプロジェクトを作成する

テンプレートを使うと、最もすばやく開始できます。platform は Mastra テンプレートから新しいリポジトリを作成し、新しいプロジェクトに接続して、テンプレートで宣言されているマネージドデータベースをプロビジョニングした後、最初のデプロイを実行します。

1. ダッシュボードで Create project を選択し、Start from a template を選びます。

2. テンプレートを選び、新しいリポジトリを所有する GitHub アカウントを選択します。リポジトリに名前を付け、非公開にするかどうかを選びます。

3. テンプレートのマネージドデータベース要件を設定します。テンプレートでは必須データベース（Turso や Neon など）を宣言でき、要件ごとにプロバイダーとリージョンを選択します。

4. テンプレート固有の環境変数（AI プロバイダーの API キーなど）を追加します。Gateway と通信するテンプレートコードが最初のデプロイから動作するように、platform は MASTRA_GATEWAY_API_KEY と MASTRA_PLATFORM_ACCESS_TOKEN を自動的に設定します。

5. Create project を選択します。platform はリポジトリを作成し、.mastra-project.json 設定ファイルを書き込み、マネージドデータベースをプロビジョニングして、Studio と Server の初回デプロイを開始します。

初回デプロイは、マネージドデータベースのプロビジョニングが完了してから開始されます。そのため、テンプレートの最初のビルド時点でデータベース接続用の環境変数を利用できます。

既存のリポジトリを接続する

GitHub リポジトリに Mastra プロジェクトがすでにある場合は、このフローを使用します。

1. ダッシュボードで Create project を選択して Connect an existing repository を選ぶか、既存のプロジェクトを開き、プロジェクト設定から Link repository を選択します。

2. インストールを選び、リポジトリを選択します。リポジトリ検索では、そのインストールで App がアクセスできるすべてのリポジトリを検索できます。

3. Studio と Server のデプロイブランチを選択します。どちらもデフォルトではリポジトリのデフォルトブランチが使用され、同じブランチを共有することも、別々のブランチを使用することもできます。

   プロジェクトで Studio または Server を無効にできます。両方が設定されている場合、手動の Deploy from GitHub ドロワーではデフォルトで両方のターゲットが選択されます。

4. Link repository を選択します。platform は、リポジトリに別のプロジェクトを指す .mastra-project.json ファイルがないことを検証します。ファイルがある場合、ダッシュボードに警告が表示され、接続時にファイルを置き換える Overwrite オプションを選択できます。

接続後、設定したブランチへの次回のプッシュによってデプロイが開始されます。

.mastra-project.json の競合

platform はプロジェクトを識別するため、接続したすべてのリポジトリに .mastra-project.json ファイルを書き込みます。このファイルがすでにあるリポジトリを接続する場合、ダッシュボードは送信前に内容を確認します。

• Missing: 接続時に platform がファイルを作成します。
• Matching: ファイルは接続対象のプロジェクトをすでに指しているため、変更は不要です。
• Conflicting: ファイルは別のプロジェクトを指しています。キャンセルするか、明示的にファイルを上書きできます。

ファイルのスキーマについては、設定を参照してください。

プッシュによるデプロイ

リポジトリを接続すると、設定したブランチへのプッシュごとにデプロイが開始されます。

• Studio branch へのプッシュで Studio のデプロイが開始されます。
• Server branch へのプッシュで Server のデプロイが開始されます。
• 両方のターゲットが同じブランチを共有している場合、1 回のプッシュで両方のデプロイが並列に開始されます。

各デプロイには、コミット SHA、ブランチ、そして利用可能な場合はそのコミットを導入したプルリクエスト番号が含まれます。ビルドは platform 内で実行され、ステータスはコミット上のチェック実行として GitHub に返されます。

デプロイターゲットごとに一度に実行されるビルドは 1 つだけです。ビルド中に新しいプッシュが届いた場合、platform は同じターゲットに対する古いキュー済みビルドをキャンセルし、最新のビルドを実行します。Studio と Server のビルドは個別に追跡されるため、両方のターゲットが設定されている場合は並列に実行できます。

GitHub からの手動デプロイ

プッシュせずに、ダッシュボードからデプロイを開始することもできます。プロジェクトを開いて Deploy from GitHub を選択し、ターゲット（Studio、Server、または両方）とブランチを選んで送信します。platform はそのブランチの最新コミットに対してデプロイを実行し、トリガーを GitHub Workflow デプロイとして記録します。

デプロイを追跡する

テンプレートからプロジェクトを作成するか、リポジトリに接続すると、Setup ページにデプロイターゲットごとに 1 行が表示されます。各行には次の内容が表示されます。

• 完了するまでデプロイをポーリングするリアルタイムのステータスバッジ。
• デプロイ ID からデプロイ詳細ページへのリンク。
• ビルドログとランタイムログをインラインでストリーミングする Show logs トグル。デプロイがアクティブな間、Server のログは 3 秒ごとにポーリングされます。

権限と取り消し

リポジトリからのデプロイを停止するには、次のいずれかを行います。

• Project settings → Repository でプロジェクトからリポジトリの接続を解除します。プロジェクトの履歴は保持され、後から別のリポジトリを再接続できます。
• GitHub.com で Mastra GitHub App のリポジトリアクセスを削除します。既存のデプロイは実行を継続しますが、新しいプッシュによるデプロイは開始されません。
• GitHub アカウントから GitHub App をアンインストールします。そのアカウント上のすべてのリポジトリへのアクセスが削除されます。

GitHub が App のインストール用トークンを取り消すかローテーションした場合、リポジトリの読み取りは github_app_permissions_outdated エラーを返し、ダッシュボードは管理者に権限の再承認を求めます。

関連項目

• Mastra platform の概要
• Mastra platform の Studio
• Mastra platform の Server
• 設定