.. _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
`_ and `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
`_.
For the purpose of this investigation I tried to import `ARC repository
`_ to GitLab.
GitLab API documentation: https://docs.gitlab.com/ee/api/
Importing a git repository
--------------------------
Project can be imported by using `create project call
`_. 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 `_ with the
whole commit history and users mapped by the e-mail.
Importing ticket
----------------
Ticket can be imported by `creating an issue
`_ , `commenting on it
`_, eventually close it
by `editing the issue
`_ and add any
attachments by `uploading file to project
`_.
I tested this on `ARC project ticket `_.
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 `_.
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
`_ 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 `_ 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
`_. 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.