Batch transfer GitLab projects with the GitLab API

This is a bit off-topic to be filed under DevOps / workflow automation but I still wanted to share it: We use GitLab at the WZB for collaborative software development and project management and I recently had to transfer all my GitLab projects to a GitLab group.[1]In case you don’t know GitLab: It’s similar to GitHub but open-source and you can install your own instance on your server so that all your data stays within your organization’s IT … Continue reading Since transferring a personal project to a group is not something that is done regularly, it’s quite hidden in the project settings and involves a lot of steps. Transferring a project manually with the GitLab web interface means visiting the project page, navigating to the “transfer project” pane in its advanced settings, selecting the group, clicking “Transfer group” and typing a confirmation string. Nobody want’s to do this manually with more than a handful of projects. Luckily GitLab comes with it’s own, well-documented REST API which can save us a lot of time by letting us automating such tedious tasks.

First, you should create the group you want to move all projects to, if you haven’t yet. Note the ID of the group, it’s shown under the title of the group on the group’s front page.[2]All instructions refer to GitLab 13 and may be different in other versions. If you want to use GitLab’s API, the first thing you need to do is to generate a personal access token (PAT). This can be done in your user settings under Access Tokens. You need to grant access to the “api” and “read_user” scopes, create the token and store it in a safe place.

We can try out the token right away by trying to transfer a sample project to the group. You need to note the ID of the project that you want to transfer. For this, go to the projects list under Your Projects > Personal and select a sample project. On its project page you will find its ID right under the project title. We now use curl on the terminal to send a transfer request to the GitLab API. There are several gaps that you need to fill in: <PAT> is your personal access token; <HOST> is the domain of your GitLab instance, e.g. gitlab.myinstitute.org; <PROJECT_ID> is the ID of your sample project; <NAMESPACE_ID> is the group ID.

curl --request PUT --header "PRIVATE-TOKEN: <PAT>" \
     "https://<HOST>/api/v4/projects/<PROJECT_ID>/transfer?namespace=<NAMESPACE_ID>"

If everything worked out, you should get a JSON formatted response. When you sift through this hard to read mess, you can notice a “namespace” key with an “id” entry which should reflect the group ID that you wanted to move the project to.

The next thing is to automate all this, i.e. fetching all personal projects of the user that is authenticated with the PAT and transferring each of these projects. I’ve written a Python script that does all this so you don’t have to.

Footnotes

Footnotes
1 In case you don’t know GitLab: It’s similar to GitHub but open-source and you can install your own instance on your server so that all your data stays within your organization’s IT realm. That’s better for data projection, customizability and you’re less dependent on the services of an external company.
2 All instructions refer to GitLab 13 and may be different in other versions.

Comments are closed.

Post Navigation