> ## Documentation Index
> Fetch the complete documentation index at: https://unkey.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Unkey is two separate products. Compute builds, deploys, and runs apps behind a gateway. API Management issues API keys, enforces rate limits, manages identities and permissions, and reports usage. Say which product a page belongs to; a reader can use either without the other.
> Every Unkey API endpoint is an HTTP POST to https://api.unkey.com/v2/{service}.{procedure} with a root key in the Authorization: Bearer header. Root keys are workspace scoped.
> Error codes have the form err:{system}:{category}:{specific} and each has a page at /errors/{system}/{category}/{specific}.
> The word environment means production or preview in Compute. Rate limiting has four meanings on this site; the glossary lists them.

# unkey api deployments create-deployment

> Start a deployment from a Git ref, an image, or an earlier deployment.

<Note>
  You need a root key with the permissions listed on this page. Create one in the dashboard under **Settings > Root Keys**. See [Permission reference](/docs/platform/root-keys/permissions-legacy) for every permission.
</Note>

Create a deployment for an <Tooltip tip="A Compute app: a deployable service inside a project. Not your application in general.">app</Tooltip> in one of its <Tooltip tip="Production or preview environments of a Compute app, not the dashboard label on a key.">environments</Tooltip>. With no source flag, the app deploys its usual source: a Git app builds its default branch, and an image app deploys its default image. That's what you want in CI for a routine redeploy.

To deploy something else, pass one source flag:

* `--oci` deploys a prebuilt image, with no build. A tag like `latest` is pinned to the exact image it points to when you deploy.
* `--git` builds a branch, commit, or fork commit from the app's connected repository.
* `--deployment` redeploys an existing deployment. A Git deployment rebuilds from its commit, and an image deployment reuses its image.

You can pass only one of them.

The command returns a `deploymentId` right away, while the build and rollout keep running. Poll [get-deployment](/docs/compute/cli/deployments/get-deployment) to follow the status.

Deploying needs an active Compute plan. Without one the API answers 412 with `The workspace has no active Compute plan.` A workspace over its Compute spend cap gets `The workspace is suspended by its Compute spend cap. Raise the spend limit to resume.` See [Compute plans](/docs/compute/get-started/plans).

## Usage

```bash theme={"system"}
unkey api deployments create-deployment --project=<project> --app=<app> --environment=<environment> [--git=<json> | --oci=<json> | --deployment=<json>]
```

## Flags

<ParamField body="--app" type="string" required>
  App ID or slug.
</ParamField>

<ParamField body="--deployment" type="string">
  Existing deployment to re-run, as a JSON object with a `deploymentId` field. It must be in the same app and environment. Any other ID returns `The specified deployment does not exist.`
</ParamField>

<ParamField body="--environment" type="string" required>
  Environment ID or slug the deployment lands in.
</ParamField>

<ParamField body="--git" type="string">
  Git source as a JSON object with `branch`, `commitSha`, or a fork's `repository` plus `commitSha`, for example `{"branch":"main"}`. Requires the app to have a repository connected.
</ParamField>

<ParamField body="--oci" type="string">
  OCI image source as a JSON object with a required `image` field. A tag is pinned to the exact image it points to when you deploy.
</ParamField>

<ParamField body="--project" type="string" required>
  Project ID or slug. Both forms resolve to the same project.
</ParamField>

### Shared flags

Every `unkey api` command accepts these; [CLI output and shared flags](/docs/platform/cli/output-and-flags) describes them in full.

<ParamField body="--body" type="string">
  A JSON document sent as the request body instead of building it from the flags above. It is mutually exclusive with the request-building flags, and unknown fields are rejected locally. See [Send a raw body](/docs/platform/cli/output-and-flags#send-a-raw-body).
</ParamField>

<ParamField body="--root-key" type="string">
  Root key for the request. Falls back to `UNKEY_ROOT_KEY`, then to the config file written by `unkey auth login`. See [CLI authentication](/docs/platform/cli/authentication).
</ParamField>

<ParamField body="--api-url" type="string" default="https://api.unkey.com">
  Base URL of the API. Falls back to `UNKEY_API_BASE_URL`. You don't normally need to set it.
</ParamField>

<ParamField body="--config" type="string" default="~/.unkey/config.toml">
  Path of the TOML file that `unkey auth login` writes. Falls back to `UNKEY_CONFIG`.
</ParamField>

<ParamField body="--output" type="string">
  Output format. Falls back to `UNKEY_OUTPUT`. Set `json` to print the full response envelope (`meta` and `data`) for piping; any other value prints the request ID followed by `data`.
</ParamField>

## Required permissions

Your root key needs one of:

* `environment.*.create_deployment` (any environment)
* `environment.<environment_id>.create_deployment` (a specific environment)

Without a matching permission the API answers 403 and the CLI prints `Permission denied:` followed by the detail. See [Root key permissions](/docs/platform/root-keys/permissions) for the full catalog.

## Examples

Deploy the app's configured source:

```bash theme={"system"}
unkey api deployments create-deployment --project=payments --app=payments-api --environment=production
```

Build and deploy a specific branch:

```bash theme={"system"}
unkey api deployments create-deployment --project=payments --app=payments-api --environment=production --git='{"branch":"main"}'
```

Deploy a prebuilt image:

```bash theme={"system"}
unkey api deployments create-deployment --project=payments --app=payments-api --environment=preview --oci='{"image":"ghcr.io/acme/payments:1.4.2"}'
```

Send the request body as JSON and capture the ID:

```bash theme={"system"}
unkey api deployments create-deployment --body='{"project":"payments","app":"payments-api","environment":"production","git":{"branch":"main"}}' --output=json | jq -r '.data.deploymentId'
```

## API endpoint

The command calls [`POST /v3/deployments.createDeployment`](/docs/compute/api-reference/deployments/create-deployment) and prints its response. The request fields carry the same names as the flags in camelCase, which is the shape `--body` expects.

## Related

<Columns cols={2}>
  <Card title="Deployments" href="/docs/compute/concepts/deployments">
    Statuses, the build queue, and why a deployment fails.
  </Card>

  <Card title="unkey deploy" href="/docs/compute/cli/deploy">
    The one-shot command that deploys an image and waits for it.
  </Card>
</Columns>