# Zeabur Deploy

> 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.

- Skill: `zeabur/zeabur-deploy` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zeabur/zeabur-deploy`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zeabur/zeabur-deploy/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: zeabur (https://skillmd.com/u/zeabur)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zeabur/zeabur-deploy

---


# 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:

```bash
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:

```bash
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:

```markdown
## 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.**

```bash
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:

```bash
# 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:**

```bash
# 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.