School of Computing Science Gitlab Platform - User Notes Contents Using Git & Gitlab... 1 Introduction... 1 Access Methods... 2 Web Access... 2 Repository Access... 2 Creating a key pair... 2 Adding a key to gitlab... 2 Set Identity information... 3 New Git Projects... 3 Adding a new user... 5 Using Git & Gitlab Introduction 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. Contact cs-support@ncl.ac.uk 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. 1
Access Methods Web Access Access to browse and edit through the web interface of Gitlab can be performed by any user with a valid account. These include locally created users with a password stored in the internal Gitlab data, Campus domain users (mostly, but not exclusively) we've batch-added within the import script and external users we've authorised via the Google social authentication plugins. 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. Repository Access 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. Creating a key pair In a windows system, we recommend the use of PuTTYGen (Figure 2) to generate a key pair. This is included in the Computing Science Portable Apps (CSPA) collection in the Communications group. 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 with the command ssh-keygen -y -f <privatekey> Figure 1 Gitlab Kerberos sign in Adding a key to gitlab 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 Figure 2PuTTY Gen 2
located on the SSH Keys tab of the user profile (which is available from the head and shoulders icon (Figure 3). Figure 3 Gitlab tool bar Set Identity information 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: git config --global user.name "John Snowdon" git config --global user.email "john.snowdon@newcastle.ac.uk" 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 Internal Public Only users or groups who have been given explicit access can access or clone it. Any users who have an account on Gitlab can access and clone it. 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. Issues Although all the standard Unix-based systems (Linux, OS X, etc) support SSH key generation with builtin tools, not all Microsoft Windows clients will. 3
One desktop client that does support SSH natively is Eclipse1, 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. Command Line Tools & IDE Create Empty Structure 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 git@gitlab.ncl.ac.uk: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. Importing Subversion Repositories 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. Tools There are a number of methods to migrate Subversion-based repositories to Git that can be found via Google2, 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. 4
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. Adding a new user 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. 5