FAQ Migration from INRIA Forge to INRIA Gitlab

Planning the migration

INRIA Forge project administrators and/or users need to coordinate to decide when and how to perform these migrations. It's also important to decide what exactly needs to be migrated, since you may not need to keep everything.

Coordination is paramount because if, as a project admin, you migrate for example the source control repository without telling the users, some of them might still use the old repository on the forge for checkouts or commits.

Communication with forge project members

As there is no simple way for a forge project administrator to get the list of emails of project members (to communicate with everyone and be sure to forget nobody), we can provide these lists on demand to forge project administrators. Open a ticket for this.

Preventing project members from commiting / pushing

Subversion

Add a pre-commit hook which always returns false. For example:

ssh scm.gforge.inria.fr
echo -e '#!'"/bin/bash\necho \"This repository is read-only\"\nexit 1" > /svnroot/<project unix name>/hooks/pre-commit
chmod a+x /svnroot/<project unix name>/hooks/pre-commit

Git

Add a pre-receive hook which always returns false. For example:

ssh scm.gforge.inria.fr
echo -e '#!'"/bin/bash\necho \"This repository is read-only\"\nexit 1" > /gitroot/<path_to_git_server_repo>/hooks/pre-receive
chmod a+x /gitroot/<path_to_git_server_repo>/hooks/pre-receive

Available documentation and help

The gitlab documentation is available here: https://gitlab.inria.fr/help

Beware that gitlab is both a software (gitlab) and a free hosting platform (https://gitlab.com). In many places in the documentation, the links given point to https://gitlab.com, you have to replace these by links to our instance: https://gitlab.inria.fr

Migration support is available through the inria helpdesk, in section "IT request", subsections "Ask for a fix" or "Service request" / "Services for research " / "GitLab" or "Inriaforge"

A mattermost channel is also available https://mattermost.inria.fr/devel/channels/gforge-gitlab (but remember that the preferred way to ask for support is through the helpdesk because support tickets can be correctly tracked).

For specific technical details on gitlab, git, git svn... there are numerous resources easily available on the web. In many situations, moving from subversion to git is pretty easy as long as you stick with basic operations:

svn checkout -> git clone
svn update -> git pull
svn commit -> git add + git commit + git push

There are cheat sheets with basic equivalence, such as this one.

To better understand git concepts, you can for example have a look at Anthony Baire tutorials

Gitlab project setup

A gitlab project needs to be created. It's up to you to choose between private / internal / public project (see https://gitlab.inria.fr/help/public_access/public_access.md). You can choose between a project in a user namespace or in a group namespace (see https://gitlab.inria.fr/help/user/group/index.md#namespaces)

Projects members need to have an account on the gitlab. If they don't have an account, they need to create one. It will then be possible for them to request access to the project (but only for public projects) or the opposite, an administrator can manually add them.

Project name and user names do need necessarily need to be the same between gforge and gitlab (though it may be simpler, if they are the same).

Also don't forget that to be able to actually do something (like cloning, pushing...) users need to setup their account correctly. If they want to use ssh to avoid entering their username/password on each action, they should have a working ssh setup and upload their ssh public key to the gitlab (the same as with the gforge)

Migration of source control repositories

INRIA gitlab is restricted to git (no subversion anymore), so for subversion users unfamiliar with git, you should take the time to read and understand the basic differences between subversion and git. If you want to stay with subversion, there is no alternative at INRIA, but you can go to SourceSup https://sourcesup.renater.fr/, which is actively maintained by Renater.

You need to decide if you want to migrate just the tip of your development history (last version on the repository) or if you want to migrate the whole commits / branching / tags history. Note that in several situations, there is no real need to migrate the whole history. For example if you keep a project only for historical reference, you may not need all the commit history.

In the following examples, we assume that the gitlab project is already created, correctly setup, and empty. The user performing the migration has a gforge account <forge_user>, a gforge project with unixname <forge_project>, a gitlab account <gitlab_user> and a gitlab project in the <gitlab_user> namespace, with name <gitlab_project>.

Migrating only the last version of the repository

Get the last version of the development tree (git or subversion), and import this in a new gitlab repository. All history is lost.

Migrating the whole (or part of the) history

From Subversion

Command-line git-svn method

Checkout the subversion repository with git-svn (https://git-scm.com/docs/git-svn). It creates a git repository from the subversion repository (with all the history). You can then add your gitlab project as a git remote and push to that project:

git svn clone svn+ssh://<forge_user>@scm.gforge.inria.fr/svnroot/<forge_project>/
cd <forge_project>
git remote add origin git@gitlab.inria.fr:<gitlab_user>/<gitlab_project>.git
git push --set-upstream origin master

This directory can then be used to work from now on, or if you want to be sure that everything is correct, you can try a new checkout from scratch from the gitlab in another directory:

cd ..
mv <forge_project> <forge_project>.migration
# (may be removed later when you're sure the migration was correct
git clone git@gitlab.inria.fr:<gitlab_user>/<gitlab_project>.git
cd <gitlab_project>
# check that all is correct

Alternative methods

Other methods are described here: https://gitlab.inria.fr/help/user/project/import/svn

From Git

Command-line mirror method

A convenient way to migrate everything (all branches, all tags) in a single operation is to use a mirror checkout:

git clone --mirror git+ssh://<forge_user>@scm.gforge.inria.fr/gitroot/<forge_project>/<forge_project>.git
cd <forge_project>.git
git push --mirror git@gitlab.inria.fr:<gitlab_user>/<gitlab_project>.git

This directory cannot be used as a local working copy since the --mirror option implies --bare. You need to checkout a new working copy:

cd  ..
mv <forge_project>.git <forge_project>.git.migration
# (may be removed later when you're sure the migration was correct
git clone git@gitlab.inria.fr:<gitlab_user>/<gitlab_project>.git
cd <gitlab_project>
# check that all is correct

Gitlab import method

An alternative method is to directly choose the "Import project" tab when creating the project in gitlab, and then choose "Git repo by URL". Enter the URL of the project's git repository on the forge, such as: https://scm.gforge.inria.fr/anonscm/git/<forge_project>/<forge_project>.git (anonymous access) or https://<forge_user>@scm.gforge.inria.fr/authscm/<forge_user>/git/<forge_project>/<forge_project>.git (https developer access). Anonymous access is only available for public repositories. For https developer access you'll need to provide forge username and passsword for gitlab to be able to retrieve and import the project from the forge. It is not possible to use a git+ssh URL scheme for this method.

Filtering history

If needed, you can filter out part of the history before pushing it to the new gitlab git repository, with tools such as git-filter-repo, bfg-ish, BFG Repo Cleaner.

Mapping subversion / git committers to gitlab users

Git itself has no knowledge of forge / gitlab users. From git point of view, the author of a commit is a string Gitlab maps commit authors to gitlab users accounts with the git .mailmap file. It allows solving situations where a forge svn or git repository is migrated to gitlab and some users don't have the same username between the forge and the gitlab. It also allows solving situations where some users have committed with varying names/addresses during the life of the project.

Subversion / Git Hooks

Classic subversion or git hooks, implemented as executable in the hooks directories of the subversion or git server repositories, are not possible on the gitlab. So the usual email on subversion commit / git push has no direct equivalent. Gitlab has the concept of notifications, where this is the user who decides what he/she wants to be notified for. But git push are not part of the notified events. So the best equivalent of the email on commit/push is to activate "Emails on push" in the gitlab project integrations.

For other, more custom / advanced hooks usage, gitlab provides web hooks https://gitlab.inria.fr/help/user/project/integrations/webhooks.md

Forge Forums and mailing lists

There is no equivalent to forge forums or forge mailing lists. An alternative is to migrate both forge forums and mailing lists to the INRIA mailing lists server https://sympa.inria.fr/sympa.

migration of mailing lists users

To get the list of users of a forge mailing list: Point a browser to https://lists.gforge.inria.fr/mailman/roster/<listname>

To import this list of users in a https://sympa.inria.fr mailing list: got to "Add/delete subscribers" on the list page, then click "Multiple add" and copy/paste the list of email addresses

Forge Trackers

The equivalent to forge trackers are gitlab issues. The equivalent to having multiple trackers is to use issue labels. D. Vojtisek has contributed a script to help migrate trackers to gitlab: https://gitlab.inria.fr/sed-rennes/gforge-to-gitlab-scripts

Forge Tasks

One can use a combination of gitlab milestones and/or issue boards to manage the development.

Forge Documents, File Release System (FRS)

Forge Documents and File Release System are two tools with similar functionality: managing files. Gitlab is lacking a full equivalent. Since v8.2, there is a release functionality (https://about.gitlab.com/releases/2015/11/22/gitlab-8-2-released/#releases) and since 11.11 there is guest access to releases (https://about.gitlab.com/releases/2019/05/22/gitlab-11-11-released/#guest-access-to-releases). These have some limitations, as pointed in https://stackoverflow.com/questions/29013457/how-to-store-releases-binaries-in-gitlab. The most important limitations are that parts of the functionality can only be controlled by the API, and though releases can be removed, file attachments cannot. There is an open issue upstream regarding this feature: https://gitlab.com/gitlab-org/gitlab/-/issues/16229. Current up-to-date documentation can be found here: https://gitlab.inria.fr/help/user/project/releases/index

Forge News

No equivalent on gitlab

Forge Project Activity

The activity page of gitlab projects lists events such as pushes, merge request comments, issues.

Statistics

No direct equivalent in gitlab, but one should be able to compute many kind of custom statistics by using git itself (for the git repositories) or the gitlab API (for gitlab specific stuff).

Forge mediawiki

A wiki may be associated with each project in gitlab. The markup language is slightly different from mediawiki, though. When planning the migration of a wiki, you also need to handle attached files (images, etc.).

Forge Project Hierarchy

Gitlab groups are the alternative to Forge projects hierarchy, and they are actually more powerful and easy to use.

Forge Web Hosting

Web hosting in gitlab is done with gitlab pages. Gitlab pages can only serve static content, so this means no PHP (unlike the forge) or database. For example it is not possible to host a dokuwiki (which is php based). The generation of the pages is done with the same mechanisms as gitlab continuous integration. Any static site generator can be used (and there are templates for many). Gitlab pages are served over HTTPS but it has been decided that custom domains / certificates won't be activated.

A gitlab runner is needed to build gitlab pages. A gitlab runner is a server/VM/docker container running an agent and which can act as an executor for gitlab continuous integration jobs (and gitlab pages are a special case of gitlab continuous integration). As it is annoying for every project to setup a runner just for being able to publish a website, there is a work in progress to add shared runners to the inria gitlab. In the meantime, all projects requiring a runner for quick tasks like gitlab pages generation can ask to join the qlf-ci-gitlab-runner which provides such pseudo-shared docker runners.

We are currently evaluating the possibility to offer the possibility to redirect the web hosting of forge projects to new URLs.

Forge Shell Access

Not available in gitlab

Alternatives to INRIA gitlab

If you absolutely need a close equivalent to INRIA forge, RENATER SourceSup might be an alternative. It is based on FusionForge (like INRIA forge), offers git and subversion hosting, and is currently actively maintained. https://sourcesup.renater.fr/

Forge to Gitlab migration FAQ