# Deploy

This page assumes an existing project and the identifier of its environment: see [Create a project](project.md).

## 1. Start the build

The `deployment_create` tool builds a Git reference and puts it live.

| Field | Required | Meaning |
| --- | --- | --- |
| `projectId` | yes | The `prj_...` identifier of the project. |
| `environmentId` | yes | The `env_...` identifier of the environment to deploy. |
| `ref` | no | Branch, tag or commit; by default, the environment's branch. |
| `stage` | no | True: build without putting it live; the version can be promoted afterwards. |
| `releaseId` | no | An already built release to promote, with no rebuild. |
| `idempotencyKey` | no | Replaying the call with the same key returns the first response. |

```json
{
  "projectId": "prj_01JQ8ZK4M7NP2RSTVWXYZ34567",
  "environmentId": "env_01JQ8ZK4M7NP2RSTVWXYZ34567",
  "ref": "main"
}
```

The response is immediate (`202`): it carries the deployment, a `taskId` (`job_...`) and `previousReleaseId`, the release that [a restore](restore.md) would bring back.

## 2. Follow the task

The `task_read` tool (arguments `projectId` and `taskId`) returns the state of the task and the progress of the deployment: its timestamped steps and their duration. It does not hold a connection open: read it again at a reasonable interval until a final state.

The `deployment_read` tool returns a deployment's state, its end cause and the duration of each step; with `diagnose`, it adds a ranked diagnosis.

## 3. Read the build log

If the build fails, the `deployment_log_read` tool returns the log, structured by step and timestamped to the millisecond. Fix the repository, then start again at step 1.

## 4. Cancel

`deployment_cancel` cancels a deployment still queued or building, before it has served.

## What is not done for you

Putting live what was built with `stage` takes a second call to `deployment_create` with `releaseId`. A write to the production environment is never silent: it is traced and may require a person's approval depending on its reversibility class, given in [the MCP reference](../reference/en/mcp.md).

See also: [Restore](restore.md).