deployment.io

Deploy and operate apps on deployment.io from any SKILL.md-compliant coding agent (Claude Code, Codex, Cursor, Gemini CLI, Copilot, Antigravity, JetBrains Junie, and more).

Prerequisites

This skill assumes the deployment.io MCP server is connected to your agent. If deploy_static_site, deploy_web_service, list_environments, etc. are not available as tools:

• Sign in at https://deployment.io and follow the agent-connection guide: https://deployment.io/docs/coding-agents/mcp-configuration/
• The MCP server uses OAuth 2.1 + PKCE; no tokens to copy-paste.

When to use this skill

• "Deploy the current branch to staging."
• "Ship this to production."
• "Why is the API returning 500? Check logs."
• "Create a new environment called preview-42."
• "Redeploy service X."

Parameter detection: static sites

For deploy_static_site:

• repository_url: git remote get-url origin
• branch: git branch --show-current (or the branch the user names)
• build_command: package.json scripts.build (check the branch with git show <branch>:package.json if not checked out)
• publish_directory: pick from the framework table below, or check framework config for overrides

| Framework | publish_directory | |---|---| | Vite, Svelte, Astro | dist | | Create React App | build | | Next.js static export | out | | Hugo | public | | Jekyll | _site |

• is_spa: true for apps that import react-router-dom or vue-router; false for static site generators (Hugo, Jekyll, Astro, Next.js export).

Parameter detection: web services

For deploy_web_service:

• port: the port the service listens on inside the container. Find it in one of:
• Dockerfile EXPOSE directive or ENV PORT=...
• App listen call: app.listen(3000), http.ListenAndServe(":8080"), uvicorn.run(port=8000)
• process.env.PORT, os.Getenv("PORT") usage
• dockerfile_path: omit unless the Dockerfile is not at the repo root (e.g. docker/Dockerfile).
• health_check_path: search the codebase for common routes — /health, /healthz, /ping, /ready, /status. Check Dockerfile for a HEALTHCHECK directive. If none found, omit (defaults to /).
• Dockerfile must exist on the deploy branch. For a non-checked-out branch: git show <branch>:Dockerfile. If missing and you're creating one, commit and push before calling the tool.

Git pre-flight (before any deploy_* call)

The runner clones from the remote, so only pushed commits deploy.

1. Fetch the remote branch.

git fetch origin <branch>

1. Check for unpushed commits:

git log origin/<branch>..HEAD Push anything listed. Do not proceed with unpushed work.

1. Capture the exact SHA to pass as commit_hash:

git rev-parse origin/<branch>

Write a changes_summary

Every deploy_* takes a changes_summary. Human reviewers see it on approval requests; keep it one-line and plain-English (don't paste raw git log). Example: "Hotfix for null-pointer in /api/users endpoint when email is missing."

Resolve environment_id

Always call list_environments first. If none match the target, offer to create one via create_environment (which itself calls list_runners first).

After an async call

deploy_* and get_deployment_logs are async — they return a structured accepted result containing job_id, poll_tool, poll_args, and poll_interval. Follow those fields: poll get_job_status at poll_interval until is_done: true. Log output lands in output.

Approval flow

Write tools on protected environments return a message starting "⏳ Approval required" with a request_id. Surface the approval URL to the user. Then poll get_approval_status with the request_id. Do not retry the original deploy call — the server runs it automatically on approval.

Diagnosing a bad deploy

1. list_deployments <environment_id> → find the deployment_id.
2. get_deployment_logs with a 5-minute window around the failure → returns a job_id.
3. Poll get_job_status until is_done; read output.
4. For build (not runtime) failures, the original deploy_* job's get_job_status already contains build logs; dashboard URL in the message body.

Creating Tasks (AI coding-agent PRs)

A task is a unit of engineering work you hand to an AI coding agent: it makes code changes across one or more repositories and opens a pull request per repository for review. Use tasks when the user wants the agent to make the change for them, rather than deploying code they've already written.

Cost awareness

Tasks burn the user's Anthropic/Bedrock budget — typical runs use 50k–500k tokens, larger refactors more. Do not call create_task speculatively. Confirm with the user before calling, especially when wrapping the call inside a longer agent workflow ("I'll have deployment.io fix this for you, is that OK?").

Parameter detection: create_task

• title: short noun phrase (≤ 200 chars), e.g. "Migrate users service to TypeScript".
• description: the actual prompt the agent will receive. Be specific — list constraints, files, acceptance criteria. Quality of description drives quality of output. Do not paste raw chat transcripts.
• repositories: one entry per repo the agent should touch. For each:
• repository_url: git remote get-url origin (or the URL the user names).
• branch: the base branch to work from. Detect the default with git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@', or use the branch the user names.
• model (optional): omit unless the user specifies. Server falls back to the org's configured default (typically "sonnet"). Explicit values: "haiku" (cheaper, simpler tasks), "sonnet" (balanced), "opus" (harder refactors).
• max_turns (optional): omit unless the user has a reason. Server default is 30, which fits most tasks. Raise to 50–80 explicitly for large refactors; lower to 10–15 for tightly-scoped edits.
• token_budget (optional): don't set this unless the user explicitly asks for a cost ceiling (0 = uncapped).

Polling

create_task returns an accepted envelope with task_id, poll_tool: "get_task_status", poll_args, poll_interval: "15s". Poll until is_done: true. Tasks take minutes to hours; don't poll faster than 15s.

Reading status

get_task_status returns the task's rolled-up state, per-repo PR URLs (populated once the PRs are opened), and the last 10 log lines from the most recent agent run. Full agent transcripts live at the url field — share that with the user for deep inspection.

Terminal states:

• Succeeded — PRs opened (check repositories[].pr_url). Surface each PR link to the user for review.
• NoChanges — agent ran but produced no diffs. Usually means the description was satisfied by existing code, or the agent couldn't find a path. Read latest_run_logs and surface to the user.
• Failed — read latest_run_logs and the dashboard url to diagnose. Common causes: the agent ran out of turns, or build/test checks failed during the run.
• Cancelled — user (or admin) stopped the task.

References

• Full tool reference: https://deployment.io/docs/coding-agents/available-mcp-tools/
• MCP server: https://api.deployment.io/v1/mcp (protocol version 2025-11-25)
• This repo: https://github.com/deployment-io/skills