2018-09-29 22:34:47 +00:00
# frozen_string_literal: true
2016-08-16 06:45:23 +00:00
module API
2017-03-06 17:19:15 +00:00
# Deployments RESTful API endpoints
2020-10-15 00:08:42 +00:00
class Deployments < :: API :: Base
2016-11-21 19:15:46 +00:00
include PaginationParams
2016-08-16 06:45:23 +00:00
before { authenticate! }
2020-10-29 12:08:50 +00:00
feature_category :continuous_delivery
2022-04-29 12:10:13 +00:00
urgency :low
2020-10-29 12:08:50 +00:00
2016-08-16 06:45:23 +00:00
params do
2022-10-27 15:09:49 +00:00
requires :id , types : [ String , Integer ] , desc : 'The ID or URL-encoded path of the project owned by the authenticated user'
2016-08-16 06:45:23 +00:00
end
2018-11-08 12:18:17 +00:00
resource :projects , requirements : API :: NAMESPACE_OR_PROJECT_REQUIREMENTS do
2022-10-27 15:09:49 +00:00
desc 'List project deployments' do
detail 'Get a list of deployments in a project. This feature was introduced in GitLab 8.11.'
2016-08-16 06:45:23 +00:00
success Entities :: Deployment
2022-10-27 15:09:49 +00:00
is_array true
tags %w[ deployments ]
2016-08-16 06:45:23 +00:00
end
params do
2016-11-21 19:15:46 +00:00
use :pagination
2022-10-27 15:09:49 +00:00
optional :order_by ,
type : String ,
values : DeploymentsFinder :: ALLOWED_SORT_VALUES ,
default : DeploymentsFinder :: DEFAULT_SORT_VALUE ,
desc : 'Return deployments ordered by either one of `id`, `iid`, `created_at`, `updated_at` or `ref` fields. Default is `id`'
optional :sort ,
type : String ,
values : DeploymentsFinder :: ALLOWED_SORT_DIRECTIONS ,
default : DeploymentsFinder :: DEFAULT_SORT_DIRECTION ,
desc : 'Return deployments sorted in `asc` or `desc` order. Default is `asc`'
optional :updated_after ,
type : DateTime ,
desc : 'Return deployments updated after the specified date. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`)'
optional :updated_before ,
type : DateTime ,
desc : 'Return deployments updated before the specified date. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`)'
2020-01-17 21:08:29 +00:00
optional :environment ,
type : String ,
desc : 'The name of the environment to filter deployments by'
optional :status ,
type : String ,
values : Deployment . statuses . keys ,
2022-10-27 15:09:49 +00:00
desc : 'The status to filter deployments by. One of `created`, `running`, `success`, `failed`, `canceled`, or `blocked`'
2016-08-16 06:45:23 +00:00
end
2019-11-28 03:06:32 +00:00
2016-08-16 06:45:23 +00:00
get ':id/deployments' do
authorize! :read_deployment , user_project
2021-03-29 12:09:14 +00:00
deployments =
DeploymentsFinder . new ( params . merge ( project : user_project ) )
. execute . with_api_entity_associations
2019-11-28 03:06:32 +00:00
present paginate ( deployments ) , with : Entities :: Deployment
2021-05-06 06:10:11 +00:00
rescue DeploymentsFinder :: InefficientQueryError = > e
bad_request! ( e . message )
2016-08-16 06:45:23 +00:00
end
2022-10-27 15:09:49 +00:00
desc 'Get a specific deployment' do
2016-08-16 06:45:23 +00:00
detail 'This feature was introduced in GitLab 8.11.'
2022-02-02 06:16:52 +00:00
success Entities :: DeploymentExtended
2022-10-27 15:09:49 +00:00
tags %w[ deployments ]
2016-08-16 06:45:23 +00:00
end
params do
2022-10-27 15:09:49 +00:00
requires :deployment_id , type : Integer , desc : 'The ID of the deployment'
2016-08-16 06:45:23 +00:00
end
get ':id/deployments/:deployment_id' do
authorize! :read_deployment , user_project
deployment = user_project . deployments . find ( params [ :deployment_id ] )
2022-02-02 06:16:52 +00:00
present deployment , with : Entities :: DeploymentExtended
2016-08-16 06:45:23 +00:00
end
2019-10-16 18:08:01 +00:00
2022-10-27 15:09:49 +00:00
desc 'Create a deployment' do
detail 'This feature was introduced in GitLab 12.4.'
2022-02-02 06:16:52 +00:00
success Entities :: DeploymentExtended
2022-10-27 15:09:49 +00:00
tags %w[ deployments ]
2019-10-16 18:08:01 +00:00
end
params do
requires :environment ,
type : String ,
2022-10-27 15:09:49 +00:00
desc : 'The name of the environment to create the deployment for'
2019-10-16 18:08:01 +00:00
requires :sha ,
type : String ,
2022-10-27 15:09:49 +00:00
desc : 'The SHA of the commit that is deployed'
2019-10-16 18:08:01 +00:00
requires :ref ,
type : String ,
2022-10-27 15:09:49 +00:00
desc : 'The name of the branch or tag that is deployed'
2019-10-16 18:08:01 +00:00
requires :tag ,
type : Boolean ,
2022-10-27 15:09:49 +00:00
desc : 'A boolean that indicates if the deployed ref is a tag (`true`) or not (`false`)'
2019-10-16 18:08:01 +00:00
requires :status ,
type : String ,
2022-10-27 15:09:49 +00:00
desc : 'The status to filter deployments by. One of `running`, `success`, `failed`, or `canceled`' ,
2019-10-16 18:08:01 +00:00
values : %w[ running success failed canceled ]
end
post ':id/deployments' do
authorize! ( :create_deployment , user_project )
authorize! ( :create_environment , user_project )
environment = user_project
. environments
. find_or_create_by_name ( params [ :environment ] )
unless environment . persisted?
render_validation_error! ( deployment )
end
authorize! ( :create_deployment , environment )
service = :: Deployments :: CreateService
. new ( environment , current_user , declared_params )
deployment = service . execute
if deployment . persisted?
2022-02-02 06:16:52 +00:00
present ( deployment , with : Entities :: DeploymentExtended , current_user : current_user )
2019-10-16 18:08:01 +00:00
else
render_validation_error! ( deployment )
end
end
2022-10-27 15:09:49 +00:00
desc 'Update a deployment' do
detail 'This feature was introduced in GitLab 12.4.'
2022-02-02 06:16:52 +00:00
success Entities :: DeploymentExtended
2022-10-27 15:09:49 +00:00
tags %w[ deployments ]
2019-10-16 18:08:01 +00:00
end
params do
requires :status ,
2022-07-26 06:11:51 +00:00
type : String ,
2022-10-27 15:09:49 +00:00
desc : 'The new status of the deployment. One of `running`, `success`, `failed`, or `canceled`' ,
2022-07-26 06:11:51 +00:00
values : %w[ running success failed canceled ]
2019-10-16 18:08:01 +00:00
end
put ':id/deployments/:deployment_id' do
authorize! ( :read_deployment , user_project )
deployment = user_project . deployments . find ( params [ :deployment_id ] )
authorize! ( :update_deployment , deployment )
if deployment . deployable
forbidden! ( 'Deployments created using GitLab CI can not be updated using the API' )
end
service = :: Deployments :: UpdateService . new ( deployment , declared_params )
if service . execute
2022-02-02 06:16:52 +00:00
present ( deployment , with : Entities :: DeploymentExtended , current_user : current_user )
2019-10-16 18:08:01 +00:00
else
render_validation_error! ( deployment )
end
end
2020-01-13 21:07:39 +00:00
2022-10-27 15:09:49 +00:00
desc 'Delete a specific deployment' do
detail 'Delete a specific deployment that is not currently the last deployment for an environment or in a running state. This feature was introduced in GitLab 15.3.'
http_codes [
[ 204 , 'Deployment destroyed' ] ,
[ 403 , 'Forbidden' ] ,
[ 400 , '"Cannot destroy running deployment" or "Deployment currently deployed to environment"' ]
]
tags %w[ deployments ]
2022-07-26 06:11:51 +00:00
end
params do
2022-10-27 15:09:49 +00:00
requires :deployment_id , type : Integer , desc : 'The ID of the deployment'
2022-07-26 06:11:51 +00:00
end
delete ':id/deployments/:deployment_id' do
deployment = user_project . deployments . find ( params [ :deployment_id ] )
authorize! ( :destroy_deployment , deployment )
destroy_conditionally! ( deployment ) do
2022-08-11 00:09:45 +00:00
result = :: Ci :: Deployments :: DestroyService . new ( user_project , current_user ) . execute ( deployment )
if result [ :status ] == :error
render_api_error! ( result [ :message ] , result [ :http_status ] || 400 )
end
2022-07-26 06:11:51 +00:00
end
end
2020-01-13 21:07:39 +00:00
helpers Helpers :: MergeRequestsHelpers
2022-10-27 15:09:49 +00:00
desc 'List of merge requests associated with a deployment' do
detail 'Retrieves the list of merge requests shipped with a given deployment. This feature was introduced in GitLab 12.7.'
2020-01-13 21:07:39 +00:00
success Entities :: MergeRequestBasic
2022-10-27 15:09:49 +00:00
tags %w[ deployments ]
2020-01-13 21:07:39 +00:00
end
params do
2020-02-25 00:09:12 +00:00
use :pagination
2022-10-27 15:09:49 +00:00
requires :deployment_id , type : Integer , desc : 'The ID of the deployment'
2020-01-13 21:07:39 +00:00
use :merge_requests_base_params
end
get ':id/deployments/:deployment_id/merge_requests' do
authorize! :read_deployment , user_project
mr_params = declared_params . merge ( deployment_id : params [ :deployment_id ] )
merge_requests = MergeRequestsFinder . new ( current_user , mr_params ) . execute
2020-02-25 00:09:12 +00:00
present paginate ( merge_requests ) , { with : Entities :: MergeRequestBasic , current_user : current_user }
2020-01-13 21:07:39 +00:00
end
2016-08-16 06:45:23 +00:00
end
end
end
2022-01-06 06:10:35 +00:00
API :: Deployments . prepend_mod