summaryrefslogtreecommitdiff
path: root/lib/api/releases.rb
blob: 9e085a91a7c12792c832eebba78acbbf0f200d73 (plain)
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
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
# 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'

    feature_category :release_orchestration

    params do
      requires :id, type: String, desc: 'The ID of a group'
    end
    resource :groups, requirements: API::NAMESPACE_OR_PROJECT_REQUIREMENTS do
      before { authorize_read_group_releases! }

      desc 'Get a list of releases for projects in this group.' do
        success Entities::Release
      end
      params do
        requires :id, type: Integer, desc: 'The ID of the group to get releases for'
        optional :sort, type: String, values: %w[asc desc], default: 'desc',
                 desc: 'Return projects sorted in ascending and descending order by released_at'
        optional :simple, type: Boolean, default: false,
                 desc: 'Return only the ID, URL, name, and path of each project'

        use :pagination
      end
      get ":id/releases" do
        not_found! unless Feature.enabled?(:group_releases_finder_inoperator)

        finder_options = {
          sort: params[:sort]
        }

        strict_params = declared_params(include_missing: false)
        releases = find_group_releases(finder_options)

        present_group_releases(strict_params, releases)
      end
    end

    params do
      requires :id, type: String, desc: 'The ID of a project'
    end
    resource :projects, requirements: API::NAMESPACE_OR_PROJECT_REQUIREMENTS do
      before { authorize_read_releases! }

      after { track_release_event }

      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
      route_setting :authentication, job_token_allowed: true
      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
      route_setting :authentication, job_token_allowed: true
      get ':id/releases/:tag_name', requirements: RELEASE_ENDPOINT_REQUIREMENTS do
        authorize_download_code!

        not_found! unless release

        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
      route_setting :authentication, job_token_allowed: true
      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
      route_setting :authentication, job_token_allowed: true
      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_read_group_releases!
        authorize! :read_release, user_group
      end

      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, user_project
      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

      def find_group_releases(finder_options)
        ::Releases::GroupReleasesFinder
          .new(user_group, current_user, finder_options)
          .execute(preload: true)
      end

      def present_group_releases(params, releases)
        options = {
          with: params[:simple] ? Entities::BasicReleaseDetails : Entities::Release,
          current_user: current_user
        }

        # GroupReleasesFinder has already ordered the data for us
        present paginate(releases, skip_default_order: true), options
      end
    end
  end
end

API::Releases.prepend_mod_with('API::Releases')