Skip to content
forgit api docs

Create an environment

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

Creates an environment for a specified project.

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
name
required

The name of the environment

string
nullable
external_url

Place to link to for this environment

string
nullable
slug
string
nullable
tier

The tier of the new environment. Allowed values are production, staging, testing, development, and other

string
nullable
Allowed values: production staging testing development other
cluster_agent_id

The ID of the Cluster Agent to associate with this environment

integer
nullable
kubernetes_namespace

The Kubernetes namespace to associate with this environment

string
nullable
flux_resource_path

The Flux resource path to associate with this environment

string
nullable
description

The description of the environment

string
nullable
auto_stop_setting

The auto stop setting for the environment. Allowed values are always and with_action

string
nullable
Allowed values: always with_action

Responses

Section titled “ Responses ”

201

Section titled “ 201 ”

Created

Media type application/json
object
id
integer format: int64
name
string
slug
string
external_url
string
created_at
string format: date-time
updated_at
string format: date-time
tier
string
project
object
id
integer format: int64
description
string
name
string
name_with_namespace
string
path
string
path_with_namespace
string
created_at
string format: date-time
default_branch
string
tag_list
Array<string>
topics
Array<string>
ssh_url_to_repo
string
http_url_to_repo
string
web_url
string
readme_url
string
forks_count
integer
license_url
string
license
object
key
string
name
string
nickname
string
html_url
string
source_url
string
avatar_url
string
star_count
integer
last_activity_at
string format: date-time
visibility
string
namespace
object
id
integer format: int64
name
string
path
string
kind
string
full_path
string
parent_id
integer format: int64
avatar_url
string
web_url
string
custom_attributes
object
key
string
value
string
repository_storage
string
last_deployment
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
state
string
auto_stop_at
string format: date-time
cluster_agent
object
id
integer format: int64
name
string
config_project
object
id
integer format: int64
description
string
name
string
name_with_namespace
string
path
string
path_with_namespace
string
created_at
string format: date-time
created_at
string format: date-time
created_by_user_id
integer format: int64
is_receptive
boolean
kubernetes_namespace
string
flux_resource_path
string
description
string
auto_stop_setting
string
Example 
{
  "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",
  "tier": "development",
  "project": {
    "id": 1,
    "description": "desc",
    "name": "project1",
    "name_with_namespace": "John Doe / project1",
    "path": "project1",
    "path_with_namespace": "namespace1/project1",
    "created_at": "2020-05-07T04:27:17.016Z",
    "default_branch": "main",
    "tag_list": [
      "tag"
    ],
    "topics": [
      "topic"
    ],
    "ssh_url_to_repo": "git@gitlab.example.com:gitlab/gitlab.git",
    "http_url_to_repo": "https://gitlab.example.com/gitlab/gitlab.git",
    "web_url": "https://gitlab.example.com/gitlab/gitlab",
    "readme_url": "https://gitlab.example.com/gitlab/gitlab/blob/master/README.md",
    "forks_count": 1,
    "license_url": "https://gitlab.example.com/gitlab/gitlab/blob/master/LICENCE",
    "license": {
      "key": "gpl-3.0",
      "name": "GNU General Public License v3.0",
      "nickname": "GNU GPLv3",
      "html_url": "http://choosealicense.com/licenses/gpl-3.0"
    },
    "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png",
    "star_count": 1,
    "last_activity_at": "2013-09-30T13:46:02Z",
    "visibility": "public",
    "namespace": {
      "id": 2,
      "name": "project",
      "path": "my_project",
      "kind": "project",
      "full_path": "group/my_project",
      "parent_id": 1,
      "avatar_url": "https://example.com/avatar/12345",
      "web_url": "https://example.com/group/my_project"
    },
    "custom_attributes": {
      "key": "foo",
      "value": "bar"
    },
    "repository_storage": "default"
  },
  "last_deployment": {
    "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"
  },
  "state": "available",
  "auto_stop_at": "2019-05-25T18:55:13.252Z",
  "cluster_agent": {
    "id": 1,
    "config_project": {
      "id": 1,
      "description": "desc",
      "name": "project1",
      "name_with_namespace": "John Doe / project1",
      "path": "project1",
      "path_with_namespace": "namespace1/project1",
      "created_at": "2020-05-07T04:27:17.016Z"
    },
    "created_by_user_id": 1
  },
  "description": "description",
  "auto_stop_setting": "always"
}

400

Section titled “ 400 ”

Bad request

401

Section titled “ 401 ”

Unauthorized

404

Section titled “ 404 ”

Not found