fix parsing errors and sphinx warnings
Signed-off-by: Ryan Lerch <rlerch@redhat.com>
This commit is contained in:
zlopez
parent
8fb9b2fdf0
commit
ba720c3d77
98 changed files with 4799 additions and 4788 deletions
|
|
@ -3,49 +3,50 @@
|
|||
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).
|
||||
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>`_.
|
||||
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.
|
||||
<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.
|
||||
{
|
||||
"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>`_.
|
||||
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>`_.
|
||||
|
||||
|
|
@ -53,11 +54,11 @@ I tested this on `ARC project ticket <https://pagure.io/fedora-infra/arc/issue/5
|
|||
|
||||
.. 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."
|
||||
}
|
||||
{
|
||||
"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>`_.
|
||||
|
||||
|
|
@ -65,45 +66,44 @@ I tested this on `ARC project ticket <https://pagure.io/fedora-infra/arc/issue/5
|
|||
|
||||
.. 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:
|
||||
{
|
||||
"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."
|
||||
}
|
||||
{
|
||||
"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:
|
||||
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."
|
||||
}
|
||||
|
||||
|
||||
{
|
||||
"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:
|
||||
<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
|
||||
|
||||
|
|
@ -112,30 +112,31 @@ the options that could be leveraged by the user for migration:
|
|||
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue