docs/pagure2gitlab/gitlab.rst

@@ -2,3 +2,83 @@
 
 GitLab API investigation
 ========================
+
+This document investigates API calls that are needed to address the requirements for Pagure to GitLab
+importer. Currently the GitLab provides both `REST <https://docs.gitlab.com/ee/api/rest/>`_
+and `GraphQL <https://docs.gitlab.com/ee/api/graphql/>`_ APIs. In this investigation I will only
+focus on REST API v4, because GraphQL API doesn't provide required calls
+(importing project and importing merge requests).
+
+All the REST API calls need user to provide
+`GitLab API token <https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html>`_.
+
+For the purpose of this investigation I tried to import `ARC repository
+<https://pagure.io/fedora-infra/arc>`_ to GitLab.
+
+GitLab API documentation: https://docs.gitlab.com/ee/api/
+
+
+Importing a git repository
+--------------------------
+
+Project can be imported by using `create project call
+<https://docs.gitlab.com/ee/api/projects.html#create-project>`_. Following is a payload for import
+of the ARC repository.
+
+.. code-block:: json
+
+   {
+     "name":"arc",
+     "description":"The Advance Reconnaissance Crew",
+     "namespace_id":"10910066",
+     "import_url":"https://pagure.io/fedora-infra/arc.git"
+   }
+
+This creates `ARC repository on GitLab <https://gitlab.com/testgroup519/arc>`_ with the whole
+commit history and users mapped by the e-mail.
+
+
+Importing ticket
+----------------
+
+Ticket can be imported by `creating an issue <https://docs.gitlab.com/ee/api/issues.html#new-issue>`_
+, `commenting on it <https://docs.gitlab.com/ee/api/notes.html#create-new-issue-note>`_,
+eventually close it by `editing the issue
+<https://docs.gitlab.com/ee/api/notes.html#create-new-issue-note>`_ and add any attachments by
+`uploading file to project <https://docs.gitlab.com/ee/api/projects.html#upload-a-file>`_.
+
+I tested this on `ARC project ticket <https://pagure.io/fedora-infra/arc/issue/59>`_.
+
+1. Payload for creating an issue
+
+   .. code-block:: json
+
+      {
+        "created_at": "2023-01-19T11:41:40Z",
+        "title": "Investigate the GitLab API for Pagure to Gitlab importer",
+        "description": "Investigate the GitLab API for Pagure to Gitlab importer ARC investigation. This ticket will also work as a test ticket in investigation."
+      }
+
+   This creates the `issue on GitLab <https://gitlab.com/testgroup519/arc/-/issues/1>`_.
+
+2. Payload for adding a comment
+
+   .. code-block:: json
+
+      {
+        "created_at": "2023-01-19T12:59:59Z",
+        "body": "Here's a sample comment as you requested @zlopez."
+      }
+
+   This creates `comment <https://gitlab.com/testgroup519/arc/-/issues/1#note_1245817484>`_ on
+   the previously created issue. In this case the comment was created by user, who executed the
+   API call and according to API documentation it's not possible to change it.
+
+
+Conclusion
+----------
+
+Using the REST API v4 is not useful for our purpose, because it will set author of every pull
+request, issue and comment to user running the migration tool. This means that we will lose
+most of the information we want to preserve. Thus it doesn't make sense to continue in the
+investigation.