zeabur-deploy

name	zeabur-deploy
description	Use when deploying a local project or codebase to Zeabur. Use when the user says "deploy this", "deploy to Zeabur", "deploy from GitHub", "search my repos", or "find my repository". Default to direct deploy unless the user explicitly asks for Git-based deployment.

Zeabur Deploy

Always use npx zeabur@latest to invoke Zeabur CLI. Never use zeabur directly or any other installation method. If npx is not available, install Node.js first.

Prerequisites — Identify the Target Project

Before using this skill, you must first determine which Zeabur project to deploy to. If neither the conversation history nor project files mention a project, run:

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

• When projects exist, ask the user which one to use.
• If the list is empty, or the user wants to create a new project, you MUST invoke the zeabur-project-create skill. Do NOT run project create CLI commands directly — the skill handles region selection via server list, which is required.

Do not proceed with deployment until the target project is confirmed.

Deploying to a Specific Dedicated Server

If the user asks to deploy to a specific server (e.g. "deploy to my AWS Tokyo server"), do NOT SSH into the server. Servers running ZeaburOS are managed via the platform — you deploy services through the Zeabur CLI, not by manually placing files on the machine.

Only ZeaburOS servers can host projects. A rented server starts as plain Ubuntu (base OS and SSH, no Zeabur services); ZeaburOS has to be installed on it first — see the zeabur-server-rent skill. If deploying to a server fails because it has no Zeabur services, that is why; tell the user instead of trying to set the machine up over SSH.

To find the project bound to a server:

1. Get the server ID from npx zeabur@latest server list -i=false (or from conversation context).
2. In the project list --json output, look for a project whose Region.ID matches server-<server-id>.
3. If a matching project exists, use its project ID to deploy.
4. If no matching project exists, invoke the zeabur-project-create skill to create one on that server.

Choosing a Deploy Method

Zeabur supports two ways to deploy a project:

Method	When to use
Direct deploy (default)	User says "deploy this project/website/app". No Git repo required. Fast and simple.
Git deploy	User explicitly asks to deploy via Git/GitHub, or wants CI/CD with automatic redeploy on push.

Default to direct deploy unless the user specifically requests Git-based deployment.

Direct Deploy (Default)

Deploy the current local directory to Zeabur with one command.

Flags

Flag	Required	Description
--project-id	Yes (non-interactive)	Project ID to deploy on
--json	Recommended	Output in JSON format
--name	No	Service name (defaults to directory name)
--service-id	No	Service ID to redeploy on (omit to create new service)
--environment-id	No	Environment ID (defaults to first environment)

Note: Do NOT use --create, -r, or --region flags with deploy commands. If the user needs to create a new project or select a region, use the zeabur-project-create skill first.

First Deploy

When deploying for the first time, omit --service-id — a new service is created automatically:

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

The response includes a service_id. You MUST save this service_id for all subsequent deploys. Write it to the current project's CLAUDE.md immediately:

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

Redeploy (Update Existing Service)

IMPORTANT: When redeploying code changes, you MUST pass --service-id to update the existing service. Omitting --service-id creates a NEW duplicate service every time.

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

Do NOT use this flow for version upgrades / downgrades of prebuilt or marketplace services (e.g. "upgrade PostgreSQL to 16", "downgrade n8n to 1.2"). That is a version switch, not a code redeploy — use the zeabur-update-service skill's tag update instead. Redeploying in place of a tag change can orphan or wipe the service's mounted disk.

If no project exists yet, invoke the zeabur-project-create skill (do not run CLI commands directly).

Git Deploy (On User Request)

If the user explicitly wants Git-based deployment (e.g. for CI/CD, auto-redeploy on push):

1. First, ensure the code is pushed to a GitHub repository.
2. Deploy via 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 Deploy Flags

Flag	Required	Description
--template GIT	Yes	Specifies Git-based deployment
--project-id	Non-interactive	Project ID (interactive mode will prompt)
--repo-id	Non-interactive	GitHub repository ID
--branch-name	Non-interactive	Git branch to deploy from
--name	No	Service name (defaults to repo name)
--keyword	No	Keyword to search GitHub repos (interactive mode)

Git Deploy Workflow

Git deploy workflow:

# 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

After deployment, Zeabur will auto-redeploy on every push to the selected branch.

Only guide the user through this flow when they specifically ask for Git-based deployment.

Tips

• Direct deploy only requires --project-id — a new service is created automatically. No Git history or GitHub account required.
• For static sites, Zeabur auto-detects and serves them correctly.
• Always save both Project ID and Service ID after first deploy. This prevents duplicate services on redeploy.
• After deployment, use the zeabur-deployment-logs skill to check build and runtime logs.