Newer
Older
This page offers you some introductory information on how to use JLU GitLab, but it cannot replace the [official user help](https://gitlab.ub.uni-giessen.de/help/user/index.md).
For specific information about JLU GitLab, see [information](Information.md).
[[_TOC_]]
## Important concepts

Christian Krippes
committed
Git and GitLab are versatile tools using many technical concepts and terms.
As both are developed and created in English-speaking environments, these concepts and terms have been only partially translated into other languages.
To keep the following list of helpful information (e.g. regarding read and write permissions) short and comprehensible, the essential terms are explained in plain English.
This is only a well-intended overview; [further help](#further-help) provides a collection of links for you to familiarize yourself with these concepts.

Christian Krippes
committed
- [*Git*](https://en.wikipedia.org/wiki/Git) is a software for version-controlling files.
- A *repository* is a collection of files, which depicts edits of those files as a history of snapshots.
Using Git, you can manage as many separate repositories as you want.
- A *commit* is a snapshot of the data in the repository.
When you create a commit, the configured email address, name, date, time and a random comment become inseparably connected with the file contents of the new snapshot.
This is a fundamental security feature of Git to prevent future changes of this snapshot.
[Read here](#settings_privacy) how to change these potentially private settings.

Christian Krippes
committed
- A *branch* is a subset of snapshots that has been given an arbitrary name, and which helps to keep a repository neat and tidy.
- The Git commands `pull` and `push` can synchronize branches of Git repositories across devices (such as your own computer and JLU GitLab).

Christian Krippes
committed
As soon as two branches are synchronized, both of them contain a copy of all data, i.e. the full history of snapshots.
### GitLab terminology
- A *project* on (JLU) GitLab nearly always contains a Git-Repository, and offers many additional functions for its management.
In addition, GitLab offers multiple systems to automatically execute source code within the project, e.g. to run tests or to generate a website (like this one).

Christian Krippes
committed
- Every project is assigned to the *namespace* of an individual user or a group of users.
All users have their own namespace for their personal projects.
Likewise, all user groups have their own namespace for group projects.

Christian Krippes
committed
Your read and write permissions for a project depend indirectly on its namespace:
For projects within the namespace of other users, your permissions depend on the [project's visibility](#visibility-of-projects) and, if you are a project member, [your role in the project](#project_roles).
For group projects, the permissions depend further on the [group's visibility](#visibility-of-groups) and, for group members, on [their role in the group](#group_roles).

Christian Krippes
committed
<!-- NOTE, unnecessary?: - Using a *merge request* you can ask to merge one or multiple commits from one Git repository into another one. -->
## How to use GitLab?
- TODO: Using the browser is sufficient for many small issues, but for more serious work you should install Git locally.
- TODO: Many of the most common scientific softwares such as MATLAB, RStudio, etc. have integration with Git.
Please note that access from the Internet is restricted to HTTPS; access via SSH is only possible [via VPN](https://www.uni-giessen.de/fbz/svc/hrz/svc/netz/campus/vpn/).
## How to register an account?
To create an account for JLU GitLab, an existing JLU account (g-, s-, n-, or j-) is required.
Please refer to [this page](https://www.uni-giessen.de/faculties/svc/it/index_html/userid/useraccounts?set_language=en) for information on JLU accounts.
If you have a JLU account, your account for JLU GitLab will be registered upon your first login, if you agree to the [Terms of Use](TermsOfUse.md).
To login, go to https://gitlab.ub.uni-giessen.de/ and enter your [JLU user ID](https://www.uni-giessen.de/faculties/svc/it/index_html/userid) (g-, s-, n-, or j- account) into the field **JLU (g-/s-/n-/j-) Username** and your corresponding, personal password into the field **Password**.
Upon your first login, you will be prompted with the [Terms of Use](TermsOfUse.md) ([in German](../de/Nutzungsbedingungen.md)); your account be registered only after you agree to it.

TODO: Rough overview, links to good resources for learning more ([see further help below](#further-help)).
- You can choose another language at [Einstellungen > Profil > Einstellungen > Lokalisierung](https://gitlab.ub.uni-giessen.de/profile/preferences#localization). But as GitLab uses many untranslatable terms, there might still be many English terms, despite different language settings.
TODO: Link to guided Tour within GitLab (or is this just an EE feature?).
<!-- TODO, see issue #35 in admin repo; Insert: "Now might be a good time to consider changing your username, if you want to"? -->
## Visibility of projects

Christian Krippes
committed
Every project has a visibility setting as either *private*, *internal*, or *public*.
The visibility can only be changed by the *Owner* of the project (see [user roles below](#user-roles-in-projects)).
- Projects with *private* visibility are only visible to the [members of the project](#user-roles-in-projects).
For group projects, this includes the [group members](#user-roles-in-groups), depending on their role.
- Projects with *internal* visibility are visible to anyone with a user account who is logged in.
[Please read here](Information.md#who-may-use-jlu-gitlab) which people are included.
- Projects with *public* visibility are visible for people without a user account who can access JLU GitLab.
[Please read here](Information.md#who-may-access-jlu-gitlab) which people are included.
For more details, please refer to the [official documentation](https://gitlab.ub.uni-giessen.de/help/public_access/public_access.md#public-access).
## User roles in projects

Christian Krippes
committed
When adding project members you have to assign them to a designated role:
You can pick either *Guest*, *Reporter*, *Developer*, *Maintainer* or *Owner*.
Each role entails an increasing set of permissions, see also the [official documentation](https://gitlab.ub.uni-giessen.de/help/user/permissions.md#project-members-permissions).
For projects within the namespace of a group, the group members will get the respective [group role](#user-roles-in-groups); e.g. a *Guest* in the group will also be a *Guest* in all group projects, unless that is overwritten by individual project roles.
<!-- NOTE: Let's below exclude the permissions from subscription plans STARTER, PREMIUM, ULTIMATE that are not part of the Community Edition. -->
### Permissions as *Guest*

Christian Krippes
committed
The *Guest* role is for non-active members who can only read some content, and open and comment on tickets.
Project members with the *Guest* role can
download the project,
leave comments,
view and pull project files,
view wiki pages,
create new issues,
see related issues,
create confidential issues,
and view self-created confidential issues.
If *Public pipelines* is enabled in *Project Settings > CI/CD*, they can also
see a list of jobs,
see a job log,
and download and browse job artifacts.
### Permissions as *Reporter*

Christian Krippes
committed
The *Reporter* role is for those members who get more insights and who work with the issue tracker.
In addition to those of the *Guest* role, project members assigned to the *Reporter* role have the following permissions:
*Reporters* can assign and
label issues,
lock issue threads,
and manage the issue tracker and labels.
*Reporters* can also create code snippets,
see a commit status,

Christian Krippes
committed
see the container registry,
see environments,
see a list of merge requests,
view project statistics,
and view the Error Tracking list.

Christian Krippes
committed
<!-- NOTE: The error tracking list is part of Operations (de:"Vorgänge"), and you have to connect to a Sentry server. -->
### Permissions as *Developer*

Christian Krippes
committed
The *Developer* role is for members who actively contribute, and have access to everything throughout the entire project process, unless something has been explicitly restricted (e.g. by branch protection).
In addition to those of a *Reporter* role, project members assigned to the *Developer* role have the following permissions:

Christian Krippes
committed
In the Git-repository, *Developers* can create new branches,
and `push` to, or remove non-read-only branches.

Christian Krippes
committed
They can create new merge requests,
manage/accept,
assign and label existing ones,
and lock merge request threads.
They can create new environments and stop them.
Additionally, *Developers* can cancel and retry jobs,

Christian Krippes
committed
and create or update a commit status.
They can update a container registry, or

Christian Krippes
committed
delete an image from the container registry.
They can create/edit/delete project milestones and add tags in the issue tracker.
They can apply code change suggestions,
create and edit wiki pages, and
rewrite/remove Git tags.
### Permissions as *Maintainer*
The *Maintainer* role is for members who manage a project and its members.

Christian Krippes
committed
In addition to those of the *Developer* role, project members assigned to the *Maintainer* role have the following permissions:
*Maintainers* can add new project members,
use environment terminals,

Christian Krippes
committed
enable/disable branch write protection,
`push` to protected branches,
turn on/off write-protected branch push for *Developers*,

Christian Krippes
committed
enable/disable tag write protections.
*Maintainers* can edit the project settings,
add deploy keys to the project,
and configure project hooks.

Christian Krippes
committed
They can manage runners,
If GitLab Pages is activated, they can manage and delete them,
and manage their domains and certificates,
They can manage clusters,
edit comments posted by any user,
manage Error Tracking,
and delete wiki pages.
<!-- "view project Audit Events": Not available in CE... -->
### Permissions as *Owner*

Christian Krippes
committed
Users assigned to the *Owner* role control all aspects of a project, including its removal.
In personal projects (within the namespace of a user), that user exclusively has the *Owner* role.
In group projects (within the namespace of a group), multiple *Owners* may exist, if multiple group members are *Owners* as their [group role](#group_roles).
Project members with the *Owner* role get the following permissions in addition to the *Maintainer* role:

Christian Krippes
committed
*Owners* can change the [visibility](#project_visibility) of the project,
transfer the project into another namespace,
remove the project,
delete issues,
and disable notification emails.

Christian Krippes
committed
Note that according to the [terms of service of JLU GitLab](TermsOfService.md), all *Owners* are held responsible for the content of their projects, even if it originates from other users.
All users can create *groups* to organize multiple projects and people.

Christian Krippes
committed
Note that the [data you contribute to a group project will not be deleted](Information.md#what-happens-to-my-data-when-my-account-is-deleted) when you [leave the university](Information.md#what-happens-when-i-leave-jlu) or [delete your account](#how-to-delete-my-account), as long as the group has at least one member remaining.

Christian Krippes
committed
The access rights to a project within the namespace of a group depend on the group's [visibility](#group_visibility) and [user roles](#group_roles).
Additionally, individual users from outside of the group can be added as members to individual group projects.
### Visibility of groups
Like the [visibility of projects](#visibility-of-projects), the visibility of a group can be set to 1) *private*, 2) *internal*, or 3) *public* to allow access to 1) explicitly selected users, 2) all logged-in users, or 3) any person, including those without a user account.
[Please read here](Information.md#who-may-use-jlu-gitlab) what the visibility levels *internal* and *public* mean in the case of JLU GitLab.

Christian Krippes
committed
### User roles within groups

Christian Krippes
committed
If you add users as group members, you also have to assign them a designated role:
As with [roles for project members](#user-roles-in-projects), you can pick either *Guest*, *Reporter*, *Developer*, *Maintainer* or *Owner*.
The group role of a member determines the permissions of the equivalent [project role](#user-roles-in-projects) for all group projects.
In addition, the project role of a member can be adapted individually for each project.
Each group role entails an increasing set of permissions within the group, see also the [official documentation](https://gitlab.ub.uni-giessen.de/help/user/permissions.md#group-members-permissions):
<!-- NOTE: Let's below exclude the permissions from subscription plans STARTER, PREMIUM, ULTIMATE that are not part of the Community Edition. -->

Christian Krippes
committed
*Guests* can only browse the group, but not change anything.
*Reporters* can additionally manage group labels.

Christian Krippes
committed
*Developers* can additionally create projects within the group,
and they can create/edit/delete group milestones.
*Maintainers* can additionally create sub-groups.
*Owners* can additionally edit the group settings,
manage group members,
remove the group,
view group Audit Events,
and disable notification emails.

Christian Krippes
committed
Note that according to the [terms of use for JLU GitLab](TermsOfUse.md), all *Owners* are held responsible for the content of their projects, even if it originates from other users.
## Settings concerning private information
TODO: Describe setting of commit name and email address (in GitLab and locally), hiding of activity and profile, changing username?, ...

Christian Krippes
committed
Before you [leave the university](Information.md#what-happens-when-i-leave-jlu) or [delete your account](Information.md#what-happens-to-my-data-when-my-account-is-deleted), you may consider some options to keep your data, or to hand it over to other users. This is because if your account gets deleted, all your personal projects will be deleted as well.

Christian Krippes
committed
For example, you may want to synchronize all important Git repositories from JLU GitLab to your computer to prevent data loss.

Christian Krippes
committed
So as not to delete a personal project within your own namespace, you can transfer it into the namespace of another user or of a group.
This has to be coordinated with the new *Owners*.

Christian Krippes
committed
You can also export projects; this will allow you to migrate (nearly) all related data to another GitLab instance.
Unlike merely synchronizing Git repositories, this will include issues, wikis, etc.
## How to delete my account?
You can delete your account at any time by navigating to [*Settings > Account > Delete account*](https://gitlab.ub.uni-giessen.de/profile/account) in your browser and confirming with your password.

Christian Krippes
committed
Before you delete your account, please read this [overview on what data will be deleted](Information.md#what-happens-to-my-data-when-my-account-is-deleted);
just a few [last steps](#last-steps) can spare you future trouble.

Christian Krippes
committed
Note that you cannot immediately delete your account if you are the only *Owner* within a group.
In this case, you have to assign the *Owner* role to at least one other member, or delete the group in question (e.g. if you are the only remaining member).

Christian Krippes
committed
TODO: More useful links, maybe sorted into categories. GitLab itself has a bunch more.
- [The official user help for JLU GitLab](https://gitlab.ub.uni-giessen.de/help/user/index.md).
- [Free online book *Pro Git*](https://git-scm.com/book/)