version: "1.0.1" 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:

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

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

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.