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.

{
  "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.

Payload for creating an issue

{
  "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.

Payload for adding a comment
```
{
  "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:
```
{
  "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:
```
{
  "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:

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.
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.
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.
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.