What is GIT?
Git is a distributed version control system originally designed for development of the Linux kernel. It is mature and robust, and possesses some advanced features that other version-control systems are lacking, such as full distributed operation and strong guarantees of content integrity through the use of cryptographic checksums.
The git tools are installed as standard on all CSG Linux workstations and servers, and are used internally by CSG for code and content management and distribution functions.
What is GitLab?
GitLab is a GitHub-like flexible collaboration tool (based on Git, naturally) for projects with arbitrary members. Anyone in DoC can use GitLab, create projects, add other DoC members to their project (with particular levels of privilege), then push and pull changes to it. An easy way to add external collaborators to the system will be implemented in a few weeks. Find the gitlab server at:
Five minute guide to getting started with GitLab
Introduction:
This is a "5 minute guide to gitlab" for users within Imperial College London's Department of Computing. This guide covers the use of gitlab to share code or a project with one or more collaborators.
Part One: Logging in to gitlab.
To log into gitlab simply point a web browser to https://gitlab.doc.ic.ac.uk. A login screen will appear. Use the LDAP option to login using your username and your college password. You will arrive to your user homepage, called the "Dashboard". Clicking on the cat-raccoon icon in the upper right-hand side of the web page will allow you to return to your "Dashboard" from any location in the gitlab web interface.
Part Two: Adding an SSH key to gitlab.
In order to pull and push code to the repository you need to add an ssh key to your gitlab account. To do this, first create a ssh key (if you don't already have one):
1. create a rsa ssh key here at DoC, in your home directory. On any DoC linux machine do the following:
ssh-keygen -t rsa -C "$USER@imperial.ac.uk"
Choose a ssh pass word or phrase, different from (often longer than!) your ordinary password. Accept most of the keygen defaults and enter your fresh passphrase when asked. This creates ~/.ssh/id_rsa, a private key and ~/.ssh/id_rsa.pub, a public key. Never give the private key to anyone, treat it like a password.
2. Next, output the key to the terminal screen so that you can cut and paste it into your browser:
cat ~/.ssh/id_rsa.pub
Copy this key to your profile. Navigate to your profile by clicking on the person icon (a head and shoulders, a bust, whatever) in the upper right-hand corner of the Gitlab web page. In your profile page, click on the "Add Public Key" button. Cut and paste your ssh key from the terminal to the "Key" text field. Then press the button "Add key".
3. In order to push and pull code from gitlab, you will need to enter the password of the private key for each interaction unless you use an ssh-agent. To use an ssh-agent you need to initialise it on the "client end" (your local pc or laptop). Copy your SSH private key (~/.ssh/id_rsa) from your DoC home directory to your local machine, for example if your local machine runs Linux:
scp COLLEGEUSERNAME@shell4.doc.ic.ac.uk:.ssh/id_rsa ~/ssh/
Then do the following on your local Linux machine: Check for the existence of an ssh-agent, and to see if your private key has been loaded:
ssh-add -l [lists out the keys loaded into the agent]
If the output reports that no ssh-agent is currently running, then:
eval `ssh-agent` [start the ssh-agent]
# 'man ssh-agent' for more details. ssh-add ~/.ssh/id_rsa [enter your passphrase when you are prompted for it] ssh-add -l [lists out what keys are loaded in the agent]
4. Now the DoC gitlab server should let you use git commands with no password or phrase required, for the lifetime of that ssh-agent process. Logging out at the client end, or rebooting the client machine, will obviously terminate that ssh-agent and it's loaded key. On the other hand, be aware of the security implications - suppose ssh-agent is running on your laptop, with your key loaded in. If you suspend your laptop rather than shut it down, and it gets stolen, the thief could resume it - complete with the right to modify your git repo on gitlab, and ssh into DoC shell servers as you and delete/corrupt all your files. To avoid this, when you have finished using ssh-agent, you should probably destroy the agent and it's loaded keys via:
ssh-agent -k
If you run into problems, tell us precisely what you've done - and on which machine - and what files each step has created EXCEPT, please DO NOT send details of the private key. If you want to demonstrate that two files are the same, send us the ls -l and cksum output for both files.
Part Three: Creating a project in gitlab.
Any DoC user can create projects and groups and add other users to these. The creation of a project is achieved by clicking on the "+ New Project" button on the project tab located on the right of your screen. Follow the instructions on the screen, fill in the project name, and then give a short description. Once you create the new project, gitlab will give you some useful instructions to follow. Here is an example: Say that DoC user Julius Caesar (DoC login jc82, email julius.caesar@imperial.ac.uk ) would like to share his gitlab documentation project. The project name is gitlab_documentation, and it is in a directory of the same name. The first thing that Julius needs to do is perform some one time git configuration on his local machine:
git config --global user.name "Julius Caesar" git config --global user.email "julius.caesar@imperial.ac.uk"
Create a repository inside the project's directory:
cd gitlab_documentation git init touch README echo "Some interesting README notes" > README git add README git commit -m 'first commit' git remote add origin git@gitlab.doc.ic.ac.uk:jc82/gitlab_documentation.git git push -u origin master
Or, if the project exists inside a directory that is already under git control:
cd existing_git_repo git remote add origin git@gitlab.doc.ic.ac.uk:jc82/gitlab_documentation.git git push -u origin master
That is all that Julius has to do to start a DoC gitlab project. Note that customised versions of the above command sequences are shown in Gitlab immediately after you create a new repo.
Part Four: Sharing your code with someone.
To share your new project/code with someone go to the project page, and click on the "Settings" tab located on the second row of buttons on the top of the Gitlab page. This takes you to the Edit Project page. Click the Members button in the control bar on the upper left of the web page. You will now see two buttons in the upper right hand corner of the web page. With these buttons you can either include a single user to your project, or import members from another project to your own.
In order to share your project with another member of DoC, that person needs to:
-
Log onto the GitLab site. Go to their profile page (the icon in the upper right-hand corner of a head and shoulders).
-
Click on "Add Public Key". Find their public key (in ~THEM/.ssh/id_rsa.pub), or ask them to create one as per the instructions given above and then send it to you.
- Now copy and paste the public key into the field titled "Key".
- Add a title to the field referred to as "Title".
- Then (assuming that you have already added the member to your project), they can clone the project repository to their local working directory using:
git clone git@gitlab.doc.ic.ac.uk:<project owner>/<new-project>.git
where project owner is the username of the owner of the project, and new-project is the project name.
This information can also be found at the top of the project's web page. You can reach the project's web page by clicking on the project link found in the "Projects" tab on the right of your dashboard (click on the raccoon/cat icon on the top right-hand corner of the gitlab home page).
Part Five: Someone contributing to your code/project.
Once your collaborator has followed the instructions above and cloned your project into a directory on their local computer, they can then make changes, and add that to your project. Assume that the project is the gitlab_documentation project, and your collaborator has cloned that project to a directory called by the same name: "gitlab_documentation". In order to make changes, your collaborator will:
cd gitlab_documentation vim gitlab_documentation.txt # Make changes to an existing file.
git add gitlab_documentation.txt vim newfile.txt # Add a new file. git add newfile.txt # to add the new file. git commit # Add notes of the changes made.
git push # To push changes back to gitlab.
Then you can check your gitlab dashboard and see the update to the project. Other users can now:
git pull
From within their repository directories and start to work on the latest version of the code or project. The commands given are only the smallest subset of git. You must consult git documentation to better understand how to manage a git repository.
Part Six: Other users and groups.
DoC users can create external user (that is, non-College) accounts on the DoC Gitlab service via https://users.doc.ic.ac.uk. That web-site is only accessible within the College network or over VPN.
You can create a project, or several linked projects can be organised as a group. A group is created by clicking on the create new project button found in the upper right-hand corner of the Gitlab web page (The icon is in the shape of a plus sign, and is next to the head and shoulders icon we met earlier). The "New Project" page contains a button in the lower left-hand corner called "Create a group". Group members can have different levels of access to the code in the group based on Gitlab's permissions model. The model can be viewed at https://gitlab.doc.ic.ac.uk/help/permissions.
If you have any more queries or questions about the use of the DoC Gitlab service, please contact CSG at doc-help@imperial.ac.uk .
