Skip to content
forgit api docs

Create a deployment

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

Creates a deployment.

Authorizations

Section titled “ Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
id
required
One of:
string

The ID or URL-encoded path of the project owned by the authenticated user

Request Body required

Section titled “ Request Body required ”
Media type application/json
object
environment
required

The name of the environment to create the deployment for

string
nullable
sha
required

The SHA of the commit that is deployed

string
nullable
ref
required

The name of the branch or tag that is deployed

string
nullable
tag
required

A boolean that indicates if the deployed ref is a tag (true) or not (false)

boolean
nullable
status
required

The status of the deployment that is created. One of running, success, failed, or canceled

string
>= 1 characters
Allowed values: running success failed canceled

Responses

Section titled “ Responses ”

201

Section titled “ 201 ”

Created

Media type application/json
object
id
integer format: int64
iid
integer
ref
string
sha
string
created_at
string format: date-time
updated_at
string format: date-time
user
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
environment
object
id
integer format: int64
name
string
slug
string
external_url
string
created_at
string format: date-time
updated_at
string format: date-time
deployable
object
id
integer format: int64
status
string
stage
string
name
string
ref
string
tag
boolean
coverage
number format: float
allow_failure
boolean
created_at
string format: date-time
started_at
string format: date-time
finished_at
string format: date-time
erased_at
string format: date-time
duration

Time spent running

number format: float
queued_duration

Time spent enqueued

number format: float
user
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
created_at
string
bio
string
location
string
linkedin
string
twitter
string
discord
string
website_url
string
github
string
job_title
string
pronouns
string
organization
string
bot
boolean
work_information
string
followers
string
following
string
is_followed
string
local_time
string
commit
object
id
string
short_id
string
created_at
string format: date-time
parent_ids
Array<string>
title
string
message
string
author_name
string
author_email
string
authored_date
string format: date-time
committer_name
string
committer_email
string
committed_date
string format: date-time
trailers
object
extended_trailers
object
web_url
string
pipeline
object
id
integer format: int64
iid
integer
project_id
integer format: int64
sha
string
ref
string
status
string
source
string
created_at
string format: date-time
updated_at
string format: date-time
web_url
string
failure_reason
string
web_url
string
project
string
artifacts_file
object
filename
string
size
integer
artifacts
Array<object>
object
file_type
string
size
integer
filename
string
file_format
string
runner
object
id
integer format: int64
description
string
ip_address
string
active
boolean
paused
boolean
is_shared
boolean
runner_type
string
name
string
online
boolean
created_by
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
created_at
string format: date-time
status
string
job_execution_status
string
runner_manager
object
id
integer format: int64
system_id
string
version
string
revision
string
platform
string
architecture
string
created_at
string
contacted_at
string
ip_address
string
status
string
job_execution_status
string
artifacts_expire_at
string format: date-time
archived
boolean
tag_list
Array<string>
status
string
pending_approval_count
integer
approvals
object
user
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
status
string
created_at
string format: date-time
comment
string
approval_summary
object
rules
object
id
integer format: int64
user_id
integer format: int64
group_id
integer format: int64
access_level
integer
access_level_description
string
required_approvals
integer
group_inheritance_type
integer
deployment_approvals
object
user
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
status
string
created_at
string format: date-time
comment
string
Example 
{
  "id": 41,
  "iid": 1,
  "ref": "main",
  "sha": "99d03678b90d914dbb1b109132516d71a4a03ea8",
  "created_at": "2016-08-11T11:32:35.444Z",
  "updated_at": "2016-08-11T11:32:35.444Z",
  "user": {
    "id": 1,
    "username": "admin",
    "public_email": "john@example.com",
    "name": "Administrator",
    "state": "active",
    "avatar_url": "https://gravatar.com/avatar/1",
    "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
    "custom_attributes": [
      {
        "key": "foo",
        "value": "bar"
      }
    ],
    "web_url": "https://gitlab.example.com/root"
  },
  "environment": {
    "id": 1,
    "name": "deploy",
    "slug": "deploy",
    "external_url": "https://deploy.gitlab.example.com",
    "created_at": "2019-05-25T18:55:13.252Z",
    "updated_at": "2019-05-25T18:55:13.252Z"
  },
  "deployable": {
    "id": 1,
    "status": "waiting_for_resource",
    "stage": "deploy",
    "name": "deploy_to_production",
    "ref": "main",
    "coverage": 98.29,
    "created_at": "2015-12-24T15:51:21.880Z",
    "started_at": "2015-12-24T17:54:30.733Z",
    "finished_at": "2015-12-24T17:54:31.198Z",
    "erased_at": "2015-12-24T18:00:29.728Z",
    "duration": 0.465,
    "queued_duration": 0.123,
    "user": {
      "id": 1,
      "username": "admin",
      "public_email": "john@example.com",
      "name": "Administrator",
      "state": "active",
      "avatar_url": "https://gravatar.com/avatar/1",
      "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
      "custom_attributes": [
        {
          "key": "foo",
          "value": "bar"
        }
      ],
      "web_url": "https://gitlab.example.com/root"
    },
    "commit": {
      "id": "2695effb5807a22ff3d138d593fd856244e155e7",
      "short_id": "2695effb",
      "created_at": "2017-07-26T11:08:53.000+02:00",
      "parent_ids": [
        "2a4b78934375d7f53875269ffd4f45fd83a84ebe"
      ],
      "title": "Initial commit",
      "message": "Initial commit",
      "author_name": "John Smith",
      "author_email": "john@example.com",
      "authored_date": "2012-05-28T04:42:42-07:00",
      "committer_name": "Jack Smith",
      "committer_email": "jack@example.com",
      "committed_date": "2012-05-28T04:42:42-07:00",
      "trailers": {
        "Merged-By": "Jane Doe janedoe@gitlab.com"
      },
      "extended_trailers": {
        "Signed-off-by": [
          "John Doe <johndoe@gitlab.com>",
          "Jane Doe <janedoe@gitlab.com>"
        ]
      },
      "web_url": "https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746"
    },
    "pipeline": {
      "id": 1,
      "iid": 2,
      "project_id": 3,
      "sha": "0ec9e58fdfca6cdd6652c083c9edb53abc0bad52",
      "ref": "feature-branch",
      "status": "success",
      "source": "push",
      "created_at": "2022-10-21T16:49:48.000+02:00",
      "updated_at": "2022-10-21T16:49:48.000+02:00",
      "web_url": "https://gitlab.example.com/gitlab-org/gitlab-foss/-/pipelines/61"
    },
    "failure_reason": "script_failure",
    "web_url": "https://example.com/foo/bar/-/jobs/1",
    "artifacts_file": {
      "filename": "artifacts.zip",
      "size": 1000
    },
    "artifacts": [
      {
        "file_type": "archive",
        "size": 1000,
        "filename": "artifacts.zip",
        "file_format": "zip"
      }
    ],
    "runner": {
      "id": 8,
      "description": "test-1-20150125",
      "ip_address": "127.0.0.1",
      "active": true,
      "paused": false,
      "is_shared": true,
      "runner_type": "instance_type",
      "name": "test",
      "online": true,
      "created_by": {
        "id": 1,
        "username": "admin",
        "public_email": "john@example.com",
        "name": "Administrator",
        "state": "active",
        "avatar_url": "https://gravatar.com/avatar/1",
        "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
        "custom_attributes": [
          {
            "key": "foo",
            "value": "bar"
          }
        ],
        "web_url": "https://gitlab.example.com/root"
      },
      "created_at": "2025-05-03T00:00:00.000Z",
      "status": "online",
      "job_execution_status": "idle"
    },
    "runner_manager": {
      "id": 8,
      "system_id": "runner-1",
      "version": "16.11.0",
      "revision": "91a27b2a",
      "platform": "linux",
      "architecture": "amd64",
      "created_at": "2023-10-24T01:27:06.549Z",
      "contacted_at": "2023-10-24T01:27:06.549Z",
      "ip_address": "127.0.0.1",
      "status": "online",
      "job_execution_status": "idle"
    },
    "artifacts_expire_at": "2016-01-19T09:05:50.355Z",
    "archived": false,
    "tag_list": [
      "ubuntu18",
      "docker runner"
    ]
  },
  "status": "created",
  "pending_approval_count": 0,
  "approvals": {
    "user": {
      "id": 1,
      "username": "admin",
      "public_email": "john@example.com",
      "name": "Administrator",
      "state": "active",
      "avatar_url": "https://gravatar.com/avatar/1",
      "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
      "custom_attributes": [
        {
          "key": "foo",
          "value": "bar"
        }
      ],
      "web_url": "https://gitlab.example.com/root"
    },
    "status": "approved",
    "created_at": "2022-02-24T20:22:30.097Z",
    "comment": "LGTM"
  },
  "approval_summary": {
    "rules": {
      "deployment_approvals": {
        "user": {
          "id": 1,
          "username": "admin",
          "public_email": "john@example.com",
          "name": "Administrator",
          "state": "active",
          "avatar_url": "https://gravatar.com/avatar/1",
          "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
          "custom_attributes": [
            {
              "key": "foo",
              "value": "bar"
            }
          ],
          "web_url": "https://gitlab.example.com/root"
        },
        "status": "approved",
        "created_at": "2022-02-24T20:22:30.097Z",
        "comment": "LGTM"
      }
    }
  }
}

400

Section titled “ 400 ”

Bad request

401

Section titled “ 401 ”

Unauthorized

404

Section titled “ 404 ”

Not found