log in | SSH | repository creation | basics | sharing | migration | groups | rules | references

GitLab

GitLab is a web-based Git repository management similar to GitHub. Besides repository (called "project" in GitLab) management it also offers Wiki and Issue tracking.

Log in

Students and teachers that have an active faculty account can log in using LDAP authentication using the following URL:

https://gitlab.fi.muni.cz/

Enter your faculty login and password, the account will be created automatically unless it already exists. The Dashboard page should appear.

Users without the FI account have should contact system administrators and ask for an external account. To log in use Standard authentication.

SSH key access

In order to be able to checkout, pull or push to repositories without password authentication, you can set up a public SSH key. You can follow these instructions or the following short version:

Key creation

Open a terminal and enter the following commands:

mkdir -p ~/.ssh && cd ~/.ssh
ssh-keygen -t rsa -b 4096 -f id_gitlab -C "key description"

The latter command usually asks for a passphrase, skip it by pressing Enter as you would be asked for this passphrase each time you try to pull or push. The program will create two files, id_gitlab.pub (public key) and id_gitlab (private key). Keep your private key safe.

Adding the key to GitLab

From the left panel on the Dashboard navigate to Profile settingsSSH Keys. Paste contents of the public key into the Key text field. The Title field should be filled automatically, but it case it is still empty, enter some short description. Then click Add key.

New repository

The project can be created from the Dashboard or from the project list. In both cases, click on the New Project button in the upper left part of the page. Then fill the following information:

  1. Project path (dropdown menu): if you are a Master member of some group, you can choose the group's namespace here
  2. Project path (text field): this will appear in the URL, so use project-name with hyphens instead of spaces
  3. Description: optional, can contain Markdown formatting
  4. project accessibility, choose one:
    1. Private: only you and project members can access to project
    2. Internal: all authenticated people can see the project, but project membership is needed to push
    3. Public: accessible even without authentication, project membership still needed to push
  5. click Create Project

Clone and first commit

After project creation you should be redirected to the project's main page. Below the name there should be project URL for git, either HTTPS or SSH.

In your terminal type the following commands:

# without SSH key
git clone https://gitlab.fi.muni.cz/path/repository.git

# with SSH key
eval $(ssh-agent -s)
ssh-add ~/.ssh/id_gitlab
git clone git@gitlab.fi.muni.cz:path/repository.git

The repository folder should appear. Now try to create README.md file in it:

cd repository
cat > README.md <<EOF
# Project README

This file can contain //Markdown// **formatting**.
See also: [manual](http://doc.gitlab.com/ce/markdown/markdown.html).
EOF

A new or modified file has to be staged for commit. Then it can be committed and pushed:

git add README.md           # stage README.md for commit
git commit -m "MESSAGE"     # if you omit -m "MESSAGE", an editor should appear
git push

Refresh the project's page and you should see the README.md file with its content displayed below the project description. Modify the content from GitLab: FilesREADME.mdEdit (on the right). Add some text below and click Commit Changes. Navigate back to the project's page (Project link on the left side) and you should see that README.md has changed.

You can update your local repository with git pull command.

Repository sharing

In case that you want other people to be able to access and contribute to your project, you need to grant them a membership.

  1. from project's main page navigate to Members,
  2. to the People field enter user names,
  3. select Project Access for these users; short description:
    1. Guest can create Issues or add comments
    2. Reporter can pull the project from repository
    3. Developer can push to non-protected branches of the project
    4. Master can manage project members and change project settings
    5. Owner can move or delete the project
    See manual for a complete list of permission for each role. We advise against granting Master or Owner role to anyone unless you are sure you know what you are doing.

If you want people without FI account to access private or internal project without the ability to push or use other features (issues, wiki etc), you can set up Deploy keys for them. Otherwise an external account is needed.

Migrating a repository

It is possible to import a repository from other sources (e.g. GitHub)

Git repository

The easiest way to migrate a simple Git repository (without issues, milestones etc.) is the following:

  1. New Project
  2. enter Project path
  3. from the Import project from list select Any repo by URL
  4. to the Git repository URL field enter the source project URL
    1. if the repository is password protected, you need to embed the username and password into the URL protocol://LOGIN:PASSWORD@example.com/path/to/reporsitory
    2. if LOGIN or PASSWORD contains characters that cannot be used in URL, encode them using URL encoding, e.g.. the space will become %20

GitLab Wiki

GitLab stores Wiki pages as another Git repository, so it is possible to transfer it via Git:

  1. create or import the project
  2. log into the GitLab instance you want to import Wiki from
  3. navigate to the project's Wiki
  4. click Git Access on the top panel
  5. in Clone Your Wiki there are commands needed to clone the wiki; paste them in your terminal
    git clone https://gitlab.nekde.jinde.com/cesta/projekt.wiki.git
    cd projekt.wiki
  6. log into gitlab.fi.muni.cz
  7. from the project navigate to WikiGit Access
  8. copy the URL after git clone command
  9. from your terminal run the following command:
    git push URL

Importing other features (Issues, Milestones...)

There is no officially supported way to migrate Issues nor Milestones. However, it should be possible to use the third-party tool gitlab-copy.

Groups

Some groups are automatically synchronized between Faculty Administration and GitLab. If you become a member of such a group, GitLab will send you an e-mail.

Note that group creation feature is disabled for regular users as custom groups could cause conflicts when synchronizing groups from Faculry Administration. If you want to create a new group (synchronized or not), please contact GitLab administrators.

Instructions for group owners

If a group in Faculty administration does not have a designated administrator, please specify at least one in the synchronization request. Next, specify the default permission for groups members (see permissions). Recommended permissions are Reporter for subject groups with students and Developer for others (labs, teachers). The permissions can be adjusted manually in GitLab.

Note that group permissions apply to group projects as well. For instance, if You grant Master permission to some members, they will be able to create new projects, but they will also be able to add other GitLab users to existing projects or modify project settings.

Regaring the Owner permission, it can only be granted in groups that do not have a designated administrator in Faculty administration. Though GitLab will not prevent the change, the synchronization will replace the Owner permission with the default one.

Group members are added automatically if they have an account after the synchronization (usually in an hour). If a person loses the membership in the Faculty administration group, it will be removed from the corresponding GitLab group as well. This is also true for members added manually.

Group settings

If you are an owner of a synchronized group, GitLab will allow you to change its settings. You are allowed to change the name and description, but do not change the path. It is not (yet) possible to disable this feature in GitLab, but the change can cause conflicts with synchronization of other groups.

By default, synchronized groups are created with the Private visibility. This can be adjusted to Internal or Public in SettingsGroup Visibility.


Rules of usage

  • it is forbidden to change one's display name
  • it is forbidden to change group paths
  • repositories are not suited for large files
  • quota for each repository is 1,5 GB
    (the size may be decreased by ProjectSettingsHousekeeping)
  • keep general rules (Czech only) in mind when using GitLab

References and tutorials

Responsible contact: unix(atsign)fi(dot)muni(dot)cz