arc/docs/pagure2gitlab/gitlab.rst

.. _gitlab:

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 API key is used
   to execute API call and according to API documentation it's not possible to change it.
   We can overcome this by adding relevant information to each comment or issue. For example
   the payload can look like this:


   .. code-block:: json

      {
        "created_at": "2023-01-19T12:59:59Z",
        "body": "(This comment was added by [t0xic0der](https://accounts.fedoraproject.org/user/t0xic0der/))\n\nHere's a sample comment as you requested @zlopez."
      }

   The information about GitLab account could be added as well. This could be obtained by using
   `users API call <https://docs.gitlab.com/ee/api/users.html>`_ with `mail` as parameter. If the
   user is found it will username of the user on GitLab. The final requests could look like this:

   .. code-block:: json

      {
        "created_at": "2023-01-19T12:59:59Z",
        "body": "(This comment was added by @t0xic0der [FAS](https://accounts.fedoraproject.org/user/t0xic0der/))\n\nHere's a sample comment as you requested @zlopez."
      }



Importing pull requests
-----------------------

To import the pull requests it's possible to use `Create MR API call
<https://docs.gitlab.com/ee/api/merge_requests.html#create-mr>`_. However this doesn't allow
us to open pull requests from any repository that is not hosted on GitLab. Following are
the options that could be leveraged by the user for migration:

1. Don't import any pull requests

   This option makes the migration process much easier, but we will not have any already
   existing pull request in GitLab at all.

2. Merge all the pull requests before migration

   This is the best option for migration. Migration of the merged code is easy and there wouldn't
   be any information loss when migrating.

3. Migrate forks to GitLab as well

   This will allow us to create pull requests from migrated forks of the original repository.
   But this option means migrating plenty of git repositories, just to open the pull requests.
   If this option is chosen, I'm recommending to only limit this to open pull requests on Pagure.

4. Create branches on migrated repository

   It's easy to open pull request from branch on the same repository, but this will mean that
   tool will need to go through all the forks, add them as remotes and then add those as
   local branches, which allows us to easily create a pull request. I don't recommend using
   this approach as it needs plenty of adjustments on the migrated repository before the actual
   migration.

In addition to the issue mentioned above the pull requests will have the same issue with author
as import of tickets. The author will be set to whoever generated the API key.

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 could be mitigated by
adding the information directly to the pull request, issue or comment with link to FAS account
of the user.