Environments

Use this API to interact with GitLab environments.

List all environments

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

Lists all environments for a specified project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project owned by the authenticated user
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`
`name` Query	String	Return the environment with this name. Mutually exclusive with `search`
`search` Query	String	Return list of environments matching the search criteria. Must be at least 3 characters. Mutually exclusive with `name`
`states` Query	String	List all environments that match a specific state. Accepted values: `available`, `stopping`, or `stopped`. If no state value given, returns all environments Allowed values: `stopped`, `stopping`, `available`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesEnvironment
`400`	Bad Request	—
`401`	Unauthorized	—
`404`	Not found	—

Create an environment

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

Creates an environment for a specified project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project owned by the authenticated user

Request body (application/json)

Property	Type	Description
`auto_stop_setting`	String	The auto stop setting for the environment. Allowed values are `always` and `with_action` Allowed values: `always`, `with_action`
`cluster_agent_id`	Integer	The ID of the Cluster Agent to associate with this environment
`description`	String	The description of the environment
`external_url`	String	Place to link to for this environment
`flux_resource_path`	String	The Flux resource path to associate with this environment
`kubernetes_namespace`	String	The Kubernetes namespace to associate with this environment
`name` Required	String	The name of the environment
`tier`	String	The tier of the new environment. Allowed values are `production`, `staging`, `testing`, `development`, and `other` Allowed values: `production`, `staging`, `testing`, `development`, `other`

Responses

Code	Description	Schema
`201`	Created	APIEntitiesEnvironment
`400`	Bad request	—
`401`	Unauthorized	—
`404`	Not found	—

Schedule multiple stopped review apps for deletion

DELETE /api/v4/projects/{id}/environments/review_apps

Schedules multiple stopped review apps for deletion. The deletion is performed after 1 week. By default, only environments 30 days or older are deleted.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project owned by the authenticated user
`before` Query	String (date-time)	The date before which environments can be deleted. Defaults to 30 days ago. Expected in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`)
`limit` Query	Integer	Maximum number of environments to delete. Defaults to 100 Default: `100` Maximum: `1000` Minimum: `1`
`dry_run` Query	Boolean	Defaults to true for safety reasons. It performs a dry run where no actual deletion will be performed. Set to false to actually delete the environment Default: `true`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesEnvironmentBasic
`400`	Bad request	—
`401`	Unauthorized	—
`404`	Not found	—
`409`	Conflict	—

Stop stale environments

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

Stops all environments that were last modified or deployed to before a specified date. Excludes protected environments.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project owned by the authenticated user

Request body (application/json)

Property	Type	Description
`before` Required	String (date-time)	Stop all environments that were last modified or deployed to before this date

Responses

Code	Description	Schema
`201`	Created	—
`400`	Bad request	—
`401`	Unauthorized	—
`404`	Not Found	—

Retrieve an environment

GET /api/v4/projects/{id}/environments/{environment_id}

Retrieves a specified environment for a project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project owned by the authenticated user
`environment_id` Path, required	Integer	The ID of the environment

Responses

Code	Description	Schema
`200`	OK	APIEntitiesEnvironment
`400`	Bad Request	—
`401`	Unauthorized	—
`404`	Not found	—

Update an existing environment

PUT /api/v4/projects/{id}/environments/{environment_id}

Updates an existing environment for a project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project owned by the authenticated user
`environment_id` Path, required	Integer	The ID of the environment

Request body (application/json)

Property	Type	Description
`auto_stop_setting`	String	The auto stop setting for the environment. Allowed values are `always` and `with_action` Allowed values: `always`, `with_action`
`cluster_agent_id`	Integer	The ID of the Cluster Agent to associate with this environment
`description`	String	The description of the environment
`external_url`	String	The new URL on which this deployment is viewable
`flux_resource_path`	String	The Flux resource path to associate with this environment
`kubernetes_namespace`	String	The Kubernetes namespace to associate with this environment
`tier`	String	The tier of the new environment. Allowed values are `production`, `staging`, `testing`, `development`, and `other` Allowed values: `production`, `staging`, `testing`, `development`, `other`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesEnvironment
`400`	Bad request	—
`401`	Unauthorized	—
`404`	Not found	—

Delete an environment

DELETE /api/v4/projects/{id}/environments/{environment_id}

Deletes an environment from a project. The environment must be stopped first.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project owned by the authenticated user
`environment_id` Path, required	Integer	The ID of the environment

Responses

Code	Description	Schema
`200`	OK	APIEntitiesEnvironment
`400`	Bad Request	—
`401`	Unauthorized	—
`404`	Not found	—

Stop an environment

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

Stops a specified running environment.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project owned by the authenticated user
`environment_id` Path, required	Integer	The ID of the environment

Request body (application/json)

Property	Type	Description
`force`	Boolean	Force environment to stop without executing `on_stop` actions Default: `false`

Responses

Code	Description	Schema
`201`	Created	APIEntitiesEnvironment
`400`	Bad request	—
`401`	Unauthorized	—
`404`	Not found	—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesBasicProjectDetails

Property	Type	Description
`avatar_url`	String	Example: `http://example.com/uploads/project/avatar/3/uploads/avatar.png`
`created_at`	String (date-time)	Example: `2020-05-07T04:27:17.016Z`
`custom_attributes`	APIEntitiesCustomAttribute	—
`default_branch`	String	Example: `main`
`description`	String	Example: `desc`
`forks_count`	Integer	Example: `1`
`http_url_to_repo`	String	Example: `https://gitlab.example.com/gitlab/gitlab.git`
`id`	Integer (int64)	Example: `1`
`last_activity_at`	String (date-time)	Example: `2013-09-30T13:46:02Z`
`license`	APIEntitiesLicenseBasic	—
`license_url`	String	Example: `https://gitlab.example.com/gitlab/gitlab/blob/master/LICENCE`
`name`	String	Example: `project1`
`name_with_namespace`	String	Example: `John Doe / project1`
`namespace`	APIEntitiesNamespaceBasic	—
`path`	String	Example: `project1`
`path_with_namespace`	String	Example: `namespace1/project1`
`readme_url`	String	Example: `https://gitlab.example.com/gitlab/gitlab/blob/master/README.md`
`repository_storage`	String	Example: `default`
`ssh_url_to_repo`	String	Example: `git@gitlab.example.com:gitlab/gitlab.git`
`star_count`	Integer	Example: `1`
`tag_list`	Array of strings	Example: `["tag"]`
`topics`	Array of strings	Example: `["topic"]`
`visibility`	String	Example: `public`
`web_url`	String	Example: `https://gitlab.example.com/gitlab/gitlab`

APIEntitiesCiJob

Property	Type	Description
`allow_failure`	Boolean	—
`archived`	Boolean	Example: `false`
`artifacts`	Array of APIEntitiesCiJobArtifact	—
`artifacts_expire_at`	String (date-time)	Example: `2016-01-19T09:05:50.355Z`
`artifacts_file`	APIEntitiesCiJobArtifactFile	—
`commit`	APIEntitiesCommit	—
`coverage`	Number (float)	Example: `98.29`
`created_at`	String (date-time)	Example: `2015-12-24T15:51:21.880Z`
`duration`	Number (float)	Time spent running Example: `0.465`
`erased_at`	String (date-time)	Example: `2015-12-24T18:00:29.728Z`
`failure_reason`	String	Example: `script_failure`
`finished_at`	String (date-time)	Example: `2015-12-24T17:54:31.198Z`
`id`	Integer (int64)	Example: `1`
`name`	String	Example: `deploy_to_production`
`pipeline`	APIEntitiesCiPipelineBasic	—
`project`	Object	—
`project.ci_job_token_scope_enabled`	String	Example: `false`
`queued_duration`	Number (float)	Time spent enqueued Example: `0.123`
`ref`	String	Example: `main`
`runner`	APIEntitiesCiRunner	—
`runner_manager`	APIEntitiesCiRunnerManager	—
`stage`	String	Example: `deploy`
`started_at`	String (date-time)	Example: `2015-12-24T17:54:30.733Z`
`status`	String	Example: `waiting_for_resource`
`tag`	Boolean	—
`tag_list`	Array of strings	Example: `["ubuntu18","docker runner"]`
`user`	APIEntitiesUser	—
`web_url`	String	Example: `https://example.com/foo/bar/-/jobs/1`

APIEntitiesCiJobArtifact

Property	Type	Description
`file_format`	String	Allowed values: `raw`, `zip`, `gzip` Example: `zip`
`file_type`	String	Allowed values: `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` Example: `archive`
`filename`	String	Example: `artifacts.zip`
`size`	Integer	Example: `1000`

APIEntitiesCiJobArtifactFile

Property	Type	Description
`filename`	String	Example: `artifacts.zip`
`size`	Integer	Example: `1000`

APIEntitiesCiPipelineBasic

Property	Type	Description
`created_at`	String (date-time)	Example: `2022-10-21T16:49:48.000+02:00`
`id`	Integer (int64)	Example: `1`
`iid`	Integer	Example: `2`
`project_id`	Integer (int64)	Example: `3`
`ref`	String	Example: `feature-branch`
`sha`	String	Example: `0ec9e58fdfca6cdd6652c083c9edb53abc0bad52`
`source`	String	Example: `push`
`status`	String	Example: `success`
`updated_at`	String (date-time)	Example: `2022-10-21T16:49:48.000+02:00`
`web_url`	String	Example: `https://gitlab.example.com/gitlab-org/gitlab-foss/-/pipelines/61`

APIEntitiesCiRunner

Property	Type	Description
`active`	Boolean	Example: `true`
`created_at`	String (date-time)	Example: `2025-05-03T00:00:00.000Z`
`created_by`	APIEntitiesUserBasic	—
`description`	String	Example: `test-1-20150125`
`id`	Integer (int64)	Example: `8`
`ip_address`	String	Example: `127.0.0.1`
`is_shared`	Boolean	Example: `true`
`job_execution_status`	String	Allowed values: `active`, `idle` Example: `idle`
`name`	String	Example: `test`
`online`	Boolean	Example: `true`
`paused`	Boolean	Example: `false`
`runner_type`	String	Allowed values: `instance_type`, `group_type`, `project_type` Example: `instance_type`
`status`	String	Example: `online`

APIEntitiesCiRunnerManager

Property	Type	Description
`architecture`	String	Example: `amd64`
`contacted_at`	String	Example: `2023-10-24T01:27:06.549Z`
`created_at`	String	Example: `2023-10-24T01:27:06.549Z`
`id`	Integer (int64)	Example: `8`
`ip_address`	String	Example: `127.0.0.1`
`job_execution_status`	String	Allowed values: `active`, `idle` Example: `idle`
`platform`	String	Example: `linux`
`revision`	String	Example: `91a27b2a`
`status`	String	Example: `online`
`system_id`	String	Example: `runner-1`
`version`	String	Example: `16.11.0`

APIEntitiesClustersAgent

Property	Type	Description
`config_project`	APIEntitiesProjectIdentity	—
`created_at`	String (date-time)	—
`created_by_user_id`	Integer (int64)	Example: `1`
`id`	Integer (int64)	Example: `1`
`name`	String	—

APIEntitiesCommit

Property	Type	Description
`author_email`	String	Example: `john@example.com`
`author_name`	String	Example: `John Smith`
`authored_date`	String (date-time)	Example: `2012-05-28T04:42:42-07:00`
`committed_date`	String (date-time)	Example: `2012-05-28T04:42:42-07:00`
`committer_email`	String	Example: `jack@example.com`
`committer_name`	String	Example: `Jack Smith`
`created_at`	String (date-time)	Example: `2017-07-26T11:08:53.000+02:00`
`extended_trailers`	Object	Example: `{"Signed-off-by":["John Doe \u003cjohndoe@gitlab.com\u003e","Jane Doe \u003cjanedoe@gitlab.com\u003e"]}`
`id`	String	Example: `2695effb5807a22ff3d138d593fd856244e155e7`
`message`	String	Example: `Initial commit`
`parent_ids`	Array of strings	Example: `["2a4b78934375d7f53875269ffd4f45fd83a84ebe"]`
`short_id`	String	Example: `2695effb`
`title`	String	Example: `Initial commit`
`trailers`	Object	Example: `{"Merged-By":"Jane Doe janedoe@gitlab.com"}`
`web_url`	String	Example: `https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746`

APIEntitiesCustomAttribute

Property	Type	Description
`key`	String	Example: `foo`
`value`	String	Example: `bar`

APIEntitiesDeployment

Property	Type	Description
`created_at`	String (date-time)	Example: `2016-08-11T11:32:35.444Z`
`deployable`	APIEntitiesCiJob	—
`environment`	APIEntitiesEnvironmentBasic	—
`id`	Integer (int64)	Example: `41`
`iid`	Integer	Example: `1`
`ref`	String	Example: `main`
`sha`	String	Example: `99d03678b90d914dbb1b109132516d71a4a03ea8`
`status`	String	Example: `created`
`updated_at`	String (date-time)	Example: `2016-08-11T11:32:35.444Z`
`user`	APIEntitiesUserBasic	—

APIEntitiesEnvironment

Property	Type	Description
`auto_stop_at`	String (date-time)	Example: `2019-05-25T18:55:13.252Z`
`auto_stop_setting`	String	Example: `always`
`cluster_agent`	APIEntitiesClustersAgent	—
`created_at`	String (date-time)	Example: `2019-05-25T18:55:13.252Z`
`description`	String	Example: `description`
`external_url`	String	Example: `https://deploy.gitlab.example.com`
`flux_resource_path`	String	—
`id`	Integer (int64)	Example: `1`
`kubernetes_namespace`	String	—
`last_deployment`	APIEntitiesDeployment	—
`name`	String	Example: `deploy`
`project`	APIEntitiesBasicProjectDetails	—
`slug`	String	Example: `deploy`
`state`	String	Example: `available`
`tier`	String	Example: `development`
`updated_at`	String (date-time)	Example: `2019-05-25T18:55:13.252Z`

APIEntitiesEnvironmentBasic

Property	Type	Description
`created_at`	String (date-time)	Example: `2019-05-25T18:55:13.252Z`
`external_url`	String	Example: `https://deploy.gitlab.example.com`
`id`	Integer (int64)	Example: `1`
`name`	String	Example: `deploy`
`slug`	String	Example: `deploy`
`updated_at`	String (date-time)	Example: `2019-05-25T18:55:13.252Z`

APIEntitiesLicenseBasic

Property	Type	Description
`html_url`	String	Example: `http://choosealicense.com/licenses/gpl-3.0`
`key`	String	Example: `gpl-3.0`
`name`	String	Example: `GNU General Public License v3.0`
`nickname`	String	Example: `GNU GPLv3`
`source_url`	String	—

APIEntitiesNamespaceBasic

Property	Type	Description
`avatar_url`	String	Example: `https://example.com/avatar/12345`
`full_path`	String	Example: `group/my_project`
`id`	Integer (int64)	Example: `2`
`kind`	String	Example: `project`
`name`	String	Example: `project`
`parent_id`	Integer (int64)	Example: `1`
`path`	String	Example: `my_project`
`web_url`	String	Example: `https://example.com/group/my_project`

APIEntitiesProjectIdentity

Property	Type	Description
`created_at`	String (date-time)	Example: `2020-05-07T04:27:17.016Z`
`description`	String	Example: `desc`
`id`	Integer (int64)	Example: `1`
`name`	String	Example: `project1`
`name_with_namespace`	String	Example: `John Doe / project1`
`path`	String	Example: `project1`
`path_with_namespace`	String	Example: `namespace1/project1`

APIEntitiesUser

Property	Type	Description
`avatar_path`	String	Example: `/user/avatar/28/The-Big-Lebowski-400-400.png`
`avatar_url`	String	Example: `https://gravatar.com/avatar/1`
`bio`	String	—
`bot`	Boolean	—
`created_at`	String	—
`custom_attributes`	Array of APIEntitiesCustomAttribute	—
`discord`	String	—
`followers`	String	—
`following`	String	—
`github`	String	—
`id`	Integer (int64)	Example: `1`
`is_followed`	String	—
`job_title`	String	—
`linkedin`	String	—
`local_time`	String	—
`location`	String	—
`locked`	Boolean	—
`name`	String	Example: `Administrator`
`organization`	String	—
`pronouns`	String	—
`public_email`	String	Example: `john@example.com`
`state`	String	Example: `active`
`twitter`	String	—
`username`	String	Example: `admin`
`web_url`	String	Example: `https://gitlab.example.com/root`
`website_url`	String	—
`work_information`	String	—

APIEntitiesUserBasic

Property	Type	Description
`avatar_path`	String	Example: `/user/avatar/28/The-Big-Lebowski-400-400.png`
`avatar_url`	String	Example: `https://gravatar.com/avatar/1`
`custom_attributes`	Array of APIEntitiesCustomAttribute	—
`id`	Integer (int64)	Example: `1`
`locked`	Boolean	—
`name`	String	Example: `Administrator`
`public_email`	String	Example: `john@example.com`
`state`	String	Example: `active`
`username`	String	Example: `admin`
`web_url`	String	Example: `https://gitlab.example.com/root`

List all environments

Create an environment

Schedule multiple stopped review apps for deletion

Stop stale environments

Retrieve an environment

Update an existing environment

Delete an environment

Stop an environment

Schemas

APIEntitiesBasicProjectDetails

APIEntitiesCiJob

APIEntitiesCiJobArtifact

APIEntitiesCiJobArtifactFile

APIEntitiesCiPipelineBasic

APIEntitiesCiRunner

APIEntitiesCiRunnerManager

APIEntitiesClustersAgent

APIEntitiesCommit

APIEntitiesCustomAttribute

APIEntitiesDeployment

APIEntitiesEnvironment

APIEntitiesEnvironmentBasic

APIEntitiesLicenseBasic

APIEntitiesNamespaceBasic

APIEntitiesProjectIdentity

APIEntitiesUser

APIEntitiesUserBasic

Request trial access

Thank you

Error

Request callback

Thank you

Something went wrong

Book your sessions

Thank you

Error

Request demo

Thank you

Error

Get the PCI SSC Compliance Report

Thank you

Error