diff --git a/doc/api/project_packages_protection_rules.md b/doc/api/project_packages_protection_rules.md index 0d7cb9d3af6eb20378e1ea926aae211ae62168d2..f93e0cb2f60ef133f37e902f6396d09d426c95bc 100644 --- a/doc/api/project_packages_protection_rules.md +++ b/doc/api/project_packages_protection_rules.md @@ -9,7 +9,7 @@ description: "Documentation for the REST API for Package Protection Rules in Git DETAILS: **Tier:** Free, Premium, Ultimate -**Offering:** GitLab.com, Self-managed +**Offering:** Self-managed **Status:** Experiment > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/151741) in GitLab 17.1 [with a flag](../administration/feature_flags.md) named `packages_protected_packages`. Disabled by default. @@ -72,6 +72,48 @@ Example response: ] ``` +## Create a package protection rule + +Create a package protection rule for a project. + +```plaintext +POST /api/v4/projects/:id/packages/protection/rules +``` + +Supported attributes: + +| Attribute | Type | Required | Description | +|---------------------------------------|-----------------|----------|--------------------------------| +| `id` | integer/string | Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | +| `package_name_pattern` | string | Yes | Package name protected by the protection rule. For example `@my-scope/my-package-*`. Wildcard character `*` allowed. | +| `package_type` | string | Yes | Package type protected by the protection rule. For example `npm`. | +| `minimum_access_level_for_push` | string | Yes | Minimum GitLab access level able to push a package. For example `developer`, `maintainer`, `owner`. | + +If successful, returns [`201`](rest/index.md#status-codes) and the created package protection rule. + +Can return the following status codes: + +- `201 Created`: The package protection rule was created successfully. +- `400 Bad Request`: The package protection rule is invalid. +- `401 Unauthorized`: The access token is invalid. +- `403 Forbidden`: The user does not have permission to create a package protection rule. +- `404 Not Found`: The project was not found. +- `422 Unprocessable Entity`: The package protection rule could not be created, for example, because the `package_name_pattern` is already taken. + +Example request: + +```shell +curl --request POST \ + --header "PRIVATE-TOKEN: " \ + --header "Content-Type: application/json" \ + --url "https://gitlab.example.com/api/v4/projects/7/packages/protection/rules" \ + --data '{ + "package_name_pattern": "package-name-pattern-*", + "package_type": "npm", + "minimum_access_level_for_push": "maintainer" + }' +``` + ## Delete a package protection rule Deletes a package protection rule from a project. diff --git a/lib/api/project_packages_protection_rules.rb b/lib/api/project_packages_protection_rules.rb index bcabecf47f662a6ed18900b3428ad73da03540bc..a86ac8fb07686cb0ef2000926eac4c0a9298a987 100644 --- a/lib/api/project_packages_protection_rules.rb +++ b/lib/api/project_packages_protection_rules.rb @@ -32,6 +32,35 @@ class ProjectPackagesProtectionRules < ::API::Base present user_project.package_protection_rules, with: Entities::Projects::Packages::Protection::Rule end + desc 'Create a package protection rule for a project' do + success Entities::Projects::Packages::Protection::Rule + failure [ + { code: 400, message: 'Bad Request' }, + { code: 401, message: 'Unauthorized' }, + { code: 403, message: 'Forbidden' }, + { code: 404, message: 'Not Found' }, + { code: 422, message: 'Unprocessable Entity' } + ] + tags %w[projects] + end + params do + requires :package_name_pattern, type: String, + desc: 'Package name protected by the rule. For example @my-scope/my-package-*. Wildcard character * allowed.' + requires :package_type, type: String, values: Packages::Protection::Rule.package_types.keys, + desc: 'Package type protected by the rule. For example npm.' + requires :minimum_access_level_for_push, type: String, + values: Packages::Protection::Rule.minimum_access_level_for_pushes.keys, + desc: 'Minimum GitLab access level able to push a package. For example developer, maintainer, owner.' + end + post ':id/packages/protection/rules' do + response = ::Packages::Protection::CreateRuleService.new(project: user_project, current_user: current_user, + params: declared_params(params)).execute + + render_api_error!({ error: response.message }, :unprocessable_entity) if response.error? + + present response[:package_protection_rule], with: Entities::Projects::Packages::Protection::Rule + end + desc 'Delete package protection rule' do success code: 204, message: '204 No Content' failure [ diff --git a/spec/requests/api/project_packages_protection_rules_spec.rb b/spec/requests/api/project_packages_protection_rules_spec.rb index 20079cfb867a745321d36b5401501895e567d573..95e4216f86d0a3f76a04d4e9f59dab7b142127dc 100644 --- a/spec/requests/api/project_packages_protection_rules_spec.rb +++ b/spec/requests/api/project_packages_protection_rules_spec.rb @@ -2,7 +2,7 @@ require 'spec_helper' -RSpec.describe API::ProjectPackagesProtectionRules, feature_category: :package_registry do +RSpec.describe API::ProjectPackagesProtectionRules, :aggregate_failures, feature_category: :package_registry do include ExclusiveLeaseHelpers let_it_be(:project) { create(:project, :private) } @@ -15,13 +15,22 @@ let_it_be(:invalid_token) { 'invalid-token123' } let_it_be(:headers_with_invalid_token) { { Gitlab::Auth::AuthFinders::PRIVATE_TOKEN_HEADER => invalid_token } } - shared_examples 'rejecting project packages protection rules request' do |user_role, status| - context "for #{user_role}" do + shared_examples 'rejecting project packages protection rules request when not enough permissions' do + using RSpec::Parameterized::TableSyntax + + where(:user_role, :status) do + :reporter | :forbidden + :developer | :forbidden + :guest | :forbidden + nil | :not_found + end + + with_them do before do project.send(:"add_#{user_role}", api_user) if user_role end - it_behaves_like 'returning response status', status + it_behaves_like 'returning response status', params[:status] end end @@ -30,10 +39,7 @@ subject(:get_package_rules) { get(api(url, api_user)) } - it_behaves_like 'rejecting project packages protection rules request', :reporter, :forbidden - it_behaves_like 'rejecting project packages protection rules request', :developer, :forbidden - it_behaves_like 'rejecting project packages protection rules request', :guest, :forbidden - it_behaves_like 'rejecting project packages protection rules request', nil, :not_found + it_behaves_like 'rejecting project packages protection rules request when not enough permissions' context 'for maintainer' do let(:api_user) { maintainer } @@ -52,13 +58,13 @@ context 'when the project id is invalid' do let(:url) { "/projects/invalid/packages/protection/rules" } - it_behaves_like 'rejecting project packages protection rules request', :maintainer, :not_found + it_behaves_like 'returning response status', :not_found end context 'when the project id does not exist' do let(:url) { "/projects/#{non_existing_record_id}/packages/protection/rules" } - it_behaves_like 'rejecting project packages protection rules request', :maintainer, :not_found + it_behaves_like 'returning response status', :not_found end context 'when packages_protected_packages is disabled' do @@ -66,14 +72,89 @@ stub_feature_flags(packages_protected_packages: false) end - it_behaves_like 'rejecting project packages protection rules request', :maintainer, :not_found + it_behaves_like 'returning response status', :not_found end end context 'with invalid token' do subject(:get_package_rules) { get(api(url), headers: headers_with_invalid_token) } - it_behaves_like 'rejecting project packages protection rules request', nil, :unauthorized + it_behaves_like 'returning response status', :unauthorized + end + end + + describe 'POST /projects/:id/packages/protection/rules' do + let(:url) { "/projects/#{project.id}/packages/protection/rules" } + let(:params) do + { package_name_pattern: '@my-new-scope/my-package-*', + package_type: package_protection_rule.package_type, + minimum_access_level_for_push: package_protection_rule.minimum_access_level_for_push } + end + + subject(:post_package_rule) { post(api(url, api_user), params: params) } + + it_behaves_like 'rejecting project packages protection rules request when not enough permissions' + + context 'for maintainer' do + let(:api_user) { maintainer } + + it 'creates a package protection rule' do + expect { post_package_rule }.to change { Packages::Protection::Rule.count }.by(1) + expect(response).to have_gitlab_http_status(:created) + end + + context 'with invalid package_type' do + before do + params[:package_type] = "not in enum" + end + + it 'does not create a package protection rule' do + expect { post_package_rule }.to not_change(Packages::Protection::Rule, :count) + expect(response).to have_gitlab_http_status(:bad_request) + end + end + + context 'with invalid minimum_access_level_for_push' do + before do + params[:minimum_access_level_for_push] = "not in enum" + end + + it 'does not create a package protection rule' do + expect { post_package_rule }.to not_change(Packages::Protection::Rule, :count) + expect(response).to have_gitlab_http_status(:bad_request) + end + end + + context 'with already existing package_name_pattern' do + before do + params[:package_name_pattern] = package_protection_rule.package_name_pattern + end + + it 'does not create a package protection rule' do + expect { post_package_rule }.to not_change(Packages::Protection::Rule, :count) + expect(response).to have_gitlab_http_status(:unprocessable_entity) + end + end + + context 'when the project id is invalid' do + let(:url) { "/projects/invalid/packages/protection/rules" } + + it_behaves_like 'returning response status', :not_found + end + + context 'when the project id does not exist' do + let(:url) { "/projects/#{non_existing_record_id}/packages/protection/rules" } + + it_behaves_like 'returning response status', :not_found + end + + context 'when packages_protected_packages is disabled' do + before do + stub_feature_flags(packages_protected_packages: false) + end + + it_behaves_like 'returning response status', :not_found + end end end @@ -82,10 +163,7 @@ subject(:destroy_package_rule) { delete(api(url, api_user)) } - it_behaves_like 'rejecting project packages protection rules request', :reporter, :forbidden - it_behaves_like 'rejecting project packages protection rules request', :developer, :forbidden - it_behaves_like 'rejecting project packages protection rules request', :guest, :forbidden - it_behaves_like 'rejecting project packages protection rules request', nil, :not_found + it_behaves_like 'rejecting project packages protection rules request when not enough permissions' context 'for maintainer' do let(:api_user) { maintainer } @@ -102,31 +180,31 @@ context 'when the package protection rule does belong to another project' do let(:url) { "/projects/#{other_project.id}/packages/protection/rules/#{package_protection_rule.id}" } - it_behaves_like 'rejecting project packages protection rules request', :maintainer, :not_found + it_behaves_like 'returning response status', :not_found end context 'when the project id is invalid' do let(:url) { "/projects/invalid/packages/protection/rules/#{package_protection_rule.id}" } - it_behaves_like 'rejecting project packages protection rules request', :maintainer, :not_found + it_behaves_like 'returning response status', :not_found end context 'when the project id does not exist' do let(:url) { "/projects/#{non_existing_record_id}/packages/protection/rules/#{package_protection_rule.id}" } - it_behaves_like 'rejecting project packages protection rules request', :maintainer, :not_found + it_behaves_like 'returning response status', :not_found end context 'when the rule id is invalid' do let(:url) { "/projects/#{project.id}/packages/protection/rules/invalid" } - it_behaves_like 'rejecting project packages protection rules request', :maintainer, :bad_request + it_behaves_like 'returning response status', :bad_request end context 'when the rule id does not exist' do let(:url) { "/projects/#{project.id}/packages/protection/rules/#{non_existing_record_id}" } - it_behaves_like 'rejecting project packages protection rules request', :maintainer, :not_found + it_behaves_like 'returning response status', :not_found end context 'when packages_protected_packages is disabled' do @@ -134,13 +212,13 @@ stub_feature_flags(packages_protected_packages: false) end - it_behaves_like 'rejecting project packages protection rules request', :maintainer, :not_found + it_behaves_like 'returning response status', :not_found end context 'with invalid token' do subject(:delete_package_rules) { delete(api(url), headers: headers_with_invalid_token) } - it_behaves_like 'rejecting project packages protection rules request', nil, :unauthorized + it_behaves_like 'returning response status', :unauthorized end end end