GitlabUserGuide Page History
The school of Computing Science provides a self-service gitlab server which is hosted entirely on campus using the replicated virtual machine service for reliability. Staff and students in Computing Science can automatically create a limited number of projects (repositories) each. This number can be increased and non-CS users added if needed. Raise a support with NUService ticket to do this.
This guide is intended as an introduction to our gitlab installation, not an introduction to git or to version control in general. There are many documents online covering the latter topics.
Access to browse and edit through the web interface of Gitlab can be performed by any user with a valid account. Campus domain based accounts are created for everyone associated with the School of Computing. Other users can be authorised on request to NUService. Most university users will use their campus login credentials via the Kerberos login button (Figure 1). The web interface (https://gitlab.ncl.ac.uk/) is available both internally and externally to the university.
Access to Git repositories via command line tools or IDE applications is via internal Gitlab database password or SSH key only. At the point an application wants to speak the Git protocol to the Gitlab server, it is no longer communicating with the Gitlab web application, but the Git binary itself. Git does not know anything about Kerberos or Google authentication, so those methods that we used for connecting to the web interface are not supported at this low level. This means that for all practical purposes, access to Git for development use requires an SSH public/private key pair.
In a windows system, we recommend the use of PuTTYGen (Figure 2) to generate a key pair.
This is installed on all school-managed windows systems. The key should be a 2048(minimum) RSA key. The current gitlab installation does not support elliptic curve keys. The key should be given a passphrase. The OpenSSH format public key (a single line starting “ssh”) is in the correct format to paste into gitlab. In a Linux/Unix session, use the ssh-keygen program which will prompt for a filename prefix in which to store the key pair. The public key in OpenSSH format can be generated from this with the command:
ssh-keygen -y -f <privatekey>
The public part of the generated key pair is then uploaded to the list of keys associated with your user account in gitlab. This is located on the SSH Keys tab of the user profile (which is available from the head and shoulders icon (Figure 3):
It is important that the client used to access a repository has the correct user name and account associated with you, so that when your files are merged back with the master copies held in Gitlab, the details about who has worked on them is preserved and can be mapped to the user data held in the Gitlab internal database. The name and email must always be set in full, any deviation from the guidance shown by Gitlab may cause lookup of user information in the web interface to fail. Gitlab users your full email name (First.Last@newcastle.ac.uk) for this. TortoiseGit (for windows) will prompt for this on first use, or this can be set with the settings option in the context (right-click) menu in File Explorer. The command line git client (Linux) has a config sub command to do this (clearly substituting your own details):
git config --global user.name "John Doe" git config --global user.email "firstname.lastname@example.org"
##New Git Projects
At the point a new project is created in Gitlab, guidance is shown on-screen to instruct the user how to initialise the repository and begin adding contents. Access to groups and their projects is, of course, subject to the privacy settings that have been declared on those projects. The levels of access are:
|Private||Only users or groups who have been given explicit access can access or clone it.|
|Internal||Any users who have an account on Gitlab can access and clone it.|
|Public||Anyone who is given the URL of the project can access and clone it.|
The sequence of operations is to load an existing private key (or generate a new one), entering or setting a passphrase as appropriate. The Save public key generates a file in an encoded form suitable for use in a linux/unix native client. The text-format key at the top of the Key Generator window is in the correct format to be pasted into the Key upload window. This needs to be a single line, so use the right-click menu to select all and copy the contents.
Although all the standard Unix-based systems (Linux, OS X, etc) support SSH key generation with built-in tools, not all Microsoft Windows clients will. One desktop client that does support SSH natively is Eclipse, so as a Git client / IDE for Windows, that would be the one that requires the least amount of additional software to allow key based authentication to Git. For those users not using Eclipse, and on a Windows desktop PC, some (easy, and scalable) method for generating SSH keys needs to be found. Having the support team generate them on individual users' behalf would not seem to be a sensible option.
Git does not impose any structure or content to a new repository – it is up to the user themselves to initialise the folder structure and start adding files. Gitlab recommends the following procedure which creates a new empty Git project on your local machine, then connects it to Gitlab, merging the (new) structure as it is then pushed back up:
mkdir cs-team-tools cd cs-team-tools git init touch README git add README git commit -m "first commit" git remote add origin email@example.com:cs-support-group/cs-team-tools.git git push -u origin master
As long as you are using the standard git binary and the private key half of the SSH key you added to your Gitlab profile is in the normal location (~/.ssh/keyname), the push operation should run without the need for any username or password. In fact, you will be unable to enter a username or password, due to the issues mentioned in the previous Command Line Tools section.
There is a marked difference in the methodology between Subversion and Git; the former is a centralised version control system, whereas the latter is, by its very nature, decentralised. Still, migrating Subversion to Git is a popular subject and a task that many will often want to do so that over time only a single platform is needed.
There are a number of methods to migrate Subversion-based repositories to Git that can be found via Google, many of these using the 'git-svn' bridge command. The Git project itself also has documentation3 dedicated to the subject.
However, the general principle is a long, multi-stage process, so a number of projects have sprung up to attempt to automate most of the work required. One of the easiest systems to use is svn2git, itself available on Github4.
Svn2git is a ruby programme; it needs 'rubygems' installed (specifically the 'gem' command) and installs itself via the usual Ruby installation command:
gem install svn2git
As part of the install process a number of dependencies will also be pulled in.
Additional users can be made members of a project by the project owner with various levels of access:-
|Guest||Can only raise issues and leave comments.|
|Reporter||Effectively read access.|
|Developer||Update a project’s content.|
This is done in the project settings using the Members tab. There are more details in gitlab at https://gitlab.ncl.ac.uk/help/permissions/permissions.md External users who use their google account to authenticate can also be granted access to a repository. The first time that they need this, the user should invite them to self-register and then raise a support ticket to ask for the specific account to be unblocked.