|
|
[[_TOC_]]
|
|
|
|
|
|
# FAQ Migration from INRIA Forge to INRIA Gitlab
|
|
|
|
|
|
## Planning the migration
|
|
|
# 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
|
|
|
## 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
|
|
|
## Preventing project members from commiting / pushing
|
|
|
|
|
|
Send a [Helpdesk](https://helpdesk.inria.fr/) ticket, "Submit an IT request -> Service request -> Services for research -> Request for Gitlab", to ask administrators to add a pre-commit hook.
|
|
|
|
|
|
#### Subversion
|
|
|
### Subversion
|
|
|
|
|
|
Add a pre-commit hook which always returns false. For example:
|
|
|
|
... | ... | @@ -26,7 +24,7 @@ echo -e '#!'"/bin/bash\necho \"This repository is read-only\"\nexit 1" > /svnroo |
|
|
chmod a+x /svnroot/<project unix name>/hooks/pre-commit
|
|
|
```
|
|
|
|
|
|
#### Git
|
|
|
### Git
|
|
|
|
|
|
Add a pre-receive hook which always returns false. For example:
|
|
|
|
... | ... | @@ -36,7 +34,7 @@ echo -e '#!'"/bin/bash\necho \"This repository is read-only\"\nexit 1" > /gitroo |
|
|
chmod a+x /gitroot/<path_to_git_server_repo>/hooks/pre-receive
|
|
|
```
|
|
|
|
|
|
## Available documentation and help
|
|
|
# Available documentation and help
|
|
|
|
|
|
The gitlab documentation is available here: https://gitlab.inria.fr/help
|
|
|
|
... | ... | @@ -56,7 +54,7 @@ There are cheat sheets with basic equivalence, such as [this one](http://www.che |
|
|
|
|
|
To better understand git concepts, you can for example have a look at [Anthony Baire tutorials](http://people.irisa.fr/Anthony.Baire/)
|
|
|
|
|
|
## Gitlab project setup
|
|
|
# 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)
|
|
|
|
... | ... | @@ -66,7 +64,7 @@ Project name and user names do need necessarily need to be the same between gfor |
|
|
|
|
|
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
|
|
|
# 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.
|
|
|
|
... | ... | @@ -74,17 +72,17 @@ You need to decide if you want to migrate just the tip of your development histo |
|
|
|
|
|
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
|
|
|
## 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
|
|
|
## Migrating the whole (or part of the) history
|
|
|
|
|
|
#### From Subversion
|
|
|
### From Subversion
|
|
|
|
|
|
##### Command-line git-svn method
|
|
|
#### Command-line git-svn method
|
|
|
|
|
|
###### Handling of branches and tags
|
|
|
##### Handling of branches and tags
|
|
|
|
|
|
In subversion, branches and tags are kind of symlinks to snapshots of the development history. They can be put anywhere in the repository directory hierarchy, but usually it is advised to gather them in specific directories, and the recommended best practice is the standard layout of three top directories in the subversion repository: `trunk` (main development tree), `tags`, `branches`.
|
|
|
|
... | ... | @@ -92,7 +90,7 @@ By default git-svn just clones the repository 'as-is', (you'll end up with a mig |
|
|
|
|
|
But you almost always want to convert subversion branches and tags. git-svn takes options to set the directories for branches and tags. If your subversion repository has the classic standard layout structure, you can use the shorthand option `--stdlayout` to convert all svn branches in `branches` and all svn tags in `tags` to git branches (if your repository has a non standard layout, there are options to instruct git-svn of the layout, see git-svn documentation).
|
|
|
|
|
|
###### git-svn command
|
|
|
##### git-svn command
|
|
|
|
|
|
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:
|
|
|
|
... | ... | @@ -117,7 +115,7 @@ git clone git@gitlab.inria.fr:<gitlab_user>/<gitlab_project>.git |
|
|
cd <gitlab_project>
|
|
|
# check that all is correct
|
|
|
```
|
|
|
###### Post-processing for branches and tags
|
|
|
##### Post-processing for branches and tags
|
|
|
|
|
|
git-svn by default puts all subversion branches and tags in remote branches pointing to the original subversion repository, because git-svn is bi-directional, you can push to the svn repo. But in our case, let's say that:
|
|
|
* we want to migrate to git once and for all
|
... | ... | @@ -158,13 +156,13 @@ git push --force -u origin --all |
|
|
git push --force -u origin --tags
|
|
|
```
|
|
|
|
|
|
##### Alternative methods
|
|
|
#### Alternative methods
|
|
|
|
|
|
Other methods are described here: https://gitlab.inria.fr/help/user/project/import/svn
|
|
|
|
|
|
#### From Git
|
|
|
### From Git
|
|
|
|
|
|
##### Command-line mirror method
|
|
|
#### Command-line mirror method
|
|
|
|
|
|
A convenient way to migrate everything (all branches, all tags) in a single operation is to use a mirror checkout:
|
|
|
|
... | ... | @@ -185,101 +183,101 @@ cd <gitlab_project> |
|
|
# check that all is correct
|
|
|
```
|
|
|
|
|
|
##### Gitlab import method
|
|
|
#### 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
|
|
|
### 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](https://github.com/newren/git-filter-repo), [bfg-ish](https://github.com/newren/git-filter-repo/blob/master/contrib/filter-repo-demos/bfg-ish), [BFG Repo Cleaner](https://rtyley.github.io/bfg-repo-cleaner/).
|
|
|
|
|
|
#### Mapping subversion / git committers to gitlab users
|
|
|
### 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](https://git-scm.com/docs/git-check-mailmap). 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
|
|
|
# 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
|
|
|
# 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
|
|
|
## 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>```](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
|
|
|
|
|
|
### migration of mailing lists archive
|
|
|
## migration of mailing lists archive
|
|
|
|
|
|
If you need to transfer ML archives from InriaForge to Sympa INRIA mailing lists server:
|
|
|
* You need to create the sympa mailing list beforehand
|
|
|
* You need to be admin of both the InriaForge and the Sympa mailing lists
|
|
|
* Submit a ticket, indicating both mailing lists names, on InriaForge and on Sympa (they may be the same or different)
|
|
|
|
|
|
## Forge Trackers
|
|
|
# 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
|
|
|
# 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, 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
|
|
|
# Forge News
|
|
|
|
|
|
No equivalent on gitlab
|
|
|
|
|
|
## Forge Project Activity
|
|
|
# Forge Project Activity
|
|
|
|
|
|
The activity page of gitlab projects lists events such as pushes, merge request comments, issues.
|
|
|
|
|
|
## Statistics
|
|
|
# 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
|
|
|
# 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
|
|
|
# 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
|
|
|
# Forge Web Hosting
|
|
|
|
|
|
There are several INRIA alternatives to the forge web hosting, depending on the needs:
|
|
|
|
|
|
### Wordpress hosting for INRIA Teams websites
|
|
|
## Wordpress hosting for INRIA Teams websites
|
|
|
https://team.inria.fr/
|
|
|
|
|
|
### Wordpress hosting for projects in general (research projects, collaborations)
|
|
|
## Wordpress hosting for projects in general (research projects, collaborations)
|
|
|
https://project.inria.fr/
|
|
|
|
|
|
### Static files storage
|
|
|
## Static files storage
|
|
|
https://wiki.inria.fr/support/Espace_web
|
|
|
It is intended to store static files served with http. It is accessible with webdav, so it's possible to setup automated rsync to this place. The documentation says that it's intended only for static files needed by another website, but we had confirmation that it's possible to host a full static web site.
|
|
|
|
|
|
### gitlabpages
|
|
|
## gitlabpages
|
|
|
Gitlab includes 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. A [gitlab runner](https://docs.gitlab.com/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](https://gitlab.inria.fr/inria-ci/qlf-ci-gitlab-runner) which provides such pseudo-shared docker runners.
|
|
|
There is an example project showing how to setup gitlabpages here: https://gitlab.inria.fr/siteadmin/pages-example
|
|
|
|
|
|
One point worth noting is that contrary to previously, INRIA has decided that a team website has URL <team name>.inria.fr and nothing except teams can have such inria subdomains. Therefore, it has been decided that custom domains / certificates are disabled in gitlab-pages. It means that it is not possible to alias a DNS name to a gitlab-pages website.
|
|
|
|
|
|
### Other options
|
|
|
## Other options
|
|
|
It is also possible to move forge websites to non-INRIA hosting.
|
|
|
|
|
|
### maintaining old URLs pointing to resources on gforge web hosting
|
|
|
## maintaining old URLs pointing to resources on gforge web hosting
|
|
|
We are currently evaluating the possibility to offer the possibility to redirect the web hosting of forge projects to new URLs.
|
|
|
|
|
|
## Forge Shell Access
|
|
|
# Forge Shell Access
|
|
|
|
|
|
Not available in gitlab
|
|
|
|
... | ... | |