diff options
Diffstat (limited to 'lib/api/ci/runners.rb')
| -rw-r--r-- | lib/api/ci/runners.rb | 292 |
1 files changed, 172 insertions, 120 deletions
diff --git a/lib/api/ci/runners.rb b/lib/api/ci/runners.rb index 4b578f8b7e5..988c3f4f566 100644 --- a/lib/api/ci/runners.rb +++ b/lib/api/ci/runners.rb @@ -10,20 +10,98 @@ module API feature_category :runner urgency :low + helpers do + params :deprecated_filter_params do + optional :scope, type: String, values: ::Ci::Runner::AVAILABLE_SCOPES, + desc: 'Deprecated: Use `type` or `status` instead. The scope of specific runners to return' + end + + params :filter_params do + optional :type, type: String, values: ::Ci::Runner::AVAILABLE_TYPES, desc: 'The type of runners to return' + optional :paused, type: Boolean, + desc: 'Whether to include only runners that are accepting or ignoring new jobs' + optional :status, type: String, values: ::Ci::Runner::AVAILABLE_STATUSES, + desc: 'The status of runners to return' + optional :tag_list, type: Array[String], coerce_with: ::API::Validations::Types::CommaSeparatedToArray.coerce, + desc: 'A list of runner tags', documentation: { example: "['macos', 'shell']" } + use :pagination + end + + def filter_runners(runners, scope, allowed_scopes: ::Ci::Runner::AVAILABLE_SCOPES) + return runners unless scope.present? + + unless allowed_scopes.include?(scope) + render_api_error!('Scope contains invalid value', 400) + end + + # Support deprecated scopes + if runners.respond_to?("deprecated_#{scope}") + scope = "deprecated_#{scope}" + end + + runners.public_send(scope) # rubocop:disable GitlabSecurity/PublicSend + end + + def apply_filter(runners, params) + runners = filter_runners(runners, params[:type], allowed_scopes: ::Ci::Runner::AVAILABLE_TYPES) + runners = filter_runners(runners, params[:status], allowed_scopes: ::Ci::Runner::AVAILABLE_STATUSES) + runners = filter_runners(runners, params[:paused] ? 'paused' : 'active', allowed_scopes: %w[paused active]) if params.include?(:paused) + runners = runners.tagged_with(params[:tag_list]) if params[:tag_list] + + runners + end + + def get_runner(id) + runner = ::Ci::Runner.find(id) + not_found!('Runner') unless runner + runner + end + + def authenticate_show_runner!(runner) + return if runner.instance_type? || current_user.admin? + + forbidden!("No access granted") unless can?(current_user, :read_runner, runner) + end + + def authenticate_update_runner!(runner) + return if current_user.admin? + + forbidden!("No access granted") unless can?(current_user, :update_runner, runner) + end + + def authenticate_delete_runner!(runner) + return if current_user.admin? + + forbidden!("Runner associated with more than one project") if runner.runner_projects.count > 1 + forbidden!("No access granted") unless can?(current_user, :delete_runner, runner) + end + + def authenticate_enable_runner!(runner) + forbidden!("Runner is a group runner") if runner.group_type? + + return if current_user.admin? + + forbidden!("Runner is locked") if runner.locked? + forbidden!("No access granted") unless can?(current_user, :assign_runner, runner) + end + + def authenticate_list_runners_jobs!(runner) + return if current_user.admin? + + forbidden!("No access granted") unless can?(current_user, :read_builds, runner) + end + end + resource :runners do desc 'Get runners available for user' do + summary 'List owned runners' success Entities::Ci::Runner + failure [[400, 'Scope contains invalid value'], [401, 'Unauthorized']] + tags %w[runners] end params do - optional :scope, type: String, values: ::Ci::Runner::AVAILABLE_STATUSES, - desc: 'The scope of specific runners to show' - optional :type, type: String, values: ::Ci::Runner::AVAILABLE_TYPES, - desc: 'The type of the runners to show' - optional :paused, type: Boolean, desc: 'Whether to include only runners that are accepting or ignoring new jobs' - optional :status, type: String, values: ::Ci::Runner::AVAILABLE_STATUSES, - desc: 'The status of the runners to show' - optional :tag_list, type: Array[String], coerce_with: ::API::Validations::Types::CommaSeparatedToArray.coerce, desc: 'The tags of the runners to show' - use :pagination + use :deprecated_filter_params + use :filter_params end get do runners = current_user.ci_owned_runners @@ -34,18 +112,16 @@ module API end desc 'Get all runners - shared and specific' do + summary 'List all runners' + detail 'Get a list of all runners in the GitLab instance (specific and shared). ' \ + 'Access is restricted to users with administrator access.' success Entities::Ci::Runner + failure [[400, 'Scope contains invalid value'], [401, 'Unauthorized']] + tags %w[runners] end params do - optional :scope, type: String, values: ::Ci::Runner::AVAILABLE_SCOPES, - desc: 'The scope of specific runners to show' - optional :type, type: String, values: ::Ci::Runner::AVAILABLE_TYPES, - desc: 'The type of the runners to show' - optional :paused, type: Boolean, desc: 'Whether to include only runners that are accepting or ignoring new jobs' - optional :status, type: String, values: ::Ci::Runner::AVAILABLE_STATUSES, - desc: 'The status of the runners to show' - optional :tag_list, type: Array[String], coerce_with: ::API::Validations::Types::CommaSeparatedToArray.coerce, desc: 'The tags of the runners to show' - use :pagination + use :deprecated_filter_params + use :filter_params end get 'all' do authenticated_as_admin! @@ -58,10 +134,13 @@ module API end desc "Get runner's details" do + detail 'At least the Maintainer role is required to get runner details at the project and group level. ' \ + 'Instance-level runner details via this endpoint are available to all signed in users.' success Entities::Ci::RunnerDetails + failure [[401, 'Unauthorized'], [403, 'No access granted'], [404, 'Runner not found']] end params do - requires :id, type: Integer, desc: 'The ID of the runner' + requires :id, type: Integer, desc: 'The ID of a runner' end get ':id' do runner = get_runner(params[:id]) @@ -71,19 +150,24 @@ module API end desc "Update runner's details" do + summary "Update details of a runner" success Entities::Ci::RunnerDetails + failure [[400, 'Bad Request'], [401, 'Unauthorized'], [403, 'No access granted'], [404, 'Runner not found']] end params do - requires :id, type: Integer, desc: 'The ID of the runner' + requires :id, type: Integer, desc: 'The ID of a runner' optional :description, type: String, desc: 'The description of the runner' - optional :active, type: Boolean, desc: 'Deprecated: Use `:paused` instead. Flag indicating whether the runner is allowed to receive jobs' - optional :paused, type: Boolean, desc: 'Flag indicating whether the runner should ignore new jobs' - optional :tag_list, type: Array[String], coerce_with: ::API::Validations::Types::CommaSeparatedToArray.coerce, desc: 'The list of tags for a runner' - optional :run_untagged, type: Boolean, desc: 'Flag indicating whether the runner can execute untagged jobs' - optional :locked, type: Boolean, desc: 'Flag indicating the runner is locked' + optional :active, type: Boolean, desc: 'Deprecated: Use `paused` instead. Flag indicating whether the runner is allowed to receive jobs' + optional :paused, type: Boolean, desc: 'Specifies whether the runner should ignore new jobs' + optional :tag_list, type: Array[String], coerce_with: ::API::Validations::Types::CommaSeparatedToArray.coerce, + desc: 'The list of tags for a runner', documentation: { example: "['macos', 'shell']" } + optional :run_untagged, type: Boolean, desc: 'Specifies whether the runner can execute untagged jobs' + optional :locked, type: Boolean, desc: 'Specifies whether the runner is locked' optional :access_level, type: String, values: ::Ci::Runner.access_levels.keys, - desc: 'The access_level of the runner' - optional :maximum_timeout, type: Integer, desc: 'Maximum timeout set when this Runner will handle the job' + desc: 'The access level of the runner' + optional :maximum_timeout, type: Integer, + desc: 'Maximum timeout that limits the amount of time (in seconds) ' \ + 'that runners can run jobs' at_least_one_of :description, :active, :paused, :tag_list, :run_untagged, :locked, :access_level, :maximum_timeout mutually_exclusive :active, :paused end @@ -101,10 +185,15 @@ module API end desc 'Remove a runner' do + summary 'Delete a runner' success Entities::Ci::Runner + failure [[401, 'Unauthorized'], [403, 'No access granted'], + [403, 'Runner associated with more than one project'], [404, 'Runner not found'], + [412, 'Precondition Failed']] + tags %w[runners] end params do - requires :id, type: Integer, desc: 'The ID of the runner' + requires :id, type: Integer, desc: 'The ID of a runner' end delete ':id' do runner = get_runner(params[:id]) @@ -115,13 +204,19 @@ module API end desc 'List jobs running on a runner' do + summary "List runner's jobs" + detail 'List jobs that are being processed or were processed by the specified runner. ' \ + 'The list of jobs is limited to projects where the user has at least the Reporter role.' success Entities::Ci::JobBasicWithProject + failure [[401, 'Unauthorized'], [403, 'No access granted'], [404, 'Runner not found']] + tags %w[runners jobs] end params do - requires :id, type: Integer, desc: 'The ID of the runner' + requires :id, type: Integer, desc: 'The ID of a runner' optional :status, type: String, desc: 'Status of the job', values: ::Ci::Build::AVAILABLE_STATUSES - optional :order_by, type: String, desc: 'Order by `id` or not', values: ::Ci::RunnerJobsFinder::ALLOWED_INDEXED_COLUMNS - optional :sort, type: String, values: %w[asc desc], default: 'desc', desc: 'Sort by asc (ascending) or desc (descending)' + optional :order_by, type: String, desc: 'Order by `id`', values: ::Ci::RunnerJobsFinder::ALLOWED_INDEXED_COLUMNS + optional :sort, type: String, values: %w[asc desc], default: 'desc', desc: 'Sort by `asc` or `desc` order. ' \ + 'Specify `order_by` as well, including for `id`' use :pagination end get ':id/jobs' do @@ -143,7 +238,10 @@ module API end desc 'Reset runner authentication token' do + summary "Reset runner's authentication token" success Entities::Ci::ResetTokenResult + failure [[403, 'No access granted'], [404, 'Runner not found']] + tags %w[runners] end params do requires :id, type: Integer, desc: 'The ID of the runner' @@ -158,24 +256,24 @@ module API end params do - requires :id, type: String, desc: 'The ID of a project' + 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 before { authorize_admin_project } desc 'Get runners available for project' do + summary "List project's runners" + detail 'List all runners available in the project, including from ancestor groups ' \ + 'and any allowed shared runners.' success Entities::Ci::Runner + failure [[400, 'Scope contains invalid value'], [403, 'No access granted']] + tags %w[runners projects] end params do - optional :scope, type: String, values: ::Ci::Runner::AVAILABLE_SCOPES, - desc: 'The scope of specific runners to show' - optional :type, type: String, values: ::Ci::Runner::AVAILABLE_TYPES, - desc: 'The type of the runners to show' - optional :paused, type: Boolean, desc: 'Whether to include only runners that are accepting or ignoring new jobs' - optional :status, type: String, values: ::Ci::Runner::AVAILABLE_STATUSES, - desc: 'The status of the runners to show' - optional :tag_list, type: Array[String], coerce_with: ::API::Validations::Types::CommaSeparatedToArray.coerce, desc: 'The tags of the runners to show' - use :pagination + use :deprecated_filter_params + use :filter_params end get ':id/runners' do runners = ::Ci::Runner.owned_or_instance_wide(user_project.id) @@ -187,11 +285,16 @@ module API present paginate(runners), with: Entities::Ci::Runner end - desc 'Enable a runner for a project' do + desc 'Enable a runner in project' do + detail "Enable an available specific runner in the project." success Entities::Ci::Runner + failure [[400, 'Bad Request'], + [403, 'No access granted'], [403, 'Runner is a group runner'], [403, 'Runner is locked'], + [404, 'Runner not found']] + tags %w[runners projects] end params do - requires :runner_id, type: Integer, desc: 'The ID of the runner' + requires :runner_id, type: Integer, desc: 'The ID of a runner' end post ':id/runners' do runner = get_runner(params[:runner_id]) @@ -205,10 +308,17 @@ module API end desc "Disable project's runner" do + summary "Disable a specific runner from the project" + detail "It works only if the project isn't the only project associated with the specified runner. " \ + "If so, an error is returned. Use the call to delete a runner instead." success Entities::Ci::Runner + failure [[400, 'Bad Request'], + [403, 'Only one project associated with the runner. Please remove the runner instead'], + [404, 'Runner not found'], [412, 'Precondition Failed']] + tags %w[runners projects] end params do - requires :runner_id, type: Integer, desc: 'The ID of the runner' + requires :runner_id, type: Integer, desc: 'The ID of a runner' end # rubocop: disable CodeReuse/ActiveRecord delete ':id/runners/:runner_id' do @@ -230,16 +340,15 @@ module API before { authorize_admin_group } desc 'Get runners available for group' do + summary "List group's runners" + detail 'List all runners available in the group as well as its ancestor groups, ' \ + 'including any allowed shared runners.' success Entities::Ci::Runner + failure [[400, 'Scope contains invalid value'], [403, 'Forbidden']] + tags %w[runners groups] end params do - optional :type, type: String, values: ::Ci::Runner::AVAILABLE_TYPES, - desc: 'The type of the runners to show' - optional :paused, type: Boolean, desc: 'Whether to include only runners that are accepting or ignoring new jobs' - optional :status, type: String, values: ::Ci::Runner::AVAILABLE_STATUSES, - desc: 'The status of the runners to show' - optional :tag_list, type: Array[String], coerce_with: ::API::Validations::Types::CommaSeparatedToArray.coerce, desc: 'The tags of the runners to show' - use :pagination + use :filter_params end get ':id/runners' do runners = ::Ci::Runner.group_or_instance_wide(user_group) @@ -252,8 +361,11 @@ module API resource :runners do before { authenticate_non_get! } - desc 'Resets runner registration token' do + desc 'Reset runner registration token' do + summary "Reset instance's runner registration token" success Entities::Ci::ResetTokenResult + failure [[403, 'Forbidden']] + tags %w[runners groups] end post 'reset_registration_token' do authorize! :update_runners_registration_token, ApplicationSetting.current @@ -269,8 +381,11 @@ module API resource :projects, requirements: API::NAMESPACE_OR_PROJECT_REQUIREMENTS do before { authenticate_non_get! } - desc 'Resets runner registration token' do + desc 'Reset runner registration token' do + summary "Reset the runner registration token for a project" success Entities::Ci::ResetTokenResult + failure [[401, 'Unauthorized'], [403, 'Forbidden'], [404, 'Project Not Found']] + tags %w[runners projects] end post ':id/runners/reset_registration_token' do project = find_project! user_project.id @@ -287,8 +402,11 @@ module API resource :groups, requirements: API::NAMESPACE_OR_PROJECT_REQUIREMENTS do before { authenticate_non_get! } - desc 'Resets runner registration token' do + desc 'Reset runner registration token' do + summary "Reset the runner registration token for a group" success Entities::Ci::ResetTokenResult + failure [[401, 'Unauthorized'], [403, 'Forbidden'], [404, 'Group Not Found']] + tags %w[runners groups] end post ':id/runners/reset_registration_token' do group = find_group! user_group.id @@ -298,72 +416,6 @@ module API present group.runners_token_with_expiration, with: Entities::Ci::ResetTokenResult end end - - helpers do - def filter_runners(runners, scope, allowed_scopes: ::Ci::Runner::AVAILABLE_SCOPES) - return runners unless scope.present? - - unless allowed_scopes.include?(scope) - render_api_error!('Scope contains invalid value', 400) - end - - # Support deprecated scopes - if runners.respond_to?("deprecated_#{scope}") - scope = "deprecated_#{scope}" - end - - runners.public_send(scope) # rubocop:disable GitlabSecurity/PublicSend - end - - def apply_filter(runners, params) - runners = filter_runners(runners, params[:type], allowed_scopes: ::Ci::Runner::AVAILABLE_TYPES) - runners = filter_runners(runners, params[:status], allowed_scopes: ::Ci::Runner::AVAILABLE_STATUSES) - runners = filter_runners(runners, params[:paused] ? 'paused' : 'active', allowed_scopes: %w[paused active]) if params.include?(:paused) - runners = runners.tagged_with(params[:tag_list]) if params[:tag_list] - - runners - end - - def get_runner(id) - runner = ::Ci::Runner.find(id) - not_found!('Runner') unless runner - runner - end - - def authenticate_show_runner!(runner) - return if runner.instance_type? || current_user.admin? - - forbidden!("No access granted") unless can?(current_user, :read_runner, runner) - end - - def authenticate_update_runner!(runner) - return if current_user.admin? - - forbidden!("No access granted") unless can?(current_user, :update_runner, runner) - end - - def authenticate_delete_runner!(runner) - return if current_user.admin? - - forbidden!("Runner associated with more than one project") if runner.runner_projects.count > 1 - forbidden!("No access granted") unless can?(current_user, :delete_runner, runner) - end - - def authenticate_enable_runner!(runner) - forbidden!("Runner is a group runner") if runner.group_type? - - return if current_user.admin? - - forbidden!("Runner is locked") if runner.locked? - forbidden!("No access granted") unless can?(current_user, :assign_runner, runner) - end - - def authenticate_list_runners_jobs!(runner) - return if current_user.admin? - - forbidden!("No access granted") unless can?(current_user, :read_builds, runner) - end - end end end end |