Add new BulkImports endpoint to start new migration

  - Currently the only way to start BulkImport GitLab
    migration is to do that via the UI
  - Add new endpoint to be able to do the same thing
    via the API

Changelog: added

doc/api/bulk_imports.md

@@ -11,6 +11,47 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 With the GitLab Migrations API, you can view the progress of migrations initiated with
 [GitLab Group Migration](../user/group/import/index.md).
 
+## Start a new GitLab migration
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/66353) in GitLab 14.2.
+
+```plaintext
+POST /bulk_imports
+```
+
+| Attribute                         | Type   | Required | Description |
+| --------------------------------- | ------ | -------- | ----------- |
+| `configuration`                   | Hash   | yes      | The source GitLab instance configuration. |
+| `configuration[url]`              | String | yes      | Source GitLab instance URL. |
+| `configuration[access_token]`     | String | yes      | Access token to the source GitLab instance. |
+| `entities`                        | Array  | yes      | List of entities to import. |
+| `entities[source_type]`           | String | yes      | Source entity type (only `group_entity` is supported). |
+| `entities[source_full_path]`      | String | yes      | Source full path of the entity to import. |
+| `entities[destination_name]`      | String | yes      | Destination name for the entity. |
+| `entities[destination_namespace]` | String | no       | Destination namespace for the entity. |
+
+```shell
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/bulk_imports" \
+  --data '{
+    "configuration": {
+      "url": "http://gitlab.example/",
+      "access_token": "access_token"
+    },
+    "entities": [
+      {
+        "source_full_path": "source/full/path",
+        "source_type": "group_entity",
+        "destination_name": "destination_name",
+        "destination_namespace": "destination/namespace/path"
+      }
+    ]
+  }'
+```
+
+```json
+{ "id": 1, "status": "created", "source_type": "gitlab", "created_at": "2021-06-18T09:45:55.358Z", "updated_at": "2021-06-18T09:46:27.003Z" }
+```
+
 ## List all GitLab migrations
 
 ```plaintext

lib/api/bulk_imports.rb

@@ -8,7 +8,10 @@ module API
 
     helpers do
       def bulk_imports
-        @bulk_imports ||= ::BulkImports::ImportsFinder.new(user: current_user, status: params[:status]).execute
+        @bulk_imports ||= ::BulkImports::ImportsFinder.new(
+          user: current_user,
+          status: params[:status]
+        ).execute
       end
 
       def bulk_import
@@ -16,7 +19,11 @@ module API
       end
 
       def bulk_import_entities
-        @bulk_import_entities ||= ::BulkImports::EntitiesFinder.new(user: current_user, bulk_import: bulk_import, status: params[:status]).execute
+        @bulk_import_entities ||= ::BulkImports::EntitiesFinder.new(
+          user: current_user,
+          bulk_import: bulk_import,
+          status: params[:status]
+        ).execute
       end
 
       def bulk_import_entity
@@ -27,6 +34,37 @@ module API
     before { authenticate! }
 
     resource :bulk_imports do
+      desc 'Start a new GitLab Migration' do
+        detail 'This feature was introduced in GitLab 14.2.'
+      end
+      params do
+        requires :configuration, type: Hash, desc: 'The source GitLab instance configuration' do
+          requires :url, type: String, desc: 'Source GitLab instance URL'
+          requires :access_token, type: String, desc: 'Access token to the source GitLab instance'
+        end
+        requires :entities, type: Array, desc: 'List of entities to import' do
+          requires :source_type, type: String, desc: 'Source entity type (only `group_entity` is supported)',
+                   values: %w[group_entity]
+          requires :source_full_path, type: String, desc: 'Source full path of the entity to import'
+          requires :destination_name, type: String, desc: 'Destination name for the entity'
+          requires :destination_namespace, type: String, desc: 'Destination namespace for the entity'
+        end
+      end
+      post do
+        response = BulkImportService.new(
+          current_user,
+          params[:entities],
+          url: params[:configuration][:url],
+          access_token: params[:configuration][:access_token]
+        ).execute
+
+        if response.success?
+          present response.payload, with: Entities::BulkImport
+        else
+          render_api_error!(response.message, response.http_status)
+        end
+      end
+
       desc 'List all GitLab Migrations' do
         detail 'This feature was introduced in GitLab 14.1.'
       end
@@ -48,7 +86,10 @@ module API
           desc: "Return all GitLab Migrations' entities with specified status"
       end
       get :entities do
-        entities = ::BulkImports::EntitiesFinder.new(user: current_user, status: params[:status]).execute
+        entities = ::BulkImports::EntitiesFinder.new(
+          user: current_user,
+          status: params[:status]
+        ).execute
 
         present paginate(entities), with: Entities::BulkImports::Entity
       end

spec/requests/api/bulk_imports_spec.rb

@@ -20,6 +20,48 @@ RSpec.describe API::BulkImports do
     end
   end
 
+  describe 'POST /bulk_imports' do
+    it 'starts a new migration' do
+      post api('/bulk_imports', user), params: {
+        configuration: {
+          url: 'http://gitlab.example',
+          access_token: 'access_token'
+        },
+        entities: [
+          source_type: 'group_entity',
+          source_full_path: 'full_path',
+          destination_name: 'destination_name',
+          destination_namespace: 'destination_namespace'
+        ]
+      }
+
+      expect(response).to have_gitlab_http_status(:created)
+
+      expect(json_response['status']).to eq('created')
+    end
+
+    context 'when provided url is blocked' do
+      it 'returns blocked url error' do
+        post api('/bulk_imports', user), params: {
+          configuration: {
+            url: 'url',
+            access_token: 'access_token'
+          },
+          entities: [
+            source_type: 'group_entity',
+            source_full_path: 'full_path',
+            destination_name: 'destination_name',
+            destination_namespace: 'destination_namespace'
+          ]
+        }
+
+        expect(response).to have_gitlab_http_status(:unprocessable_entity)
+
+        expect(json_response['message']).to eq('Validation failed: Url is blocked: Only allowed schemes are http, https')
+      end
+    end
+  end
+
   describe 'GET /bulk_imports/entities' do
     it 'returns a list of all import entities authored by the user' do
       get api('/bulk_imports/entities', user)