Operations related to environments
swagger: '2.0'
info:
title: GitLab access_requests environments API
version: v4
description: Operations related to access requests
host: gitlab.com
produces:
- application/json
tags:
- name: environments
description: Operations related to environments
paths:
/api/v4/projects/{id}/environments:
get:
summary: List environments
description: Get all environments for a given project. This feature was introduced in GitLab 8.11.
produces:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project owned by the authenticated user
type: string
required: true
- in: query
name: page
description: Current page number
type: integer
format: int32
default: 1
required: false
example: 1
- in: query
name: per_page
description: Number of items per page
type: integer
format: int32
default: 20
required: false
example: 20
- in: query
name: name
description: Return the environment with this name. Mutually exclusive with search
type: string
required: false
- in: query
name: search
description: Return list of environments matching the search criteria. Mutually exclusive with name. Must be at least 3 characters.
type: string
required: false
- in: query
name: states
description: 'List all environments that match a specific state. Accepted values: `available`, `stopping`, or `stopped`. If no state value given, returns all environments'
type: string
enum:
- stopped
- stopping
- available
required: false
responses:
'200':
description: List environments
schema:
type: array
items:
$ref: '#/definitions/API_Entities_Environment'
'401':
description: Unauthorized
'404':
description: Not found
tags:
- environments
operationId: getApiV4ProjectsIdEnvironments
post:
summary: Create a new environment
description: Creates a new environment with the given name and `external_url`. It returns `201` if the environment was successfully created, `400` for wrong parameters. This feature was introduced in GitLab 8.11.
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project owned by the authenticated user
type: string
required: true
- name: postApiV4ProjectsIdEnvironments
in: body
required: true
schema:
$ref: '#/definitions/postApiV4ProjectsIdEnvironments'
responses:
'201':
description: Create a new environment
schema:
$ref: '#/definitions/API_Entities_Environment'
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Not found
tags:
- environments
operationId: postApiV4ProjectsIdEnvironments
/api/v4/projects/{id}/environments/{environment_id}:
put:
summary: Update an existing environment
description: Updates an existing environment name and/or `external_url`. It returns `200` if the environment was successfully updated. In case of an error, a status code `400` is returned. This feature was introduced in GitLab 8.11.
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project owned by the authenticated user
type: string
required: true
- in: path
name: environment_id
description: The ID of the environment
type: integer
format: int32
required: true
- name: putApiV4ProjectsIdEnvironmentsEnvironmentId
in: body
required: true
schema:
$ref: '#/definitions/putApiV4ProjectsIdEnvironmentsEnvironmentId'
responses:
'200':
description: Update an existing environment
schema:
$ref: '#/definitions/API_Entities_Environment'
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Not found
tags:
- environments
operationId: putApiV4ProjectsIdEnvironmentsEnvironmentId
delete:
summary: Delete an environment
description: It returns 204 if the environment was successfully deleted, and 404 if the environment does not exist. This feature was introduced in GitLab 8.11.
produces:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project owned by the authenticated user
type: string
required: true
- in: path
name: environment_id
description: The ID of the environment
type: integer
format: int32
required: true
responses:
'401':
description: Unauthorized
'204':
description: Delete an environment
schema:
$ref: '#/definitions/API_Entities_Environment'
'404':
description: Not found
tags:
- environments
operationId: deleteApiV4ProjectsIdEnvironmentsEnvironmentId
get:
description: Get a specific environment
produces:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project owned by the authenticated user
type: string
required: true
- in: path
name: environment_id
description: The ID of the environment
type: integer
format: int32
required: true
responses:
'200':
description: Get a specific environment
schema:
$ref: '#/definitions/API_Entities_Environment'
'401':
description: Unauthorized
'404':
description: Not found
tags:
- environments
operationId: getApiV4ProjectsIdEnvironmentsEnvironmentId
/api/v4/projects/{id}/environments/review_apps:
delete:
summary: Delete multiple stopped review apps
description: It schedules for deletion multiple environments that have already been stopped and are in the review app folder. The actual deletion is performed after 1 week from the time of execution. By default, it only deletes environments 30 days or older. You can change this default using the `before` parameter.
produces:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project owned by the authenticated user
type: string
required: true
- in: query
name: before
description: The date before which environments can be deleted. Defaults to 30 days ago. Expected in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`)
type: string
format: date-time
default: {}
required: false
- in: query
name: limit
description: Maximum number of environments to delete. Defaults to 100
type: integer
format: int32
default: 100
minimum: 1
maximum: 1000
required: false
- in: query
name: dry_run
description: 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
type: boolean
default: true
required: false
responses:
'400':
description: Bad request
'204':
description: Delete multiple stopped review apps
schema:
$ref: '#/definitions/API_Entities_EnvironmentBasic'
'401':
description: Unauthorized
'404':
description: Not found
'409':
description: Conflict
tags:
- environments
operationId: deleteApiV4ProjectsIdEnvironmentsReviewApps
/api/v4/projects/{id}/environments/{environment_id}/stop:
post:
summary: Stop an environment
description: It returns 200 if the environment was successfully stopped.
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project owned by the authenticated user
type: string
required: true
- in: path
name: environment_id
description: The ID of the environment
type: integer
format: int32
required: true
- name: postApiV4ProjectsIdEnvironmentsEnvironmentIdStop
in: body
required: true
schema:
$ref: '#/definitions/postApiV4ProjectsIdEnvironmentsEnvironmentIdStop'
responses:
'201':
description: Stop an environment
schema:
$ref: '#/definitions/API_Entities_Environment'
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Not found
tags:
- environments
operationId: postApiV4ProjectsIdEnvironmentsEnvironmentIdStop
/api/v4/projects/{id}/environments/stop_stale:
post:
summary: Stop stale environments
description: It returns `200` if stale environment check was scheduled successfully
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project owned by the authenticated user
type: string
required: true
- name: postApiV4ProjectsIdEnvironmentsStopStale
in: body
required: true
schema:
$ref: '#/definitions/postApiV4ProjectsIdEnvironmentsStopStale'
responses:
'201':
description: Stop stale environments
'400':
description: Bad request
'401':
description: Unauthorized
tags:
- environments
operationId: postApiV4ProjectsIdEnvironmentsStopStale
definitions:
API_Entities_CustomAttribute:
type: object
properties:
key:
type: string
example: foo
value:
type: string
example: bar
required:
- key
- value
description: API_Entities_CustomAttribute model
API_Entities_Ci_Runner:
type: object
properties:
id:
type: integer
format: int32
example: 8
description:
type: string
example: test-1-20150125
ip_address:
type: string
example: 127.0.0.1
active:
type: boolean
example: true
paused:
type: boolean
example: false
is_shared:
type: boolean
example: true
runner_type:
type: string
enum:
- instance_type
- group_type
- project_type
example: instance_type
name:
type: string
example: test
online:
type: boolean
example: true
created_by:
$ref: '#/definitions/API_Entities_UserBasic'
created_at:
type: string
format: date-time
example: '2025-05-03T00:00:00.000Z'
status:
type: string
example: online
job_execution_status:
type: string
enum:
- active
- idle
example: idle
required:
- id
- description
- ip_address
- active
- paused
- is_shared
- runner_type
- name
- online
- created_at
- status
- job_execution_status
description: API_Entities_Ci_Runner model
API_Entities_Ci_RunnerManager:
type: object
properties:
id:
type: integer
format: int32
example: 8
system_id:
type: string
example: runner-1
version:
type: string
example: 16.11.0
revision:
type: string
example: 91a27b2a
platform:
type: string
example: linux
architecture:
type: string
example: amd64
created_at:
type: string
example: '2023-10-24T01:27:06.549Z'
contacted_at:
type: string
example: '2023-10-24T01:27:06.549Z'
ip_address:
type: string
example: 127.0.0.1
status:
type: string
example: online
job_execution_status:
type: string
enum:
- active
- idle
example: idle
required:
- id
- system_id
- version
- revision
- platform
- architecture
- created_at
- contacted_at
- ip_address
- status
- job_execution_status
description: API_Entities_Ci_RunnerManager model
API_Entities_UserBasic:
type: object
properties:
id:
type: integer
format: int32
example: 1
username:
type: string
example: admin
public_email:
type: string
example: john@example.com
name:
type: string
example: Administrator
state:
type: string
example: active
locked:
type: boolean
avatar_url:
type: string
example: https://gravatar.com/avatar/1
avatar_path:
type: string
example: /user/avatar/28/The-Big-Lebowski-400-400.png
custom_attributes:
type: array
items:
$ref: '#/definitions/API_Entities_CustomAttribute'
web_url:
type: string
example: https://gitlab.example.com/root
required:
- id
- username
- public_email
- name
- state
- locked
- avatar_url
- web_url
description: API_Entities_UserBasic model
postApiV4ProjectsIdEnvironmentsStopStale:
type: object
properties:
before:
type: string
format: date-time
description: Stop all environments that were last modified or deployed to before this date.
required:
- before
description: Stop stale environments
API_Entities_ProjectIdentity:
type: object
properties:
id:
type: integer
format: int32
example: 1
description:
type: string
example: desc
name:
type: string
example: project1
name_with_namespace:
type: string
example: John Doe / project1
path:
type: string
example: project1
path_with_namespace:
type: string
example: namespace1/project1
created_at:
type: string
format: date-time
example: '2020-05-07T04:27:17.016Z'
required:
- id
- description
- name
- name_with_namespace
- path
- path_with_namespace
- created_at
API_Entities_User:
type: object
properties:
id:
type: integer
format: int32
example: 1
username:
type: string
example: admin
public_email:
type: string
example: john@example.com
name:
type: string
example: Administrator
state:
type: string
example: active
locked:
type: boolean
avatar_url:
type: string
example: https://gravatar.com/avatar/1
avatar_path:
type: string
example: /user/avatar/28/The-Big-Lebowski-400-400.png
custom_attributes:
type: array
items:
$ref: '#/definitions/API_Entities_CustomAttribute'
web_url:
type: string
example: https://gitlab.example.com/root
created_at:
type: string
bio:
type: string
location:
type: string
linkedin:
type: string
twitter:
type: string
discord:
type: string
website_url:
type: string
github:
type: string
job_title:
type: string
pronouns:
type: string
organization:
type: string
bot:
type: boolean
work_information:
type: string
followers:
type: string
following:
type: string
is_followed:
type: string
local_time:
type: string
required:
- id
- username
- public_email
- name
- state
- locked
- avatar_url
- web_url
- bio
- location
- linkedin
- twitter
- discord
- website_url
- github
- job_title
- pronouns
- organization
- bot
- work_information
- local_time
API_Entities_Environment:
type: object
properties:
id:
type: integer
format: int32
example: 1
name:
type: string
example: deploy
slug:
type: string
example: deploy
external_url:
type: string
example: https://deploy.gitlab.example.com
created_at:
type: string
format: date-time
example: '2019-05-25T18:55:13.252Z'
updated_at:
type: string
format: date-time
example: '2019-05-25T18:55:13.252Z'
tier:
type: string
example: development
project:
$ref: '#/definitions/API_Entities_BasicProjectDetails'
last_deployment:
$ref: '#/definitions/API_Entities_Deployment'
state:
type: string
example: available
auto_stop_at:
type: string
format: date-time
example: '2019-05-25T18:55:13.252Z'
cluster_agent:
$ref: '#/definitions/API_Entities_Clusters_Agent'
kubernetes_namespace:
type: string
flux_resource_path:
type: string
description:
type: string
example: description
auto_stop_setting:
type: string
example: always
required:
- id
- name
- slug
- external_url
- created_at
- updated_at
- tier
- project
- state
- auto_stop_at
- description
- auto_stop_setting
description: API_Entities_Environment model
postApiV4ProjectsIdEnvironmentsEnvironmentIdStop:
type: object
properties:
force:
type: boolean
description: Force environment to stop without executing `on_stop` actions
default: false
description: Stop an environment
API_Entities_Ci_PipelineBasic:
type: object
properties:
id:
type: integer
format: int32
example: 1
iid:
type: integer
format: int32
example: 2
project_id:
type: integer
format: int32
example: 3
sha:
type: string
example: 0ec9e58fdfca6cdd6652c083c9edb53abc0bad52
ref:
type: string
example: feature-branch
status:
type: string
example: success
source:
type: string
example: push
created_at:
type: string
format: date-time
example: '2022-10-21T16:49:48.000+02:00'
updated_at:
type: string
format: date-time
example: '2022-10-21T16:49:48.000+02:00'
web_url:
type: string
example: https://gitlab.example.com/gitlab-org/gitlab-foss/-/pipelines/61
required:
- id
- iid
- project_id
- sha
- ref
- status
- source
- created_at
- updated_at
- web_url
description: API_Entities_Ci_PipelineBasic model
API_Entities_Ci_JobArtifact:
type: object
properties:
file_type:
type: string
enum:
- 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
- scip
- sarif
- environment_key
example: archive
size:
type: integer
format: int32
example: 1000
filename:
type: string
example: artifacts.zip
file_format:
type: string
enum:
- raw
- zip
- gzip
example: zip
required:
- file_type
- size
- filename
- file_format
API_Entities_Commit:
type: object
properties:
id:
type: string
example: 2695effb5807a22ff3d138d593fd856244e155e7
short_id:
type: string
example: 2695effb
created_at:
type: string
format: date-time
example: '2017-07-26T11:08:53.000+02:00'
parent_ids:
type: array
items:
type: string
example:
- 2a4b78934375d7f53875269ffd4f45fd83a84ebe
title:
type: string
example: Initial commit
message:
type: string
example: Initial commit
author_name:
type: string
example: John Smith
author_email:
type: string
example: john@example.com
authored_date:
type: string
format: date-time
example: '2012-05-28T04:42:42-07:00'
committer_name:
type: string
example: Jack Smith
committer_email:
type: string
example: jack@example.com
committed_date:
type: string
format: date-time
example: '2012-05-28T04:42:42-07:00'
trailers:
type: object
example:
Merged-By: Jane Doe janedoe@gitlab.com
extended_trailers:
type: object
example:
Signed-off-by:
- John Doe <johndoe@gitlab.com>
- Jane Doe <janedoe@gitlab.com>
web_url:
type: string
example: https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746
required:
- id
- short_id
- created_at
- parent_ids
- title
- message
- author_name
- author_email
- authored_date
- committer_name
- committer_email
- committed_date
- trailers
- extended_trailers
- web_url
description: API_Entities_Commit model
API_Entities_EnvironmentBasic:
type: object
properties:
id:
type: integer
format: int32
example: 1
name:
type: string
example: deploy
slug:
type: string
example: deploy
external_url:
type: string
example: https://deploy.gitlab.example.com
created_at:
type: string
format: date-time
example: '2019-05-25T18:55:13.252Z'
updated_at:
type: string
format: date-time
example: '2019-05-25T18:55:13.252Z'
required:
- id
- name
- slug
- external_url
- created_at
- updated_at
description: API_Entities_EnvironmentBasic model
postApiV4ProjectsIdEnvironments:
type: object
properties:
name:
type: string
description: The name of the environment
external_url:
type: string
description: Place to link to for this environment
tier:
type: string
description: The tier of the new environment. Allowed values are `production`, `staging`, `testing`, `development`, and `other`
enum:
- production
- staging
- testing
- development
- other
cluster_agent_id:
type: integer
format: int32
description: The ID of the Cluster Agent to associate with this environment
kubernetes_namespace:
type: string
description: The Kubernetes namespace to associate with this environment
flux_resource_path:
type: string
description: The Flux resource path to associate with this environment
description:
type: string
description: The description of the environment
auto_stop_setting:
type: string
description: The auto stop setting for the environment. Allowed values are `always` and `with_action`
enum:
- always
- with_action
required:
- name
description: Create a new environment
API_Entities_NamespaceBasic:
type: object
properties:
id:
type: integer
format: int32
example: 2
name:
type: string
example: project
path:
type: string
example: my_project
kind:
type: string
example: project
full_path:
type: string
example: group/my_project
parent_id:
type: integer
format: int32
example: 1
avatar_url:
type: string
example: https://example.com/avatar/12345
web_url:
type: string
example: https://example.com/group/my_project
required:
- id
- name
- path
- kind
- full_path
- parent_id
- avatar_url
- web_url
API_Entities_BasicProjectDetails:
type: object
properties:
id:
type: integer
format: int32
example: 1
description:
type: string
example: desc
name:
type: string
example: project1
name_with_namespace:
type: string
example: John Doe / project1
path:
type: string
example: project1
path_with_namespace:
type: string
example: namespace1/project1
created_at:
type: string
format: date-time
example: '2020-05-07T04:27:17.016Z'
default_branch:
type: string
example: main
tag_list:
type: array
items:
type: string
example:
- tag
topics:
type: array
items:
type: string
example:
- topic
ssh_url_to_repo:
type: string
example: git@gitlab.example.com:gitlab/gitlab.git
http_url_to_repo:
type: string
example: https://gitlab.example.com/gitlab/gitlab.git
web_url:
type: string
example: https://gitlab.example.com/gitlab/gitlab
readme_url:
type: string
example: https://gitlab.example.com/gitlab/gitlab/blob/master/README.md
forks_count:
type: integer
format: int32
example: 1
license_url:
type: string
example: https://gitlab.example.com/gitlab/gitlab/blob/master/LICENCE
license:
$ref: '#/definitions/API_Entities_LicenseBasic'
avatar_url:
type: string
example: http://example.com/uploads/project/avatar/3/uploads/avatar.png
star_count:
type: integer
format: int32
example: 1
last_activity_at:
type: string
format: date-time
example: '2013-09-30T13:46:02Z'
visibility:
type: string
example: public
namespace:
$ref: '#/definitions/API_Entities_NamespaceBasic'
custom_attributes:
$ref: '#/definitions/API_Entities_CustomAttribute'
repository_storage:
type: string
example: default
required:
- id
- description
- name
- name_with_namespace
- path
- path_with_namespace
- created_at
- tag_list
- topics
- ssh_url_to_repo
- http_url_to_repo
- web_url
- avatar_url
- star_count
- last_activity_at
- visibility
- namespace
description: API_Entities_BasicProjectDetails model
putApiV4ProjectsIdEnvironmentsEnvironmentId:
type: object
properties:
external_url:
type: string
description: The new URL on which this deployment is viewable
tier:
type: string
description: The tier of the new environment. Allowed values are `production`, `staging`, `testing`, `development`, and `other`
enum:
- production
- staging
- testing
- development
- other
cluster_agent_id:
type: integer
format: int32
description: The ID of the Cluster Agent to associate with this environment
kubernetes_namespace:
type: string
description: The Kubernetes namespace to associate with this environment
flux_resource_path:
type: string
description: The Flux resource path to associate with this environment
description:
type: string
description: The description of the environment
auto_stop_setting:
type: string
description: The auto stop setting for the environment. Allowed values are `always` and `with_action`
enum:
- always
- with_action
description: Update an existing environment
API_Entities_Clusters_Agent:
type: object
properties:
id:
type: string
name:
type: string
config_project:
$ref: '#/definitions/API_Entities_ProjectIdentity'
created_at:
type: string
created_by_user_id:
type: string
is_receptive:
type: string
required:
- id
- name
- config_project
- created_at
- created_by_user_id
- is_receptive
description: API_Entities_Clusters_Agent model
API_Entities_Deployment:
type: object
properties:
id:
type: integer
format: int32
example: 41
iid:
type: integer
format: int32
example: 1
ref:
type: string
example: main
sha:
type: string
example: 99d03678b90d914dbb1b109132516d71a4a03ea8
created_at:
type: string
format: date-time
example: '2016-08-11T11:32:35.444Z'
updated_at:
type: string
format: date-time
example: '2016-08-11T11:32:35.444Z'
user:
$ref: '#/definitions/API_Entities_UserBasic'
environment:
$ref: '#/definitions/API_Entities_EnvironmentBasic'
deployable:
$ref: '#/definitions/API_Entities_Ci_Job'
status:
type: string
example: created
required:
- id
- iid
- ref
- sha
- created_at
- updated_at
- user
- environment
- deployable
- status
description: API_Entities_Deployment model
API_Entities_Ci_Job:
type: object
properties:
id:
type: integer
format: int32
example: 1
status:
type: string
example: waiting_for_resource
stage:
type: string
example: deploy
name:
type: string
example: deploy_to_production
ref:
type: string
example: main
tag:
type: boolean
coverage:
type: number
format: float
example: 98.29
allow_failure:
type: boolean
created_at:
type: string
format: date-time
example: '2015-12-24T15:51:21.880Z'
started_at:
type: string
format: date-time
example: '2015-12-24T17:54:30.733Z'
finished_at:
type: string
format: date-time
example: '2015-12-24T17:54:31.198Z'
erased_at:
type: string
format: date-time
example: '2015-12-24T18:00:29.728Z'
duration:
type: number
format: float
example: 0.465
description: Time spent running
queued_duration:
type: number
format: float
example: 0.123
description: Time spent enqueued
user:
$ref: '#/definitions/API_Entities_User'
commit:
$ref: '#/definitions/API_Entities_Commit'
pipeline:
$ref: '#/definitions/API_Entities_Ci_PipelineBasic'
failure_reason:
type: string
example: script_failure
web_url:
type: string
example: https://example.com/foo/bar/-/jobs/1
project:
type: object
properties:
ci_job_token_scope_enabled:
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/gitlab-ci/refs/heads/main/openapi/gitlab-ci-environments-api-openapi.yml