zeabur-deploy

Zeabur のデプロイ

Zeabur CLI の呼び出しには、必ず npx zeabur@latest を使用してください。 zeabur を直接実行したり、ほかのインストール方法を使ったりしないでください。npx が利用できない場合は、先に Node.js をインストールしてください。

前提条件 — 対象プロジェクトの特定

このスキルを使う前に、デプロイ先の Zeabur プロジェクトを必ず特定してください。会話履歴にもプロジェクトファイルにもプロジェクトの記載がない場合は、次を実行してください。

npx zeabur@latest project list -i=false --json

• プロジェクトが存在する場合は、どのプロジェクトを使うかユーザーに確認してください。
• 一覧が空の場合、またはユーザーが新しいプロジェクトの作成を希望する場合は、必ず zeabur-project-create スキルを呼び出してください。project create CLI コマンドを直接実行しないでください。このスキルは、必須となるサーバー一覧によるリージョン選択を処理します。

対象プロジェクトが確認できるまで、デプロイを進めないでください。

特定の専用サーバーへのデプロイ

ユーザーが特定のサーバー（例：「AWS の東京サーバーにデプロイして」）へのデプロイを希望する場合、サーバーに SSH 接続しないでください。ZeaburOS を実行しているサーバーはプラットフォーム経由で管理します。デプロイには Zeabur CLI を使い、手動でマシンにファイルを配置しないでください。

プロジェクトをホストできるのは ZeaburOS サーバーだけです。 レンタルしたサーバーは、初期状態では通常の Ubuntu（ベース OS と SSH のみで、Zeabur サービスはありません）です。まず ZeaburOS をインストールする必要があります。zeabur-server-rent スキルを参照してください。Zeabur サービスがないためにサーバーへのデプロイに失敗した場合は、それが原因です。SSH でマシンをセットアップしようとせず、その旨をユーザーに伝えてください。

サーバーに紐づくプロジェクトを見つけるには、次の手順に従ってください。

1. npx zeabur@latest server list -i=false（または会話のコンテキスト）からサーバー ID を取得します。
2. project list --json の出力から、Region.ID が server-<server-id> と一致するプロジェクトを探します。
3. 一致するプロジェクトがある場合は、そのプロジェクト ID を使ってデプロイします。
4. 一致するプロジェクトがない場合は、そのサーバー上にプロジェクトを作成するため、zeabur-project-create スキルを呼び出してください。

デプロイ方法の選択

Zeabur では、プロジェクトをデプロイする方法が 2 つあります。

方法	使用する状況
直接デプロイ（デフォルト）	ユーザーが「このプロジェクト／ウェブサイト／アプリをデプロイして」と言った場合。Git リポジトリは不要です。高速で簡単です。
Git デプロイ	ユーザーが Git／GitHub 経由でのデプロイを明示的に希望する場合、またはプッシュ時に自動再デプロイされる CI/CD を希望する場合。

ユーザーが Git ベースのデプロイを特に希望していない限り、直接デプロイをデフォルトとして選択してください。

直接デプロイ（デフォルト）

現在のローカルディレクトリを、1 つのコマンドで Zeabur にデプロイします。

フラグ

フラグ	必須	説明
--project-id	はい（非対話型の場合）	デプロイ先のプロジェクト ID
--json	推奨	JSON 形式で出力します
--name	いいえ	サービス名（デフォルトはディレクトリ名）
--service-id	いいえ	再デプロイ先のサービス ID（省略すると新しいサービスを作成します）
--environment-id	いいえ	環境 ID（デフォルトは最初の環境）

注： デプロイコマンドでは、--create、-r、--region フラグを使用しないでください。ユーザーが新しいプロジェクトの作成やリージョンの選択を希望する場合は、先に zeabur-project-create スキルを使ってください。

初回デプロイ

初回のデプロイでは、--service-id を省略してください。新しいサービスが自動的に作成されます。

npx zeabur@latest deploy --project-id <project-id> --json

応答には service_id が含まれます。以降のすべてのデプロイで使うため、この service_id を必ず保存してください。 ただちに、現在のプロジェクトの CLAUDE.md に書き込んでください。

## Zeabur Deployment
- Project ID: <project-id>
- Service ID: <service-id>

再デプロイ（既存サービスの更新）

重要：コード変更を再デプロイする場合、既存のサービスを更新するには必ず --service-id を指定してください。--service-id を省略すると、毎回新しい重複サービスが作成されます。

npx zeabur@latest deploy --project-id <project-id> --service-id <service-id> --json

ビルド済みサービスやマーケットプレイスサービスのバージョンアップ／ダウングレード（例：「PostgreSQL を 16 にアップグレードする」「n8n を 1.2 にダウングレードする」）には、この方法を使用しないでください。 これはコードの再デプロイではなくバージョンの切り替えです。代わりに、zeabur-update-service スキルのタグ更新を使用してください。タグを変更する代わりに再デプロイすると、サービスにマウントされたディスクが孤立したり、消去されたりする可能性があります。

まだプロジェクトがない場合は、zeabur-project-create スキルを呼び出してください（CLI コマンドを直接実行しないでください）。

Git デプロイ（ユーザーの要望がある場合）

ユーザーが Git ベースのデプロイ（CI/CD や、プッシュ時の自動再デプロイなど）を明示的に希望する場合：

1. まず、コードが GitHub リポジトリにプッシュされていることを確認します。
2. CLI でデプロイします：

# Non-interactive mode — required parameters only
npx zeabur@latest service deploy --json -i=false \
  --project-id <project-id> \
  --template GIT \
  --repo-id <repo-id> \
  --branch-name <branch>

# With optional service name
npx zeabur@latest service deploy --json -i=false \
  --project-id <project-id> \
  --template GIT \
  --repo-id <repo-id> \
  --branch-name <branch> \
  --name "<service-name>"

Git デプロイのフラグ

フラグ	必須	説明
--template GIT	はい	Git ベースのデプロイを指定します
--project-id	非対話型	プロジェクト ID（対話型モードでは入力を求められます）
--repo-id	非対話型	GitHub リポジトリ ID
--branch-name	非対話型	デプロイ元の Git ブランチ
--name	いいえ	サービス名（デフォルトはリポジトリ名）
--keyword	いいえ	GitHub リポジトリを検索するキーワード（対話型モード）

Git デプロイのワークフロー

Git デプロイのワークフロー：

# 1. Search for the user's GitHub repo
npx zeabur@latest service search-repo <keyword> --json -i=false
# Returns: [{"Name":"my-app","Owner":"user","URL":"...","ID":12345}, ...]
# If multiple results are returned, ask the user which repo to deploy.
# The agent (not the CLI) is responsible for disambiguation.

# 2. Deploy from GitHub using the repo ID from search results
npx zeabur@latest service deploy --json -i=false \
  --project-id $PROJECT_ID \
  --template GIT \
  --repo-id <repo-id> \
  --branch-name main

デプロイ後、選択したブランチにプッシュするたびに、Zeabur が自動で再デプロイします。

Git ベースのデプロイを明示的に希望している場合に限り、この手順を案内してください。

ヒント

• 直接デプロイでは --project-id の指定だけで、新しいサービスが自動的に作成されます。Git の履歴や GitHub アカウントは不要です。
• 静的サイトは Zeabur が自動検出し、適切に配信します。
• 初回デプロイ後は、プロジェクト ID とサービス ID の両方を必ず保存してください。 これにより、再デプロイ時の重複サービスを防げます。
• デプロイ後は zeabur-deployment-logs スキルを使用して、ビルドと実行時のログを確認してください。