Table of Contents

LRZ GitLab vs. LRZ GitLab CE

The following table presents the most important differences between the two instances. 

Visual distinction between the two instances

In addition to the different URLs, the two instances can be distinguished from each other by different favicons and a colored title bar in the Community Edition.
For users who frequently use both LRZ GitLab and LRZ GitLab CE, we also recommend using different color themes for better differentiation. The color theme can be changed by clicking on the profile picture -> Preferences -> Color theme -> Save changes.

Migration of projects and groups between LRZ GitLab and LRZ GitLab CE

There are two alternative methods to transfer projects and groups from one GitLab instance to another:

1. The classic method with project export files
2. The new method Migrate groups by direct transfer

The classic method is recommended when only a few projects need to be transferred. The necessary steps are:

1. Create a project export file on the source instance: Settings → General → Advanced → Export project
2. Download the created export file
3. Import the file on the destination instance: New project → Import project → GitLab export

The new method is according to GitLab still in beta stage, but is recommended when one or more groups with a large number of projects need to be transferred. The necessary steps are:

1. Create a personal access token with the api scope on the source instance: Edit profile → Access tokens → Add new token
2. Connect the source GitLab instance: On the destination instance choose New group → Import group → Import groups by direct transfer → fill in the URL and the personal access token → Connect instance
3. In the list of groups, choose the desired groups to be migrated (Source group) and their destinations (New group). Please note, that GitLab may automatically suggest a destination group in which case the source groups will be imported as subgroups within. To import as top-level groups please choose No parent as the destination.
4. Start the migration by choosing Import with projects. Please note that the process can take a lengthy amount of time.

Remarks:

• The information who has made which commits in the repository is preserved in the migration. In case the user account does not exist on the destination instance, the email address of the original committer will be shown next to the commit instead of a link to the user profile.
• Access rights in groups and projects will only be preserved when the user account exists on the destination instance and the email adress is defined as a public email on the source instance at the time of migration. A matching email address is the decisive factor for preserving the access rights - the usernames of the accounts are allowed to differ between the instances.

In case you encounter any problems during the migration, please contact us through the LRZ Servicedesk.

What happens to projects of deleted User IDs?

When a user's ID is deleted or the right to use GitLab removed, the user will be locked out of LRZ GitLab and will not be able to log in again. Projects and groups that belong to this user are still preserved for three months in GitLab and for three additional months in the backups (total 6 months). After that, they are permanently deleted.

If one or more groups or projects of the user are to remain active, they must be transferred to another active GitLab user before the User ID is deleted.

In order to keep a group active, simply enter another user in the member list of the group with the role owner. All the projects within the group will remain active as long as there is at least one active user as group owner.

If a user's personal project is to remain active, we recommend moving the project to a group. The group can also be created specifically for this purpose. The transfer takes place in the advanced settings of the project (Project Settings → General → Advanced → Transfer project). After moving the project to the group, please enter the still active GitLab user as one of the owners in the group or in the project. Alternatively, the project can be exported (Project Settings → General → Advanced → Export project) and the downloaded file passed on to the still active GitLab user who can import the project (New project/repository → Import project → Import project from GitLab export).

Please note: Adding another person as Maintainer in a personal project does not protect it from being deleted.

Especially in the case of public projects we recommend organizing the projects into groups.

Are projects backed up? How can I recover a deleted project?

LRZ generates daily backups of the complete GitLab instance. These backups are stored on a separate storage system and regularly checked for integrity. However, these backups only serve to restore GitLab after a critical error. The entire GitLab instance is reset to the time of the backup. Restoring individual projects during operation is currently not possible.

Recovering repositories that have been deleted by the user is possible within seven days, provided the project already exists in the backup. However, only the Git repository itself can be restored, whereas issues, merge requests and snippets will be lost after deleting the project.

Can I use two-factor authentication (2FA)?

Yes, LRZ GitLab supports two-factor authentication (2FA). When you log in, after entering your usual LRZ/TUM/LMU User ID and password you will be asked for an additional password. This can be generated either with an app such as privacyIDEA Authenticator installed on a smartphone or with a U2F device such as Yubikey. The use of 2FA is a voluntary possibility to increase the security of your GitLab account. 

To activate 2FA, select "Account → Enable two-factor authentication" in your GitLab account preferences. Then scan the displayed QR code using your app and enter the newly generated one-time password. GitLab automatically registers the app and shows a list of recovery codes. These codes should be kept in a safe place. They allow you to regain access to your account if, for example, you lose your smartphone and thus the app.

A U2F device can be registered on the same page in addition to the app as a second 2FA method. You can then use your device instead of the app. Unfortunately, it is not possible to register a 2FA device in GitLab without first registering an app.

Please note: The second 2FA-password is only asked when logging in on the LRZ GitLab website. If you have added an SSH key to your account, access using the key is still possible without additional passwords. Authentication on the command line (e.g. for cloning projects) using HTTPS is no longer possible after activating 2FA. Please add an SSH key to your account to access your repositories on the command line.

Detailed instructions are available on the GitLab website. 

If you have lost both your 2FA app or device and the recovery codes, please contact us through the LRZ Servicedesk.

What is the SSH key fingerprint of GitLab?

The first time you connect to GitLab from a terminal / command prompt on your PC (for example, if you want to clone a project or write changes to the repository), you will probably be asked for the authenticity of the host you want to connect to. The fingerprints of the LRZ GitLab can be found on its instance configuration page.

How can I access my project's container registry?

Before you can access your project's container registry, you will have to enable it in your project settings ("Settings" -> "General" → "Visibility, project features, permissions" -> "Container registry"). Now you should be able to find a new menu item named "Container Registry" in the menu bar on the left side under "Deploy". There you can find your project's images and their URLs. In case you do not have any images, you will find the URL to your project's container registry.

We recommend using access tokens to log in to the container registry. See below for a usage example for the command-line.

$ docker login gitlab-int.srv.lrz.de:5005 -u USERNAME -p TOKEN

You can find more information on this topic in the official GitLab documentation: GitLab Docs: Authenticate with the container registry (externer Link)

Can I collaborate with people on GitLab who do not have a LRZ/TUM/LMU User ID?

Yes, this is possible with GitInvited.

GitInvited was developed to give external cooperation partners access to GitLab. Each user who logs in to GitLab using an LDAP account (for example, LRZ, TUM, or LMU identifier) has a contingent of 20 invitations. These invitations can be sent to any email address via GitInvited. The email address must not be registered in GitLab prior to the invitation. 

User accounts created through this method have the status external user in LRZ GitLab. That means among other things, that they are not able to create their own projects or groups. See GitLab Permissions Dokumentation for details.

The user who sent the invitation (hereinafter referred to as the "Parent User") is linked to the invited user ("Child User") in the GitInvited database. This ensures that external users can be contacted by LRZ through their Parent Users.

If a Parent User is blocked in GitLab (for example because their ID has expired), all Child Users they are responsible for will also be blocked. This can only be prevented if those users are migrated to a new Parent User. This can only be done by the GitLab administrators. Please ask the new Parent User to contact the LRZ Servicedesk.

Although GitInvited and GitLab can be reached under different URLs, the services communicate with each other. When logging in for the first time, you will be redirected between the applications via the OAuth login procedure.

How can I reduce the size of my repository?

If your project includes large or very dynamic files, the Git repository can get large. This not only affects the storage space and download times, but also causes additional load on our servers. Especially if you work with binary files and have forgotten to activate the Git Large File Storage (LFS), reducing the size of the repository is often necessary. The size of the project including the repository and LFS files is displayed on the project page. Rule of thumb: If the repository is larger than 1 GB without Git LFS, its size should be reduced.

Unfortunately, it is not enough to simply delete unnecessary files in the project directory. This doesn't make the repository smaller because the old versions of the files are still managed in Git.

Method 1: Recreating the project

The simplest and in most cases the recommended method is to recreate the project and to make sure that binary files are managed using Git LFS:

1. Create a new, empty project (New Project → Blank project → <Fill in the project name and select "Initialize repository with a README">)
2. Clone the new Projekt
   git clone https://gitlab.lrz.de/username/new-project-with-lfs.git
   (or via SSH: git clone git@gitlab.lrz.de:username/new-project-with-lfs.git)
3. Copy files from the old project to the new project (without the .git/ directory)

4. Initialize Git LFS and activate LFS tracking for binary files:
   git lfs install
git lfs track '*.jpg'
git lfs track '*.zip'
git lfs track 'my_binary_data_file'
   ... additional lfs track commands for other files and data types if necessary ...

5. Upload the files to GitLab
   git add .
git commit -m "Initial commit"
git push

6. Delete the old project (Settings → General → Advanced → Remove project) 

This method will not preserve the version history of the files and associated, commit messages, branches and issues.

Method 2: Rewriting the version history

If the availability of the previous versions of the files, commit messages and/or branches of the project is important, this somewhat more complex method can be used. In this method the version history is partially rewritten with tools such as git-filter-repo or BFG Repo Cleaner. For example, source code files can be retained with their entire versioning while old versions of the large binary files are deleted. The details of how to use these tools depend on how the files are organized in the project. Below is an example of how the steps in this method may look like:

1. Clone the existing project using the option "mirror"
   git clone --mirror https://gitlab.lrz.de/username/the-big-project.git
(or via SSH: git clone --mirror git@gitlab.lrz.de:username/the-big-project.git)
   Note: In case your project already contains LFS files, they will not be cloned through this command and must be manually added in step 5.
2. Delete selected files and folders using git-filter-repo. In our example the contents of the folder data as well as jpg- and zip-files will be removed from the project and its history. For details, please consult the documentation of the tools.
   cd the-big-project.git
git-filter-repo --use-base-name --path-glob '*.jpg' --path-glob '*.zip' --invert-paths
git-filter-repo --path data/ --invert-paths
3. Upload the modified repository to a new project
   git push --mirror https://gitlab.lrz.de/username/new-project-with-lfs.git
   Clone the new project (without option "mirror"):
4. cd ..
git clone https://gitlab.lrz.de/username/new-project-with-lfs.git
cd new-project-with-lfs

5. Copy selected binary files and directories from the old project to the new project (without the .git / directory and the files that already exist in the new project repository).
6. Initialize Git LFS and activate LFS tracking for binary files:
   git lfs install
git lfs track '*.jpg'
git lfs track '*.zip'
git lfs track 'my_binary_data_file'
   ... additional lfs track commands for other files and data types if necessary ...
   Note: If you have multiple branches in your repository, please make sure that Git LFS is properly initialized in all branches.
7. Upload the files to GitLab
   git add .
git commit -m "Adds some data files"
   git push
8. Delete the old project (Settings → General → Advanced → Remove project)

With this method, the versioning of files, branches and tags are retained. Branch requests on the GitLab web interface are lost, but because branches still exist, new branch requests can be easily created. Issues, comments, snippets and other content that is not part of the Git repository itself but is stored in the GitLab database are not retained.

Issues can be exported separately as CSV files and re-imported into the new project. However, comments in the issues are not retained.

Important: Also when using this method please make sure to create a new project with a new path and push the new size-reduced repository there. If you push it over the old project, the old versions of the files will still be retained as internal references on the server.

(For advanced users there is a method described on the GitLab page which rewrites the repository within the project and thus preserves all other data such as issues, comments, etc. as well as the original path. It's relatively complicated and we don't recommend it unless you are experienced with Git and GitLab. If you want to try this method, please ensure that all steps, including the repository cleanup with the commit.map file, are carried out. Furthermore it is important that all members of the project delete their local copies and re-clone the project. Otherwise their next git push will upload the old versions of the files, commits etc. back to the GitLab which will lead to a chaos.)