User Tools

Site Tools


Sidebar

Navigation

public:help:gitlab

GitLab

Page Disambiguation

This page gives you a some informations you need to work with the gitlab environment on the EnterpriseLab.
The official documentation of what GitLab is can be found here: https://about.gitlab.com/what-is-gitlab/

Start with Gitlab

Gitlab is accessible on the following URL: gitlab.enterpriselab.ch

Login for the first time

You will need an EnterpriseLab Account for gitlab.

To create a login in the EnterpriseLab environment, visit eportal.enterpriselab.ch and log in with your AAI credentials. Click on create an account and set your Enterprise Lab password. For more help on this step read this help page.

Sign in on gitlab.enterpriselab.ch with your LDAP EnterpriseLab Login and the EnterpriseLab password

Configure your Profile

SSH Keys

You won't be able to pull or push project code via SSH until you add an SSH key to your profile.

So you have to add your public key into your gitlab Profile.

Profile Settings → SSH Keys → Add SSH Keys

An advanced documentation of this procedure, including how to create a SSH Key can be found on http://doc.gitlab.com/ce/ssh/ssh.html

GitLab Projects

Create a Project

If you want to create a new Project click on the "+" Sign on page headline.

Projectname - out of this information will a URL be created

gitlab.enterpriselab.ch/%USERNAME%/%PROJECT-NAME%

gitlab.enterpriselab.ch/%GROUP-NAME%/%PROJECT-NAME%

Namespace - You assign this project to a group or your own workspace

as mentioned before, the selected namespace will also specify the URL

Visibility Level

  • Private - Only accessible for invited users
  • Internal - Accessible for all logged in users
  • Public - Accessible for all users including unauthenticated users

Understanding Visibility Levels

More information about the visibility level can be found here: Public Access

Additional information about the users permissions can be found here: Permissions

Project templates can pre-populate your new project with necessary files to get you started quickly for a certain type of project, like a Java Spring application for example.
A special type of project template are the GitLab Pages templates which allow you to host static websites on GitLab. Learn more here: Hosting a static web page on GitLab

Create a Group

A Group can be used if you are a team, and you have different projects you are working on together. The biggest benefit is, you don't have to assign permissions for all project members, on every new created project.

Another benefit is, you can still give additional permissions on every project in a group.

If you assign a user different permissions on group and project level, always the higher permission level will be used.

Create a Group

You can create a new group on the new Project site. On the right bottom is a button "Create a group".

There is also a possibilty on Profile Settings → Groups → "+ New group"

or on the right side of the dashboard → Groups → "New group"

Groups will have an other URL than user projects. gitlab.enterpriselab.ch/%GROUP-NAME%/%PROJECT-NAME%

Granting Permissions to other users

  • Go to your gitlab repository an click on "Settings".
  • On the left pane select "Members".
  • Click on "New project member

Now you can search for your project members and add them into your repository. (A new project member can only be found, if he has already logged in once into gitlab)

Give them the correlated access permission.

  • Guest - can clone a repository
  • Reporter - can pull code into the repository
  • Developer - can pull code, create banches, merge request…
  • Master - can nearly do the same thing like an owner of the repository

A complete permission documentation can be found here: Permissions

Import existing Git Repos

If you already have a git repository, which is located on another git Service (e.g. git.enterpriselab.ch), you have do to the following steps to transfer it to the new gitlab.enterpriselab.ch service

Import existing repo

Dont use the Option "Import existing repo" in the "new Project" dialog, you have to send your password in plain text, so its not very secure.

Download the latest version of the git repository on the old location

me:test-sandro Sandro$ git clone thbachma@git.enterpriselab.ch:thbachma/test-sandro.git

Check where this repository is located

me:test-sandro Sandro$ git remote -v
origin	thbachma@git.enterpriselab.ch:thbachma/test-sandro.git (fetch)
origin	thbachma@git.enterpriselab.ch:thbachma/test-sandro.git (push)

Remove the locations

me:test-sandro Sandro$ git remote rm origin

Add the new location

me:test-sandro Sandro$ git remote add origin git@gitlab.enterpriselab.ch:thbachma/test-sandro.git

Check if the repository is now located on the new gitlab service

me:test-sandro Sandro$ git remote -v
origin	git@gitlab.enterpriselab.ch:thbachma/test-sandro.git (fetch)
origin	git@gitlab.enterpriselab.ch:thbachma/test-sandro.git (push)

Now you can push the local files to the gitlab.entepriselab.ch service

me:test-sandro Sandro$ git push -u origin master

On the gitlab.entepriselab.ch website you should now see the files in your project folder

Scenarios

Single user project

  • New project
  • Namespace → User
  • Visibility Level → Private

Multi user project

  • New project
  • Namespace → User
  • Visibility Level → Private
  • Add project members and assign permissions

Workgroup with different projects

  • Create a Group
  • Add members to the group
  • Create project within the group
  • Namespace → Group
  • Visibility Level → Private

BDA/PAWI Projects

  • New project
  • Namespace → User
  • Visibility Level → Private
  • Add teacher and assign "Reporter" permission

Open Project inside HSLU

  • New project
  • Namespace → User
  • Visibility Level → Internal

Open Project

  • New project
  • Namespace → User
  • Visibility Level → Public

Educational Repository Creation Workflow

Draft

Access to the API

If you want to access Gitlab via the API use following command: You can find your private token in your profile-settings under account.
API: GET /users/:ID

curl --header "PRIVATE-TOKEN: XXXXXXXXXXXXXX" https://gitlab.enterpriselab.ch/api/v4/users/382

Clean the history

If you don't need the history anymore, have multiple changed big files in the history or something has gone wrong you can start from scratch:

# create temporary branch on "first commit" with hash e.g. b7c85f5 <- change it
git checkout b7c85f5 -b tmp

# merge with latest revision of branch "master" 
git merge master

# reset head pointer to the "first commit" (e.g. b7c85f5) (diffs to the latest revision are now uncommitted in stash)
git reset b7c85f5

# commit the changes between "first commit" and actual revision
git add -A
git commit -m "Purge history"

# force overwrite remote branch (here master) with tmp branch
git push origin -f tmp:master

# overwrite the local branch and cleanup the local temporary branch
git checkout master
git pull origin -f master:master
git branch -D tmp

Oops… I spelled that last commit message wrong

After a good few hours of coding, it's easy for a spelling error to sneak into your commit messages. Luckily, there's a simple fix.

git commit --amend

This will open up your editor and allow you to make a change to that last commit message. No one needs to know you spelled, "addded" with three "d"s.

Oops… I forgot to add a file to that last commit

Another common Git pitfall is committing too early. You missed a file, forgot to save it, or need to make a minor change for the last commit to make sense. –amend is your friend once again.

Add that missed file then run that trusty command.

git add missed-file.txt
git commit --amend

At this point, you can either amend the commit message or just save it to keep it the same.

Oops… I added a file I didn't want in the repo

But what if you do the exact opposite? What if you added a file that you didn't want to commit? A rogue ENV file, a build directory, a picture of your cat that you accidentally saved to the wrong folder? It's all fixable. If all you did was stage the file and you haven't committed it yet, it's as simple as resetting that staged file:

git reset /assets/img/misty-and-pepper.jpg

If you've gone as far as committing that change, you need to run an extra step before:

git reset --soft HEAD~1
git reset /assets/img/misty-and-pepper.jpg
rm /assets/img/misty-and-pepper.jpg
git commit

This will undo the commit, remove the image, then add a new commit in its place.

Oops… I committed all those changes to the master branch

So you're working on a new feature and in your haste, you forgot to open a new branch for it. You've already committed a load of files and now them commits are all sitting on the master branch. Luckily, GitLab can prevent you from pushing directly to master. So we can roll back all these changes to a new branch with the following three commands:

git branch future-brunch
git reset HEAD~ --hard
git checkout future-brunch

This creates a new branch, then rolls back the master branch to where it was before you made changes, before finally checking out your new branch with all your previous changes intact.

Oops… I made a spelling mistake in my branch name

The keen-eyed among you will notice a slight spelling error in my last example. It's almost 3:00 PM and I haven't had lunch yet, so in my hunger, I've named our new branch future-brunch. Delicious. We rename this branch in a similar way to how we rename a file with the mv command: by moving it to a new location with the correct name.

git branch -m future-brunch feature-branch

If you've already pushed this branch, there are a couple of extra steps required. We need to delete the old branch from the remote and push up the new one:

git push origin --delete future-brunch
git push origin feature-branch

Oops… I did it again

This command is for when everything has gone wrong. When you've copy-pasted one too many solutions from Stack Overflow and your repo is in a worse state than it was when you started. We've all been there.

git reflog shows you a list of all the things you've done. It then allows you to use Git's magical time-traveling skills to go back to any point in the past. I should note, this is a last resort thing and should not be used lightly. To get this list, type:

git reflog

Every step we took, every move we made, Git was watching us. Running that on our project gives us this:

3ff8691 (HEAD -> feature-branch) HEAD@{0}: Branch: renamed refs/heads/future-brunch to refs/heads/feature-branch
3ff8691 (HEAD -> feature-branch) HEAD@{2}: checkout: moving from master to future-brunch
2b7e508 (master) HEAD@{3}: reset: moving to HEAD~
3ff8691 (HEAD -> feature-branch) HEAD@{4}: commit: Adds the client logo
2b7e508 (master) HEAD@{5}: reset: moving to HEAD~1
37a632d HEAD@{6}: commit: Adds the client logo to the project
2b7e508 (master) HEAD@{7}: reset: moving to HEAD
2b7e508 (master) HEAD@{8}: commit (amend): Added contributing info to the site
dfa27a2 HEAD@{9}: reset: moving to HEAD
dfa27a2 HEAD@{10}: commit (amend): Added contributing info to the site
700d0b5 HEAD@{11}: commit: Addded contributing info to the site
efba795 HEAD@{12}: commit (initial): Initial commit

Take note of the left-most column, as this is the index. If you want to go back to any point in the history, run the below command, replacing {index} with that reference, e.g. dfa27a2.

git reset HEAD@{index}

Git LFS

Git is a distributed version control system, meaning the entire history of the repository is transferred to the client during the cloning process. For projects containing large files, particularly large files that are modified regularly, this initial clone can take a huge amount of time, as every version of every file has to be downloaded by the client. Git LFS (Large File Storage) is a Git extension developed by Atlassian, GitHub, and a few other open source contributors, that reduces the impact of large files in your repository by downloading the relevant versions of them lazily. Specifically, large files are downloaded during the checkout process rather than during cloning or fetching. Git LFS does this by replacing large files in your repository with tiny pointer files. During normal usage, you'll never see these pointer files as they are handled automatically by Git LFS.

Please keep in mind that a BLOB-file has a maximum of 1GB.

Git and undifferentiable files

LFS doesn't make your repository smaller or magicaly change the behaviour of git. Commit these files only if it's really neccessary.

Install Git LFS

On Ubuntu you have to add an additional repository before you can install git-lfs:

sudo add-apt-repository ppa:git-core/ppa
curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash
sudo apt-get install git-lfs

Note: Info for ppa
https://github.com/git-lfs/git-lfs/wiki/Installation

Settings on Gitlab

The LFS-feature is deactivated by default in the project settings. Change it in the project-settings-general-permissions tab. :WARNING: At the moment (feb 2018) there is an open issue, that the setting isn't visible to a non-admin user. If you want to use this feature, contact a member of the Enterprise Lab team.

Settings in your development environment

Check if your git lfs Version >= 1.01

git lfs version

In the project directory do once:

git lfs install

You need for every file or wildcard extension a track command:

git lfs track template-list

This adds or ammends an existing .gitattributes file. After that add the files and commit as usual.

Display what lfs is tracking:

git lfs track

IMPORTANT! You have to add the .gitattributes file to you repo. Otherwise gitlab doesn't know anything about your desired trackings.

git add .gitattributes

You can show all large storage files with this command:

git lfs ls-files

You cannot convert existing files in a repo to lfs. Only new files can be tracked. When you commited and pushed everithing, a LFS-symbol is shown next to the filename on gitlab's project-website. You shouldn't add the same testdata-lfs-file to every algorithm-variant-project. Use it as a test-data-repository, work with branches or tags and link it to your project-folder. This saves storage and helps us to ensure the backups.

Problems

Error 500 after project transfer

Our setup at the intern-gitlab doesn't allow gitlab to rename a namespace. It will try but the process can't be finished. Every time when this old project should be displayed the error 500 will rise.

You (the admin) have to do the following steps:

  • Login to Gitlab's web GUI
  • Make sure the project is deleted
  • Login to the nas02 and navigate to the namespace (/export/dev/intern-gitlab/repositories/…) and make sure it's empty.
  • destroy the zfs dataset (zfs destroy dpool1/dev/intern-gitlab/repositories/vm2-hs17)
  • on the new destination check if the files are there
  • if yes delete that folder too (if it's older than a day, it has been converted to a dataset too)

Unable to push

If you get an error during the push action like this, your quota is exceeded. Write a ticket to increase yout git quota including the full path of the repo.

error: unpack failed: unable to create temporary object directory
...
error: failed to push some refs to ..

Unable to push or pull through ssh

If you can't push through ssh (git@gitlab.enterpriselab.ch:…) it is possible that you are banned, because of too many retries. We use fail2ban. Wait 10 minutes and try again. If you still can't use it after this time, write a ticket to the Enterprise Lab team.

Sources

public/help/gitlab.txt · Last modified: 2019-07-14T11:52+0200 by job