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	ID or URL-encoded path of the project
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list 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	Filter environments by state. If omitted, returns all environments Allowed values: `stopped`, `stopping`, `available`

Responses

Code	Description	Schema
`200`	OK	Array of 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	ID or URL-encoded path of the project

Request body (application/json)

Property	Type	Description
`auto_stop_setting`	String	Auto stop setting for the environment Allowed values: `always`, `with_action`
`cluster_agent_id`	Integer	ID of the cluster agent to associate with the environment. When updating an environment, set to `null` to remove it
`description`	String	Description of the environment
`external_url`	String	URL to link to for the environment
`flux_resource_path`	String	Flux resource path to associate with the environment, for example `helm.toolkit.fluxcd.io/v2/namespaces/gitlab-agent/helmreleases/gitlab-agent`. When updating an environment, set to `null` to remove it
`kubernetes_namespace`	String	Kubernetes namespace to associate with the environment. When updating an environment, set to `null` to remove it
`name` Required	String	Name of the environment
`tier`	String	Tier of the environment 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	ID or URL-encoded path of the project
`before` Query	String (date-time)	Date before which environments can be deleted. Defaults to 30 days ago
`limit` Query	Integer	Maximum number of environments to delete Default: `100` Maximum: `1000` Minimum: `1`
`dry_run` Query	Boolean	If `true`, performs a dry run where no deletion is actually performed. If `false`, deletes 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	ID or URL-encoded path of the project

Request body (application/json)

Property	Type	Description
`before` Required	String (date-time)	Stop environments that were modified or deployed to before the specified date. Valid inputs are between 10 years ago and 1 week ago

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	ID or URL-encoded path of the project
`environment_id` Path, required	Integer	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	ID or URL-encoded path of the project
`environment_id` Path, required	Integer	ID of the environment

Request body (application/json)

Property	Type	Description
`auto_stop_setting`	String	Auto stop setting for the environment Allowed values: `always`, `with_action`
`cluster_agent_id`	Integer	ID of the cluster agent to associate with the environment. When updating an environment, set to `null` to remove it
`description`	String	Description of the environment
`external_url`	String	New URL to link to for the environment
`flux_resource_path`	String	Flux resource path to associate with the environment, for example `helm.toolkit.fluxcd.io/v2/namespaces/gitlab-agent/helmreleases/gitlab-agent`. When updating an environment, set to `null` to remove it
`kubernetes_namespace`	String	Kubernetes namespace to associate with the environment. When updating an environment, set to `null` to remove it
`tier`	String	Tier of the environment 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	ID or URL-encoded path of the project
`environment_id` Path, required	Integer	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	ID or URL-encoded path of the project
`environment_id` Path, required	Integer	ID of the environment

Request body (application/json)

Property	Type	Description
`force`	Boolean	If `true`, stops the environment 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

Request partner program details

Request received

Error