1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
|
# frozen_string_literal: true
module API
class Releases < ::API::Base
include PaginationParams
RELEASE_ENDPOINT_REQUIREMENTS = API::NAMESPACE_OR_PROJECT_REQUIREMENTS
.merge(tag_name: API::NO_SLASH_URL_PART_REGEX)
RELEASE_CLI_USER_AGENT = 'GitLab-release-cli'
before { authorize_read_releases! }
after { track_release_event }
feature_category :release_orchestration
params do
requires :id, type: String, desc: 'The ID of a project'
end
resource :projects, requirements: API::NAMESPACE_OR_PROJECT_REQUIREMENTS do
desc 'Get a project releases' do
detail 'This feature was introduced in GitLab 11.7.'
named 'get_releases'
success Entities::Release
end
params do
use :pagination
optional :order_by, type: String, values: %w[released_at created_at], default: 'released_at',
desc: 'Return releases ordered by `released_at` or `created_at`.'
optional :sort, type: String, values: %w[asc desc], default: 'desc',
desc: 'Return releases sorted in `asc` or `desc` order.'
optional :include_html_description, type: Boolean,
desc: 'If `true`, a response includes HTML rendered markdown of the release description.'
end
get ':id/releases' do
releases = ::ReleasesFinder.new(user_project, current_user, declared_params.slice(:order_by, :sort)).execute
# We cache the serialized payload per user in order to avoid repeated renderings.
# Since the cached result could contain sensitive information,
# it will expire in a short interval.
present_cached paginate(releases),
with: Entities::Release,
# `current_user` could be absent if the releases are publicly accesible.
# We should not use `cache_key` for the user because the version/updated_at
# context is unnecessary here.
cache_context: -> (_) { "user:{#{current_user&.id}}" },
expires_in: 5.minutes,
current_user: current_user,
include_html_description: params[:include_html_description]
end
desc 'Get a single project release' do
detail 'This feature was introduced in GitLab 11.7.'
named 'get_release'
success Entities::Release
end
params do
requires :tag_name, type: String, desc: 'The name of the tag', as: :tag
optional :include_html_description, type: Boolean,
desc: 'If `true`, a response includes HTML rendered markdown of the release description.'
end
get ':id/releases/:tag_name', requirements: RELEASE_ENDPOINT_REQUIREMENTS do
authorize_download_code!
present release, with: Entities::Release, current_user: current_user, include_html_description: params[:include_html_description]
end
desc 'Create a new release' do
detail 'This feature was introduced in GitLab 11.7.'
named 'create_release'
success Entities::Release
end
params do
requires :tag_name, type: String, desc: 'The name of the tag', as: :tag
optional :name, type: String, desc: 'The name of the release'
optional :description, type: String, desc: 'The release notes'
optional :ref, type: String, desc: 'The commit sha or branch name'
optional :assets, type: Hash do
optional :links, type: Array do
requires :name, type: String, desc: 'The name of the link'
requires :url, type: String, desc: 'The URL of the link'
optional :filepath, type: String, desc: 'The filepath of the link'
optional :link_type, type: String, desc: 'The link type, one of: "runbook", "image", "package" or "other"'
end
end
optional :milestones, type: Array[String], coerce_with: ::API::Validations::Types::CommaSeparatedToArray.coerce, desc: 'The titles of the related milestones', default: []
optional :released_at, type: DateTime, desc: 'The date when the release will be/was ready. Defaults to the current time.'
end
route_setting :authentication, job_token_allowed: true
post ':id/releases' do
authorize_create_release!
result = ::Releases::CreateService
.new(user_project, current_user, declared_params(include_missing: false))
.execute
if result[:status] == :success
log_release_created_audit_event(result[:release])
present result[:release], with: Entities::Release, current_user: current_user
else
render_api_error!(result[:message], result[:http_status])
end
end
desc 'Update a release' do
detail 'This feature was introduced in GitLab 11.7.'
named 'update_release'
success Entities::Release
end
params do
requires :tag_name, type: String, desc: 'The name of the tag', as: :tag
optional :name, type: String, desc: 'The name of the release'
optional :description, type: String, desc: 'Release notes with markdown support'
optional :released_at, type: DateTime, desc: 'The date when the release will be/was ready.'
optional :milestones, type: Array[String], coerce_with: ::API::Validations::Types::CommaSeparatedToArray.coerce, desc: 'The titles of the related milestones'
end
put ':id/releases/:tag_name', requirements: RELEASE_ENDPOINT_REQUIREMENTS do
authorize_update_release!
result = ::Releases::UpdateService
.new(user_project, current_user, declared_params(include_missing: false))
.execute
if result[:status] == :success
log_release_updated_audit_event
log_release_milestones_updated_audit_event if result[:milestones_updated]
present result[:release], with: Entities::Release, current_user: current_user
else
render_api_error!(result[:message], result[:http_status])
end
end
desc 'Delete a release' do
detail 'This feature was introduced in GitLab 11.7.'
named 'delete_release'
success Entities::Release
end
params do
requires :tag_name, type: String, desc: 'The name of the tag', as: :tag
end
delete ':id/releases/:tag_name', requirements: RELEASE_ENDPOINT_REQUIREMENTS do
authorize_destroy_release!
result = ::Releases::DestroyService
.new(user_project, current_user, declared_params(include_missing: false))
.execute
if result[:status] == :success
present result[:release], with: Entities::Release, current_user: current_user
else
render_api_error!(result[:message], result[:http_status])
end
end
end
helpers do
def authorize_create_release!
authorize! :create_release, user_project
end
def authorize_read_releases!
authorize! :read_release, user_project
end
def authorize_read_release!
authorize! :read_release, release
end
def authorize_update_release!
authorize! :update_release, release
end
def authorize_destroy_release!
authorize! :destroy_release, release
end
def authorize_download_code!
authorize! :download_code, release
end
def authorize_create_evidence!
# extended in EE
end
def release
@release ||= user_project.releases.find_by_tag(params[:tag])
end
def log_release_created_audit_event(release)
# extended in EE
end
def log_release_updated_audit_event
# extended in EE
end
def log_release_milestones_updated_audit_event
# extended in EE
end
def release_cli?
request.env['HTTP_USER_AGENT']&.include?(RELEASE_CLI_USER_AGENT) == true
end
def event_context
{
release_cli: release_cli?
}
end
def track_release_event
Gitlab::Tracking.event(options[:for].name, options[:route_options][:named],
project: user_project, user: current_user, **event_context)
end
end
end
end
API::Releases.prepend_mod_with('API::Releases')
|
