---
title: "Create a deployment"
method: POST
path: "/api/v4/projects/{id}/deployments"
tags: ["deploy_resources"]
---

# Create a deployment

`POST /api/v4/projects/{id}/deployments`

## Request

- Base URL: `https://gitlab.com`
- URL: `https://gitlab.com/api/v4/projects/{id}/deployments`
- Auth: none declared

Creates a deployment.

## Path parameters

- `id` string, required

## Request body

- PostApiV4ProjectsIdDeployments: Create a deployment
  - `environment` string, required: The name of the environment to create the deployment for
  - `sha` string, required: The SHA of the commit that is deployed
  - `ref` string, required: The name of the branch or tag that is deployed
  - `tag` boolean, required: A boolean that indicates if the deployed ref is a tag (`true`) or not (`false`)
  - `status` 'running' | 'success' | 'failed' | 'canceled', required: The status of the deployment that is created. One of `running`, `success`, `failed`, or `canceled`

## Response `201`

Create a deployment

- APIEntitiesDeploymentExtended: API_Entities_DeploymentExtended model
  - `id` integer, required
  - `iid` integer, required
  - `ref` string, required
  - `sha` string, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `user` APIEntitiesUserBasic, required: API_Entities_UserBasic model
    - `id` integer, required
    - `username` string, required
    - `public_email` string, required
    - `name` string, required
    - `state` string, required
    - `locked` boolean, required
    - `avatar_url` string, required
    - `avatar_path` string
    - `custom_attributes` APIEntitiesCustomAttribute[]
      - `key` string, required
      - `value` string, required
    - `web_url` string, required
  - `environment` APIEntitiesEnvironmentBasic, required: API_Entities_EnvironmentBasic model
    - `id` integer, required
    - `name` string, required
    - `slug` string, required
    - `external_url` string, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `deployable` APIEntitiesCiJob, required: API_Entities_Ci_Job model
    - `id` integer, required
    - `status` string, required
    - `stage` string, required
    - `name` string, required
    - `ref` string, required
    - `tag` boolean, required
    - `coverage` number, float, required
    - `allow_failure` boolean, required
    - `created_at` string, date-time, required
    - `started_at` string, date-time, required
    - `finished_at` string, date-time, required
    - `erased_at` string, date-time, required
    - `duration` number, float, required: Time spent running
    - `queued_duration` number, float, required: Time spent enqueued
    - `user` APIEntitiesUser, required
      - `id` integer, required
      - `username` string, required
      - `public_email` string, required
      - `name` string, required
      - `state` string, required
      - `locked` boolean, required
      - `avatar_url` string, required
      - `avatar_path` string
      - `custom_attributes` APIEntitiesCustomAttribute[]
        - `key` string, required
        - `value` string, required
      - `web_url` string, required
      - `created_at` string
      - `bio` string, required
      - `location` string, required
      - `linkedin` string, required
      - `twitter` string, required
      - `discord` string, required
      - `website_url` string, required
      - `github` string, required
      - `job_title` string, required
      - `pronouns` string, required
      - `organization` string, required
      - `bot` boolean, required
      - `work_information` string, required
      - `followers` string
      - `following` string
      - `is_followed` string
      - `local_time` string, required
    - `commit` APIEntitiesCommit, required: API_Entities_Commit model
      - `id` string, required
      - `short_id` string, required
      - `created_at` string, date-time, required
      - `parent_ids` string[], required
      - `title` string, required
      - `message` string, required
      - `author_name` string, required
      - `author_email` string, required
      - `authored_date` string, date-time, required
      - `committer_name` string, required
      - `committer_email` string, required
      - `committed_date` string, date-time, required
      - `trailers` object, required
      - `extended_trailers` object, required
      - `web_url` string, required
    - `pipeline` APIEntitiesCiPipelineBasic, required: API_Entities_Ci_PipelineBasic model
      - `id` integer, required
      - `iid` integer, required
      - `project_id` integer, required
      - `sha` string, required
      - `ref` string, required
      - `status` string, required
      - `source` string, required
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
      - `web_url` string, required
    - `failure_reason` string
    - `web_url` string, required
    - `project` object, required
      - `ci_job_token_scope_enabled` string, required
    - `artifacts_file` APIEntitiesCiJobArtifactFile
      - `filename` string, required
      - `size` integer, required
    - `artifacts` APIEntitiesCiJobArtifact[], required
      - `file_type` 'archive' | 'metadata' | 'trace' | 'junit' | 'sast' | 'dependency_scanning' | 'container_scanning' | 'dast' | 'codequality' | 'license_scanning' | 'performance' | 'metrics' | 'metrics_referee' | 'network_referee' | 'lsif' | 'dotenv' | 'cobertura' | 'terraform' | 'accessibility' | 'cluster_applications' | 'secret_detection' | 'requirements' | 'coverage_fuzzing' | 'browser_performance' | 'load_performance' | 'api_fuzzing' | 'cluster_image_scanning' | 'cyclonedx' | 'requirements_v2' | 'annotations' | 'repository_xray' | 'jacoco' | 'sarif', required
      - `size` integer, required
      - `filename` string, required
      - `file_format` 'raw' | 'zip' | 'gzip', required
    - `runner` APIEntitiesCiRunner, required: API_Entities_Ci_Runner model
      - `id` integer, required
      - `description` string, required
      - `ip_address` string, required
      - `active` boolean, required
      - `paused` boolean, required
      - `is_shared` boolean, required
      - `runner_type` 'instance_type' | 'group_type' | 'project_type', required
      - `name` string, required
      - `online` boolean, required
      - `created_by` APIEntitiesUserBasic: API_Entities_UserBasic model
        - `id` integer, required
        - `username` string, required
        - `public_email` string, required
        - `name` string, required
        - `state` string, required
        - `locked` boolean, required
        - `avatar_url` string, required
        - `avatar_path` string
        - `custom_attributes` APIEntitiesCustomAttribute[]
          - `key` string, required
          - `value` string, required
        - `web_url` string, required
      - `created_at` string, date-time, required
      - `status` string, required
      - `job_execution_status` 'active' | 'idle', required
    - `runner_manager` APIEntitiesCiRunnerManager: API_Entities_Ci_RunnerManager model
      - `id` integer, required
      - `system_id` string, required
      - `version` string, required
      - `revision` string, required
      - `platform` string, required
      - `architecture` string, required
      - `created_at` string, required
      - `contacted_at` string, required
      - `ip_address` string, required
      - `status` string, required
      - `job_execution_status` 'active' | 'idle', required
    - `artifacts_expire_at` string, date-time, required
    - `archived` boolean, required
    - `tag_list` string[], required
  - `status` string, required
  - `pending_approval_count` integer, required
  - `approvals` APIEntitiesDeploymentsApproval, required: API_Entities_Deployments_Approval model
    - `user` APIEntitiesUserBasic, required: API_Entities_UserBasic model
      - `id` integer, required
      - `username` string, required
      - `public_email` string, required
      - `name` string, required
      - `state` string, required
      - `locked` boolean, required
      - `avatar_url` string, required
      - `avatar_path` string
      - `custom_attributes` APIEntitiesCustomAttribute[]
        - `key` string, required
        - `value` string, required
      - `web_url` string, required
    - `status` string, required
    - `created_at` string, date-time, required
    - `comment` string, required
  - `approval_summary` APIEntitiesDeploymentsApprovalSummary, required
    - `rules` APIEntitiesProtectedEnvironmentsApprovalRuleForSummary, required
      - `id` integer, required
      - `user_id` integer, required
      - `group_id` integer, required
      - `access_level` integer, required
      - `access_level_description` string, required
      - `required_approvals` integer, required
      - `group_inheritance_type` integer, required
      - `deployment_approvals` APIEntitiesDeploymentsApproval, required: API_Entities_Deployments_Approval model
        - `user` APIEntitiesUserBasic, required: API_Entities_UserBasic model
          - `id` integer, required
          - `username` string, required
          - `public_email` string, required
          - `name` string, required
          - `state` string, required
          - `locked` boolean, required
          - `avatar_url` string, required
          - `avatar_path` string
          - `custom_attributes` APIEntitiesCustomAttribute[]
            - `key` string, required
            - `value` string, required
          - `web_url` string, required
        - `status` string, required
        - `created_at` string, date-time, required
        - `comment` string, required

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `404`: Not found

---

[API](https://skmtc.dev/gitlab/apis/gitlab-api.md) - [All operations](https://skmtc.dev/gitlab/apis/gitlab-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gitlab/apis/gitlab-api/revisions/b234947ef3f2?raw)