Welcome to mirror list, hosted at ThFree Co, Russian Federation.

gitlab.com/gitlab-org/gitlab-foss.git - Unnamed repository; edit this file 'description' to name the repository.
summaryrefslogtreecommitdiff
path: root/lib/api/deployments.rb
diff options
context:
space:
mode:
Diffstat (limited to 'lib/api/deployments.rb')
-rw-r--r--lib/api/deployments.rb113
1 files changed, 85 insertions, 28 deletions
diff --git a/lib/api/deployments.rb b/lib/api/deployments.rb
index ee0a026d7ac..141f089b5e1 100644
--- a/lib/api/deployments.rb
+++ b/lib/api/deployments.rb
@@ -5,25 +5,51 @@ module API
class Deployments < ::API::Base
include PaginationParams
+ deployments_tags = %w[deployments]
+
before { authenticate! }
feature_category :continuous_delivery
urgency :low
params do
- requires :id, type: String, desc: 'The project ID'
+ requires :id, types: [String, Integer], desc: 'The ID or URL-encoded path of the project owned by the authenticated user'
end
resource :projects, requirements: API::NAMESPACE_OR_PROJECT_REQUIREMENTS do
- desc 'Get all deployments of the project' do
- detail 'This feature was introduced in GitLab 8.11.'
+ desc 'List project deployments' do
+ detail 'Get a list of deployments in a project. This feature was introduced in GitLab 8.11.'
success Entities::Deployment
+ failure [
+ { code: 400, message: 'Bad request' },
+ { code: 401, message: 'Unauthorized' },
+ { code: 404, message: 'Not found' }
+ ]
+ is_array true
+ tags deployments_tags
end
params do
use :pagination
- optional :order_by, type: String, values: DeploymentsFinder::ALLOWED_SORT_VALUES, default: DeploymentsFinder::DEFAULT_SORT_VALUE, desc: 'Return deployments ordered by specified value'
- optional :sort, type: String, values: DeploymentsFinder::ALLOWED_SORT_DIRECTIONS, default: DeploymentsFinder::DEFAULT_SORT_DIRECTION, desc: 'Sort by asc (ascending) or desc (descending)'
- optional :updated_after, type: DateTime, desc: 'Return deployments updated after the specified date'
- optional :updated_before, type: DateTime, desc: 'Return deployments updated before the specified date'
+
+ 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`)'
+
optional :environment,
type: String,
desc: 'The name of the environment to filter deployments by'
@@ -31,7 +57,7 @@ module API
optional :status,
type: String,
values: Deployment.statuses.keys,
- desc: 'The status to filter deployments by'
+ desc: 'The status to filter deployments by. One of `created`, `running`, `success`, `failed`, `canceled`, or `blocked`'
end
get ':id/deployments' do
@@ -46,12 +72,17 @@ module API
bad_request!(e.message)
end
- desc 'Gets a specific deployment' do
+ desc 'Get a specific deployment' do
detail 'This feature was introduced in GitLab 8.11.'
success Entities::DeploymentExtended
+ failure [
+ { code: 401, message: 'Unauthorized' },
+ { code: 404, message: 'Not found' }
+ ]
+ tags deployments_tags
end
params do
- requires :deployment_id, type: Integer, desc: 'The deployment ID'
+ requires :deployment_id, type: Integer, desc: 'The ID of the deployment'
end
get ':id/deployments/:deployment_id' do
authorize! :read_deployment, user_project
@@ -61,30 +92,36 @@ module API
present deployment, with: Entities::DeploymentExtended
end
- desc 'Creates a new deployment' do
- detail 'This feature was introduced in GitLab 12.4'
+ desc 'Create a deployment' do
+ detail 'This feature was introduced in GitLab 12.4.'
success Entities::DeploymentExtended
+ failure [
+ { code: 400, message: 'Bad request' },
+ { code: 401, message: 'Unauthorized' },
+ { code: 404, message: 'Not found' }
+ ]
+ tags deployments_tags
end
params do
requires :environment,
type: String,
- desc: 'The name of the environment to deploy to'
+ desc: 'The name of the environment to create the deployment for'
requires :sha,
type: String,
- desc: 'The SHA of the commit that was deployed'
+ desc: 'The SHA of the commit that is deployed'
requires :ref,
type: String,
- desc: 'The name of the branch or tag that was deployed'
+ desc: 'The name of the branch or tag that is deployed'
requires :tag,
type: Boolean,
- desc: 'A boolean indicating if the deployment ran for a tag'
+ desc: 'A boolean that indicates if the deployed ref is a tag (`true`) or not (`false`)'
requires :status,
type: String,
- desc: 'The status of the deployment',
+ desc: 'The status to filter deployments by. One of `running`, `success`, `failed`, or `canceled`',
values: %w[running success failed canceled]
end
post ':id/deployments' do
@@ -96,7 +133,7 @@ module API
.find_or_create_by_name(params[:environment])
unless environment.persisted?
- render_validation_error!(deployment)
+ render_validation_error!(environment)
end
authorize!(:create_deployment, environment)
@@ -113,14 +150,21 @@ module API
end
end
- desc 'Updates an existing deployment' do
- detail 'This feature was introduced in GitLab 12.4'
+ desc 'Update a deployment' do
+ detail 'This feature was introduced in GitLab 12.4.'
success Entities::DeploymentExtended
+ failure [
+ { code: 400, message: 'Bad request' },
+ { code: 401, message: 'Unauthorized' },
+ { code: 403, message: 'Forbidden' },
+ { code: 404, message: 'Not found' }
+ ]
+ tags deployments_tags
end
params do
requires :status,
type: String,
- desc: 'The new status of the deployment',
+ desc: 'The new status of the deployment. One of `running`, `success`, `failed`, or `canceled`',
values: %w[running success failed canceled]
end
put ':id/deployments/:deployment_id' do
@@ -143,12 +187,17 @@ module API
end
end
- desc 'Deletes an existing deployment' do
- detail 'This feature was introduced in GitLab 15.3'
- http_codes [[204, 'Deployment was deleted'], [403, 'Forbidden'], [400, 'Cannot destroy']]
+ 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 deployments_tags
end
params do
- requires :deployment_id, type: Integer, desc: 'The deployment ID'
+ requires :deployment_id, type: Integer, desc: 'The ID of the deployment'
end
delete ':id/deployments/:deployment_id' do
deployment = user_project.deployments.find(params[:deployment_id])
@@ -166,13 +215,21 @@ module API
helpers Helpers::MergeRequestsHelpers
- desc 'Get all merge requests of a deployment' do
- detail 'This feature was introduced in GitLab 12.7.'
+ 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.'
success Entities::MergeRequestBasic
+ failure [
+ { code: 401, message: 'Unauthorized' },
+ { code: 404, message: 'Not found' }
+ ]
+ is_array true
+ tags deployments_tags
end
params do
use :pagination
- requires :deployment_id, type: Integer, desc: 'The deployment ID'
+
+ requires :deployment_id, type: Integer, desc: 'The ID of the deployment'
+
use :merge_requests_base_params
end
generated by cgit v1.2.3 (git 2.25.1) at 2024-08-16 14:32:46 +0300